13 个设计 REST API 的最佳实践

清疚 2021-09-07 06:19 334阅读 0赞

## 1. 了解应用于 REST 之上的 HTTP 知识 ##

如果你想要构建设计优良的 **REST API**，了解一些关于 **HTTP 协议**的基础知识是很有帮助的，毕竟磨刀不误砍材工。

在 MDN 上有很多质量不错的[文档][Link 1]介绍 HTTP。但是，就 **REST API 设计**本身而言，所涉及到的 HTTP 知识要点大概包含以下几条：

*  HTTP 中包含**动词**（或方法）： `GET`、`POST`、`PUT`、`PATCH` 还有 `DELETE` 是最常用的。
 *  REST 是**面向资源**的，一个资源被一个 **URI** 所标识，比如 `/articles/`。
 *  **端点（endpoint）**，一般指动词与 URI 的组合，比如 `GET: /articles/`。
 *  一个端点可以被解释为对某种资源进行的某个动作。比如， `POST: /articles` 可能代表“创建一个新的 article”。
 *  在业务领域，我们常常可以将**动词**和 **CRUD**（增删查改）关联起来：`GET` 代表查，`POST`代表增，`PUT` 和 `PATCH` 代表改（注: PUT 通常代表整体更新，而 PATCH 代表局部更新），而 `DELETE` 代表删。

当然了，你可以将 HTTP 协议中所提供的任何东西应用于 REST API 的设计之中，但以上这些是比较基础的，因此时刻将它们记在脑海中是很有必要的。

## 2. 不要返回纯文本 ##

虽然返回 JSON 数据格式的数据不是 REST 架构规范强制限定的，但大多 REST API 都遵循这条准则。

但是，仅仅返回 JSON 数据格式的数据还是不够的，你还需要指定返回 body 的头部，比如 `Content-Type`，它的值必须指定为 `application/json`。这一点对于程序化客户端尤为重要（比如通过 python 的 `requests` 模块来与 api 进行交互）—— 这些程序是否对返回数据进行正确解码取决于这个头部。

注：通常而言，对于浏览器来说，这似乎不是问题，因为浏览器一般都自带内容嗅探机制，但为了保持一致性，还是在响应中设置这个头部比较妥当。

## 3. 避免在 URI 中使用动词 ##

如果你理解了第 1 条最佳实践所传达的意思，那么你现在就会明白**不要**将动词放入 REST API 的 URI 中。这是因为 HTTP 的动词已经足以描述执行于资源的业务逻辑操作了。

举个例子，当你想要提供一个针对某个 article 提供 banner 图片并返回的接口时，可能会实现如下格式的接口：

GET: /articles/:slug/generateBanner/

这里 GET 已经说明了这个接口是在做**读**的操作，因此，可以简化为：

GET: /articles/:slug/banner/

类似的，如果这个端口是要创建一个 article:

// 不要这么做
    POST: /articles/createNewArticle/
    
    // 这才是最佳实践
    POST: /articles/

尝试用 HTTP 的动词来描述所涉及的业务逻辑操作。

## 4. 使用复数的名词来描述资源 ##

一些时候，使用资源的复数形式还是单数形式确实存在一定的困扰，比如使用 `/article/:id/` 更好还是使用 `/articles/:id/` 更好呢？

这里我推荐使用后者。为什么呢？因为复数形式可以满足所有类型端点的需求。

单数形式的 `GET /article/2/` 看起来还是不错的，但是如果是 `GET /article/` 呢？你能够仅通过字面信息来区分这个接口是返回某个 article 还是多个呢？

因此，为了避免有单数命名造成的歧义性，并尽可能的保持一致性，使用复数形式，比如：

GET: /articles/2/
    POST: /articles/
    ...

## 5. 在响应中返回错误详情 ##

当 API 服务器处理错误时，如果能够在返回的 JSON body 中包含错误信息，对于接口调用者来说，会一定程度上帮助他们完成调试。比如对于常见的提交表单，当遇到如下错误信息时：

{ 
        "error": "Invalid payoad.",
        "detail": { 
            "surname": "This field is required."
        }
    }

接口调用者很快就是明白发生错误的原因。

## 6. 小心 status code ##

这一点可能是最重要、最重要、最重要的一点，可能也是这篇文章中，唯一你需要记住的那一点。

你可能知道，HTTP 中你可以返回带有 200 状态码的错误响应，但这是十分糟糕的。不要这么做，你应当返回与返回错误类型相一致的**具有一定含义的状态码**。

聪明的读者可能会说，我按照第 5 点最佳实践来提供足够详细的信息，难道不行吗？当然可以，不过让我讲一个故事：

我曾经使用过一个 API，对于它返回的所有响应的状态码均是 `200 OK`，同时通过响应数据中的 `status` 字段来表示当前的请求是否成功，比如：

{ 
        "status": "success",
        "data": { }
    }

所以，虽然状态码是 `200 OK`，但我却不能绝对确定请求是否成功，事实上，当错误发生时，这个 API 会按如下代码片段返回响应：

HTTP/1.1 200 OK
    Content-Type: text/html
    
    { 
        "status": "failure",
        "data": { 
            "error": "Expected at least two items in list."
        }
    }

头部还是 `text/html`，因为它同时返回了一些 HTML 片段。

正因为这样，我不得不在检查响应状态码正确的同时，还需校验这个具有特殊含义的 `status` 字段的值，才可以放心的处理响应返回的 `data`。

这种设计的一个真正坏处在于，它打破了接口与调用者之间的“信任”，因为你可能会担心这个接口对你撒谎（注：言外之意就是，由于特设的字段可能会改变，因此增加了不可靠性）。

所以，使用正确的状态码，同时仅在响应的 body 中返回错误信息，并设置正确的头部，比如：

HTTP/1.1 400 Bad Request
    Content-Type: application/json
    
    { 
        "error": "Expected at least two items in list."
    }

## 7. 保持 status code 的一致性 ##

当你掌握了正确使用状态码之后，就应该努力使它们具有一致性。

比如，如果一个 POST 类型的端点返回 `201 Created`，那么所有的 POST 端点都应返回同样的状态码。这样做的好处在于，调用者无需在意端点返回的状态码取决于某种特殊条件，也就形成了一致性。如果有特殊情况，请在文档中显著地说明它们。

下面是我推荐的与动词相对应的状态码：

GET: 200 OK
    POST: 201 Created
    PUT: 200 OK
    PATCH: 200 OK
    DELETE: 204 No Content

https://blog.florimondmanca.com/restful-api-design-13-best-practices-to-make-your-users-happy

## 8. 不要嵌套资源 ##

使用 REST API 获取资源数据，通常情况下会直接获取多个或者单个，但当我们需要获取**相关联**的资源时，该怎么做呢？

比如说，我们期望获取作者为某个 author 的 article 列表 —— 假设 authro 的 `id=12`。这里提供两种方案：

第一种方案通过在 URI 中，将嵌套的资源放在所关联的资源后边来进行描述，比如：

GET: /authors/12/articles/

一些人推荐这种方案的理由是，这种形式的 URI 一定程度上描述了 author 与 article 之间的一对多关系。但与此同时，结合第 4 点最佳实践，我们就不太能够分清当前端点返回的数据到底是 author 类型还是 article 类型。

这里有一篇[文章][Link 2]，详细阐述了扁平化形式优于嵌套形式，因此一定有更好的方法，这就是下面的第二种方案：

GET: /articles/?author_id=12

直接将筛选 article 的逻辑抽离为 querystring 即可，这样的 URI 相比之前，更加清晰地描述了“获取所有 author(id=12) 的 article”的意思。

## 9. 优雅地处理尾部斜杠 ##

一个好的 URI 中是否应当包含尾部斜杠，并不具有探讨价值，选择一种更倾向的风格并保持一致性即可，同时当客户端误用尾部斜杠时，提供重定向响应。

我再来讲我自己的一个故事。某天，我在将某个 API 端点集成到项目中，但是我总是收到 `500 Internal Error` 的错误，我调用的端点差不多看起来这样：

POST: /entities
    ```
    调试一段时间之后，我几乎崩溃了，因为我根本不知道我哪里做错了，直到我发现服务器之所以报 500 的错误，是因为我粗心丢掉了尾部斜杠（注：这种经历人人都会遇到，我在 SF 上遇过无数次类似的问题），当我把 URI 改成：

POST: /entities/

之后，一切正常运转。
    
    当然，大多数的 web 框架都针对 URL 是否包含尾部斜杠，进行了优雅地处理并提供定制选项，如果可以的话，找到它并开启这项功能。
    
    ## 10. 使用 querystring 来完成筛选和分页功能
    大部分情况下，一个简单的端点没有办法满足负责业务场景。
    
    你的用户可能想要获取满足一定条件下的某些数据集合 ，同时为了保证性能，仅仅获取这个集合下的一个子集。换言之，这通常叫作**筛选**功能和**分页**功能：
    * 筛选：用户可以提供额外的属性来控制返回的数据集合
    * 分页：获取数据集合的子集，最简单的分页是基于分页个数的分页，它由 `page` 和 `page_size` 来决定
      
    那么问题来了，我们如何将这两项功能与 RESTful API 结合在一起呢？
    
    答案当然是通过 **querystring**。对于分页，很显然使用这种方式再合适不过了，比如：

GET: /articles/?page=1&page\_size=10

但对于筛选，你可能会犯第 8 点最佳实践中所指出的问题，比如获取处于 published 状态的 article 列表：

GET: /articles/published/

除了之前提出的问题外，这里还涉及一个设计上的问题，就是 **published** 本身不是资源，它仅仅是资源的特征，类似这种特征字段，应该将它们放到 querystring 中：

GET: /articles/?published=true&page=2&page\_size=20 \`\`\`更加优雅、清晰，不是吗？

## 11. 分清 401 和 403 ##

当我们遇到 API 中关于安全的错误提示时，很容易混淆这两个不同类型的错误，**认证**和**授权**（比如权限相关）—— 老实讲，我自己也经常搞混。

这里是我自己总结的备忘录，它阐述了我如何在实际情况下，区分它们：

*  用户是否未提供身份验证凭据？认证是否还有效？这种类型的错误一般是未认证（`401 Unauthorized`）。
 *  用户经过了正常的身份验证，但没有访问资源所需的权限？这种一般是未授权（`403 Forbidden`）

## 12. 巧用 202 Accepted ##

我发现 `202 Accepted` 在某些场合是 `201 Created` 的一个非常便捷的替代方案，这个状态码的含义是：

> 服务器已经接受了你的请求，但是到目前为止还未创建新的资源，但一切仍处于正常状态。

我分享两种特别适合使用 `202 Accepted` 状态码的业务场景：

*  如果资源是经过位于将来一系列处理流程之后才创建的，比如当某项作业完成时
 *  如果资源已经存在，但这是理想状态，因此不应该被识别为一个错误时

## 13. 采用 REST API 定制化的框架 ##

作为最后一个最佳实践，让我们来探讨这样一个问题：你如何在 API 的实施中，实践最佳实践呢？

通常的情况是这样的，你想要快速创建一个 API 以便一些服务可以互相访问彼此。Python 开发者可能马上掏出了 Flask，而 JS 开发者也不甘示弱，祭出了 Express，他们会使用实现一些简单的 routes 来处理 HTTP 请求。

但这样做的问题是，通常，web 框架并不是针对构建 REST API 服务而专门存在的，换言之，Flask 和 Express 是两个十分通用的框架，但它们并非特别适合用于构建 REST API 服务。因此，你必须采取额外的步骤来实施 API 中的最佳实践，但大多数情况下，由于懒惰或者时间紧张等因素，意味着你不会投入过多精力在这些方面 —— 然后给你的用户提供了一个古怪的 API 端点。

解决方案十分简单：工欲善其事，必先利其器，掌握并使用正确的工作才是最好的方案。在各种语言中，许多专门用于构建 REST API 服务的新框架已经出现了，它们可以帮助你在不牺牲生产力的情况下，轻松地完成工作，同时遵循最佳实践。在 Python 中，我发现的最好的 API 框架之一是 [Falcon][]。它与 Flask 一样简单，非常高效，十分适合构建 REST API 服务。如果你更喜欢 Django 的话，使用 [Django REST Framework][]就足够了，虽然框架不是那么直观（注：按我的理解应该是说不太容易上手，但是我不这么认为），但功能非常强大。在 NodeJS 中，[Restify][] 似乎也是一个不错的选择，尽管我还没有尝试过。我强烈建议你给这些框架一个机会！它们将帮助你构建规范，优雅且设计良好的 REST API 服务。

## 总结 ##

我们都应致力于让调用 API 这件事成为一种乐趣。希望本文能使你了解到在构建更好的 REST API 服务的过程中，涉及到的一些建议和技巧。对我而言，应该把这些最佳实践归结为三点，分别是良好的语义，简洁和合理性。

[转自：原文地址][Link 3]

[Link 1]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Overview
[Link 2]: https://www.python.org/dev/peps/pep-0020/#id3
[Falcon]: https://falconframework.org/
[Django REST Framework]: http://www.django-rest-framework.org/
[Restify]: http://restify.com/
[Link 3]: https://cloud.tencent.com/developer/article/1579007