Restful开发规范以及开发流程

目录

一、RestFul开发规范

二、开发流程

---

一、RestFul开发规范

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

1. 使用合适的HTTP方法： 使用HTTP方法（GET、POST、PUT、DELETE等）来表示对资源的不同操作。GET用于获取资源，POST用于创建资源，PUT用于更新资源，DELETE用于删除资源。

2. 使用清晰的URL结构： URL应该有意义且易于理解。使用资源名词作为URL的一部分，例如 /users、/products 等。避免使用动词，让HTTP方法表示操作类型。

3. 使用HTTP状态码： 使用合适的HTTP状态码来表示请求的结果。例如，200表示成功，201表示资源已创建，400表示客户端请求错误，404表示资源未找到，500表示服务器内部错误等。

4. 版本控制： 在URL中包含版本号，以便在未来进行API的更改时可以进行平滑的迁移。例如 /v1/users。

5. 请求和响应格式： 使用合适的数据格式，如JSON或XML，来进行请求和响应的传输。设置适当的Content-Type和Accept头部。

6. 资源的表示： 资源的表示应该包含完整的信息，包括所有相关的属性。可以使用嵌套的结构来表示资源之间的关系。

7. 使用HTTP缓存： 使用HTTP缓存机制来减少重复请求，提高性能。通过设置适当的缓存头部，如Cache-Control。

8. 使用合适的HTTP方法： 使用合适的HTTP方法来表示对资源的操作，如GET、POST、PUT和DELETE。不要将动作动词放入URL中。

9. 过滤和排序： 通过查询参数来支持资源的过滤、排序和分页。例如，/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"
      }
    ]
  }

二、开发流程

我们在进行功能开发时，都是根据如下流程进行：

1. 查看页面原型明确需求

     根据页面原型和需求，进行表结构设计、编写接口文档。

2. 阅读接口文档

3. 思路分析

4. 功能接口开发

    就是开发后台的业务功能，一个业务功能，我们称为一个接口。

5. 功能接口测试

   功能开发完毕后，先通过Postman进行功能接口测试，测试通过后，再和前端进行联调测试

6. 前后端联调测试

    和前端开发人员开发好的前端工程一起测试