#RESTful 规范

## 1、统一接口规范:

RESTful架构风格规定，数据的元操作，即CRUD(create, read, update和delete,即数据的增删查改)操作，分别对应于HTTP方法：GET用来获取资源，POST用来新建资源（也可以用于更新资源），PUT用来更新资源，DELETE用来删除资源，这样就统一了数据操作的接口，仅通过HTTP方法，就可以完成对数据的所有增删查改工作。

即：

- GET（SELECT）：从服务器取出资源（一项或多项）。
- POST（CREATE）：在服务器新建一个资源。
- PUT（UPDATE）：在服务器更新资源（客户端提供完整资源数据）。
- PATCH（UPDATE）：在服务器更新资源（客户端提供需要修改的资源数据）。
- DELETE（DELETE）：从服务器删除资源。

## 2、项目中应用

```java
@Api(description = "账户管理API")
@RestController
@RequestMapping("/admin/web")
public class AdminAccountController extends AdminWebBaseController {
	private static final Logger LOGGER = LoggerFactory.getLogger(AdminAccountController.class);
	
	@Autowired
	private AdminAccountService adminAccountService;

	@ApiOperation(value = "分页获取账户信息")
	@RequestMapping(value = { "/accountinfo/list" }, method = RequestMethod.GET)
    public JSONObject listAccountInfo(
        @ApiParam(value = "当前页码", required = true) @RequestParam Integer pageNo, 			           @ApiParam(value = "访问次数，前端传入，无需处理", required = true) @RequestParam Integer draw, @ApiParam(value = "每页显示条数，前端传入，无需处理", required = true) @RequestParam Integer pageSize ){
		return adminAccountService.queryForPaging(pageNo, pageSize, "", draw);
	}

	@ApiOperation(value = "删除账号")
	@RequestMapping(value = {"/accountinfo/del"}, method = RequestMethod.POST)
	public ResultTemplate delAccountInfo(@ApiParam(value = "用户id", required = true)
                                         @RequestParam String userId) {
		return adminAccountService.delByUserId(userId);
	}

	@ApiOperation(value = "添加账号")
	@RequestMapping(value = {"/accountinfo/add"},method = RequestMethod.POST)
    public ResultTemplate addAccountInfo(@ApiParam(value = "账户对象", required = true) 											  @RequestBody String accountInfo){
		return adminAccountService.addAccountInfo(accountInfo);
	}

	@ApiOperation("获取客户账户流水信息")
	@GetMapping("/accountinfo/{userId}")
	public JSONObject getAccountListByUserId(
        @ApiParam(value = "用户id", required = true) @PathVariable String userId,
        @ApiParam(value = "访问次数，前端传入，无需处理", required = true)@RequestParam Integer draw,
        @ApiParam(value = "页码") @RequestParam(required = false, defaultValue = "0")int pageNo,
	    @ApiParam(value = "每页条目") @RequestParam(required = false, defaultValue = "10") int pageSize){
		return adminAccountService.getAccountListByUserId(userId, draw, pageNo, pageSize);
	}

}

```

###2.1	API接口调整说明

调整前:

| -API                            | -请求方式 | -说明                |
| ------------------------------- | --------- | -------------------- |
| /admin/web/accountinfo/list     | GET       | 分页获取账户信息     |
| /admin/web/accountinfo/del      | POST      | 删除账号             |
| /admin/web/accountinfo/add      | POST      | 添加账号             |
| /admin/web/accountinfo/{userId} | GET       | 获取客户账户流水信息 |

调整后:

| -API                             | -请求方式 | -说明                |
| -------------------------------- | --------- | -------------------- |
| /admin/web/accountinfos          | GET       | 分页获取账户信息     |
| /admin/web/accountinfos/{userId} | DELETE    | 删除账号             |
| /admin/web/accountinfos          | POST      | 添加账号             |
| /admin/web/accountinfos/{userId} | GET       | 获取客户账户流水信息 |

### 2.2	API 返回数据格式说明

+ #####所有返回数据必须是 JSON 格式


+ ##### *第一级数据必须有且只有code (状态码)，msg (响应信息)，data (数据内容)*

**返回示例**
````json
{
    "code" : 0,
    "msg" : "请求成功",
    "data" : {
        "draw": 1,
        "recordsTotal": 10,
        "recordsFiltered": 10,
        "dataList": [
            {
                "name":"Angelica",
                "age":"Ramos",
                "office":"System Architect",
                "address":"London",
                "date":"9th Oct 09",
                "salary":"$2,875"
            },
            {
                "name":"Ashton",
                "age":"Cox",
                "office":"Technical Author",
                "address":"San Francisco",
                "date":"12th Jan 09",
                "salary":"$4,800"
            },
            ...
        ]
    ｝         
}
}
````
####2.2.1	状态码说明 `(code) `

+ #####*`code` 值必须是数字*

+ #####通用状态码说明

| 状态码 | 响应信息 |
| ------ | -------- |
| 0      | 请求成功 |
| 1      | 请求失败 |

#### 2.2.2	响应信息说明 `(msg)`

+ ##### `msg` 必须只是字符串，不可为 `null`，`undefined` 等类型 

	### 2.2.3	数据内容说明 `(data)`

+ ##### 任何情况下 `data` 只能为 `null` (无数据) 或 `object` (对象) 和 `array` (数组) 类型 

## 3、待补充