良好的接口定义规范

• 接口定义

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

---

补充一点， 代码里尽量不要有很多被注释掉的内容，不要的代码直接删除掉，以后需要的话也可以通过版本管理工具找回的，不要有大段大段的代码，尽量提供语义清晰，职责单一的方法。