rest的后端接口规范

请求方式

使用HTTP的请求方式代表操作资源的动作，定义接口时要根据业务选择适合的请求方式,常见的HTTP请求有5种：

1. GET: 从服务器查询出一个或多个数据
2. PUT： 更新服务器完整资源
3. PATCH: 更新服务器部分资源
4. POST: 新增资源
5. DELETE: 删除资源

请求地址

请求地址就是URL，我们已经用HTTP请求代表操作资源的动作了，所以我们在URL中就不应该出现动作。

假设场景设计一个接口操作公司的部门和员工，下面给出规范的URL的例子：

查询示例

1. 查询所有部门
GET  /department
2. 根据部门编号查询部门信息
GET  /department/{id}
3. 根据部门编号,员工编号查询员工
GET /account/{id}/department/{id}
4. 分页查询部门
GET  /department?currentPage=1&pageSize=10

新增示例

1. 新增部门
POST /department
2. 新增员工
POST /account

更新示例

1. 更新部门除主键的所有信息
PUT  /department
2. 更新部门的名称
PUT /department

删除示例

1. 删除部门
DELETE /department/{id}

1. 删除某部门中名叫狗剩的员工
DELETE /account/{name}/department/{id}

请求参数

新增和更新

前端在调用新增和更新接口时传递的是一个对象，所以当请求参数个数等于1时，可以直接接收此参数，当参数大于1时需要新建一个DTO对象来接收。

方便接口调用方调用，我们要把对象和属性写上详细的swagger注释(该类的作用、该值的作用、格式规则、示例)。

具体示例参考下面代码,节约篇幅省去了getter和setter:

@ApiModel("部门对象")
public class DepartmentDto {
    @ApiModelProperty(value ="部门id、不得超过6位",example = "1")
    private Integer id;
    @ApiModelProperty(value ="部门名称、不得超过10位",example = "市场部")
    private String name;


}

查询和删除

查询和删除不能新建一个对象来接受，所以只能在接口处定义swagger注释(该值的作用、格式规则、示例)，并且描述该接口的作用、错误码的返回、成功的返回;

 @ApiOperation(value = "根据部门id查询部门信息", notes = "根据部门id查询部门信息")
    @GetMapping("/{id}")
    @ApiResponses(value = {@ApiResponse(code = 200, message = "查询成功"),
            @ApiResponse(code = 500, message = "systemError<br>"
                    + "lengthError<br>")})
    @ApiImplicitParam(name = "id",value = "部门id、不得超过6位",example = "1")
    public Result<DepartmentDto> getList(@PathVariable("id") String id){
        //假装查询哈
        return Result.success("查询成功",new DepartmentDto());
    }

响应数据

前后端分离时，我们需要定义统一的返回数据格式，并且对异常也要全局拦截。

统一返回数据对象

统一返回对象应包括以下字段，code：Http状态码、message:错误码、data:返回数据。

• 这三个字段应加上swagger注释;
• 构造方法私有化、新建静态的构建方法以便快速得到;
• 为打印日志方便可以重写toString方法;

@ApiModel("统一返回对象")
public class Result<T> {

    @ApiModelProperty("HTTP 请求状态码")
    private String code;
    @ApiModelProperty("返回的错误码")
    private String message;
    @ApiModelProperty("返回数据")
    private T data;
    private static final String success = HttpStatus.OK.value()+"";
    private static final String fail = HttpStatus.INTERNAL_SERVER_ERROR.value()+"";

    private Result(String code, String message, T t) {
        this.code = code;
        this.message = message;
        this.data = t;
    }

    public static Result success(String message,Object data){
        return new Result(success,message,data);
    }
}

 以上就是极悦小编介绍的"rest的后端接口规范"，希望对大家有帮助，如有疑问，请在线咨询，有专业老师随时为您务。