1hjz-document/38技术方案/RESTful规范/RESTful规范.md

#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、项目中应用

@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 (数据内容)

返回示例

{
    "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、待补充