良好的接口定义规范

• 接口定义

restful风格，类的路径固定，有自己唯一的前缀； 方法路径纯名词，通过请求方式表示语义是查询还是添加，多个单词用短横线连接。增加版本号管理。定义的时候做好参数校验。如果用对象接受，禁止请求对象在多个方法公用，不需要的参数不允许定义在对象里。且请求参数字段尽量与表对象字段保持一致。
示例：

@Api(tags="用户相关接口")
@RestController
@RequestMapping("/api/user/v1")
@Validated
public class Demo{

@ApiOperation(value="根据用户名查询用户信息")
@GetMapping(value="/user-info")
public List<UserDto> getUserInfo(@RequestParam(value="name") @NotEmpty String name){
}

@ApiOperation(value="添加用户信息")
@PostMapping(value="/user-info")
public void addUserInfo(@RequestBody @Valid UserForm.Add userForm){
}

@ApiOperation(value="修改用户信息")
@PutMapping(value="/user-info/{id}")
public void updateUserInfo(@RequestBody @Valid UserForm.Update userForm){
}
}

public class UserForm{
  public static class Add{
  @NotEmpty
  private String name;
  private Integer age;
  ...
}
 public static class Update{
  @NotEmpty
  private Long id;
  private Integer age;
  ...
}
}

• 请求方式

请求方式尽量做到符合语义，
查询GetMapping
新增PostMapping
修改PutMapping
删除DeleteMapping

• 接口返回

接口返回对象统一

public class Result<T>{
private Integer code;
private String mgs;
private T data;
...
}

返回的对象统一封装成xxxDto对象，需要什么返回什么，禁止直接返回表实体类。

• 返回码处理

  定义统一的返回码格式

public enum CodeEnum{
  SUCCESS(000000, "请求成功")，
  ERROR(999999, "系统异常")，

//业务返回码
E1100001(1100001, "用户不存在")，
E1100002(1100002, "没有添加权限")，

//参数校验
E710001(710001, "入参校验失败")，

//调用其他服务失败
E810001(810001, "调用用户服务失败")，

//系统异常
E910001(910001, "数据库异常")
}

• 异常处理

加上全局的异常处理，定义几种主要的业务异常，可以在全局处理处统一捕获，并返回对应的返回码。

• 方法定义

  前缀最好统一，不要add，insert，get，query等混用，
  可以统一如下：
  查询getxxx
  列表查询getxxxList
  添加addxxx
  修改updatexxx
  删除deletexxx