项目设计-RESTful API设计_restful api 微服务项目设计-CSDN博客

本文链接：https://blog.csdn.net/m0_37609394/article/details/122413823

1.背景：

只要 HTTP 协议存在，Web 服务就已经存在。但尤其是自云计算出现以来，它们已成为让客户与我们的数据交互的一种非常常见的方式。

我一直在从事涉及构建或使用 API 的项目。

我见过的大多数 API 都声称是“ RESTful ”——即符合 REST 架构的原则和约束。

但是，他们中的一些人一直在给 REST 一个非常非常糟糕的名字。

或者是一些非常糟糕的设计。

还有状态代码的错误使用、纯文本响应、不一致的模式……等。

所以我决定写下我认为在设计 REST API 时的一些好的做法。

2. 免责声明

我不认为以下说法和做法 100% 符合的 REST 原则，但我觉得该方案无限接近REST 原则。

3.基础知识

如果你要构建一个设计良好的REST API，您最好了解HTTP 协议的基础知识。我

MDN web docs 上的Overview of HTTP是一本很好的文档。

HTTP REST 的应用：

HTTP 有动词（或方法）：GET、POST、PUT、PATCH 和 DELETE 是最常见的。
REST 是面向资源的，资源由URI :表示/newspapers/。
一个端点是一个动词和URI，例如组合GET: /articles/。
端点可以解释为对资源的操作。例如，POST: /articles/可能意味着“创建一篇新文章”。
在高层次，动词映射到CRUD操作：GET方法Read，POST手段Create，PUT和PATCH均值Update，和DELETE手段......好吧，Delete。
响应的状态由其状态码指定：1xx信息、2xx成功、3xx重定向、4xx客户端错误和5xx服务器错误。

4.不友好的 API 与友好的 API 示例：

HTTP/1.1 200 OK
Content-Type: text/html

{
    "code":0,
    "message":""
    "data": {
        // 请求的数据
    }
}

HTTP/1.1 200 OK
Content-Type: text/html

{
    "code":-1,
    "message","请求失败！"
    "data": {
        // 请求的数据
    }
}

为什么说改设计，不友好。

1. 首先你需要判断code == 0，在去取data内的值。增加不必要的业务逻辑。

2. 正确的请求和错误的请求混淆，主业务逻辑臃肿，且容易出现bug。

友好的示例

HTTP/1.1 200 OK
Content-Type: application/json

{
  "name":"Chen Yu",
   "age":26,
   "height":172
}


HTTP/1.1 500 Internal Server Error
Content-Type: application/json

{
  "status":500,
  "error":"Internal Server Error"
}

1.正确请求直接返回结果。

2.错误请求时，返回错误的结果，及错误的详情。

3.正确流程线，和错误流程线分开，有助于写出清晰的代码。

客户端请求、解析示例：

    axios({
      method:'get',
      url:'http://localhost:3000/',
      responseType:'stream'
    })
      .then((response)=> {
        //正确的响应
      }).catch((e)=>{
        //错误的响应
      });

该设计与github 同款。

https://api.github.com/