一、RestFul开发规范

RESTful（Representational State Transfer）是一种用于设计和开发网络应用程序的架构风格，它强调使用标准HTTP方法和状态码来进行资源的管理和交互。以下是一些常见的RESTful开发规范和最佳实践：

使用合适的HTTP方法： 使用HTTP方法（GET、POST、PUT、DELETE等）来表示对资源的不同操作。GET用于获取资源，POST用于创建资源，PUT用于更新资源，DELETE用于删除资源。
使用清晰的URL结构： URL应该有意义且易于理解。使用资源名词作为URL的一部分，例如 /users、/products 等。避免使用动词，让HTTP方法表示操作类型。
使用HTTP状态码： 使用合适的HTTP状态码来表示请求的结果。例如，200表示成功，201表示资源已创建，400表示客户端请求错误，404表示资源未找到，500表示服务器内部错误等。
版本控制： 在URL中包含版本号，以便在未来进行API的更改时可以进行平滑的迁移。例如 /v1/users。
请求和响应格式： 使用合适的数据格式，如JSON或XML，来进行请求和响应的传输。设置适当的Content-Type和Accept头部。
资源的表示： 资源的表示应该包含完整的信息，包括所有相关的属性。可以使用嵌套的结构来表示资源之间的关系。
使用HTTP缓存： 使用HTTP缓存机制来减少重复请求，提高性能。通过设置适当的缓存头部，如Cache-Control。
使用合适的HTTP方法： 使用合适的HTTP方法来表示对资源的操作，如GET、POST、PUT和DELETE。不要将动作动词放入URL中。
过滤和排序： 通过查询参数来支持资源的过滤、排序和分页。例如，/users?status=active 或 /products?sort=price。

这些规范和最佳实践有助于创建一致、可维护和易于使用的RESTful API。但要根据具体项目和团队的需求来灵活地调整和应用这些规范。

代码定义：

package com.itheima.pojo;

import lombok.AllArgsConstructor;
import lombok.Data;
import lombok.NoArgsConstructor;

@Data
@NoArgsConstructor
@AllArgsConstructor
public class Result {
    private Integer code;//响应码，1 代表成功; 0 代表失败
    private String msg;  //响应信息 描述字符串
    private Object data; //返回的数据

    //增删改 成功响应
    public static Result success(){
        return new Result(1,"success",null);
    }
    //查询 成功响应
    public static Result success(Object data){
        return new Result(1,"success",data);
    }
    //失败响应
    public static Result error(String msg){
        return new Result(0,msg,null);
    }
}

接口文档示例

基本信息

请求路径：/depts

请求方式：GET

接口描述：该接口用于部门列表数据查询

请求参数

无

响应数据

参数格式：application/json

参数说明：

参数名	类型	是否必须	备注
code	number	必须	响应码，1 代表成功，0 代表失败
msg	string	非必须	提示信息
data	object[ ]	非必须	返回的数据
\|- id	number	非必须	id
\|- name	string	非必须	部门名称
\|- createTime	string	非必须	创建时间
\|- updateTime	string	非必须	修改时间

响应数据样例：

{
  "code": 1,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "name": "学工部",
      "createTime": "2022-09-01T23:06:29",
      "updateTime": "2022-09-01T23:06:29"
    },
    {
      "id": 2,
      "name": "教研部",
      "createTime": "2022-09-01T23:06:29",
      "updateTime": "2022-09-01T23:06:29"
    }
  ]
}