RESTful API 是现代 Web 开发的一个重要组成部分。作为一个完整、灵活、易于扩展的体系结构风格，RESTful API 可以很好地支持分布式系统、云计算和万维网等多种场景下的 Web 服务。
然而，设计 RESTful API 的过程中，我们可能会遇到不少的反模式（anti-patterns）。
本文旨在介绍 RESTful API 设计中的一些常见反模式和如何避免它们，以及如何设计出高效、可维护、易于使用的 RESTful API。
什么是反模式？
反模式是指在软件工程中会导致质量低下、可维护性差、可扩展性差等问题的设计或编程做法。
在 RESTful API 设计中，一些典型的反模式包括：
- URI 参数过多
- 不合理的 HTTP 方法使用
- 返回码不规范
- 不合理的数据格式
- 缺乏版本控制
- 缺乏安全性设计
- 数据库与 API 的紧耦合
下面将详细介绍如何避免这些反模式。
避免 URI 参数过多
URI 是 RESTful API 的核心组成部分之一，是 API 的入口，也是引导用户访问服务的标识。
在 URI 中包含参数是很常见的一种做法。比如以下例子：
/users?role=admin&sort=-name&limit=10&page=1
这个 URI 带有四个参数（role、sort、limit、page），用于筛选、排序、分页等功能。
然而，如果参数过多，会导致接口设计混乱、难以维护，同时也会减慢 API 的性能，因为参数过多可能导致数据库查询等计算任务变得更加复杂。
因此，我们应该尽量避免 URI 中参数过多的情况。如果确实有很多参数需要传递，一种可能的做法是采用 POST 方法，将参数放在请求体中。当然，这种方法需要服务器端也做相应的修改。
合理使用 HTTP 方法
RESTful API 根据不同的业务需求来选择不同的 HTTP 方法，是其设计的重要特征。比如：
- GET 方法用于获取数据，不对服务端资源进行修改；
- POST 方法用于创建资源；
- PUT 方法用于更新或替换资源；
- DELETE 方法用于删除资源。
但是，很多开发者在实际开发中，会把 POST 视为所有操作的通用方法，这是很不合理的。因为 POST 方法没有幂等性，即多次执行该方法不会得到相同的结果。
比如，以下 URI：
/users/123
如果使用 POST 方法来更新用户 ID 为 123 的信息，那么每次更新都会新增一条记录，而不是更新现有的记录。因此，这种方法会导致数据不一致，资源浪费，从而降低系统性能。
正确的做法是应该使用 PUT 方法来更新或替换资源。另外，DELETE 方法也需要谨慎使用，因为一旦执行，数据恢复困难。
返回码规范化
在设计 RESTful API 时，返回码也是一个重要的设计要素。合理的返回码可以方便客户端进行错误处理和决策。
一般来说，HTTP 返回码应该是标准的、规范化的，而不是随意设定的数字。比如：
- 200 OK 表示服务器接收到并处理了请求；
- 201 Created 表示新建资源成功；
- 204 No Content 表示资源更新成功，但不需要返回任何内容；
- 400 Bad Request 表示客户端请求的数据出现了错误；
- 401 Unauthorized 表示未授权访问；
- 404 Not Found 表示请求的资源不存在；
- 500 Internal Server Error 表示服务器出现了内部错误。
除了上述标准返回码之外，也可以定义自己的返回码。但是，建议总体上尽量遵循这些标准码，这样更有利于客户端开发者使用。
合理的数据格式
RESTful API 返回的数据格式是指客户端得到的响应体的数据格式。通常有以下几种：
- XML 格式
- JSON 格式
- HTML 格式
其中，JSON 格式在现代 Web 应用中用得最广泛，因为它轻量、易于解析、支持多种编程语言和框架。
另外，在 API 设计中，应该合理地利用 HTTP 头部和响应体，使 API 更加清晰、易于使用。比如，可以在 HTTP 头部中设定 Content-Type 和 Accept，指定传输和接收数据的类型。同时，在响应体中可以包含各种元数据，比如分页信息、资源链接、状态码等。
版本控制
RESTful API 的版本控制是尤为重要的一个要素，因为它关系到系统的兼容性和稳定性。
一般来说，API 版本控制分为两种常见方式：
- URI 方式，即在 URI 中带上版本号，比如 /v1/users；
- Header 方式，即在 HTTP 头部中带上版本号，比如 Accept-Version: v1。
URI 方式相对简单，但会导致 URIs 变得杂乱、可读性降低；Header 方式相对规范，但需要客户端和服务器的双方都支持。
在实际开发中，应该根据具体情况和团队约定，选择一种合适的方式来进行版本控制并坚持使用。
安全性设计
RESTful API 设计中的另一个重要的要素就是安全性设计。
在安全性设计中，需要考虑以下几方面问题：
- 鉴别和认证
- 访问控制
- 安全传输
- 数据加密
为了实现这些目标，可以实施如下的方法：
- OAuth 2.0 鉴别和认证协议；
- JWT（JSON Web Token）令牌；
- HTTPS 安全传输协议；
- SSL/TLS 数据加密协议。
在设计时，需要对安全问题进行前期评估和风险分析，以确保系统是可靠和可安全的。
解除数据库和 API 的紧耦合
最后一个反模式是数据库和 API 的紧耦合。在程序的初期版本可能没什么关系，但是随着业务量的增大，这种耦合会导致可扩展性和可维护性遭受严重影响，甚至会导致整个系统失控。
为解耦合，我们可以利用数据访问层，将数据库操作封装在一层独立的代码中，API 层只关注业务操作的逻辑，数据访问层则负责对数据库进行具体的操作。
这种分层设计使得程序变得更加易于理解、可扩展和可维护，促进了代码的复用和测试性，同时也更有利于后续的维护和重构。
总结
RESTful API 设计中的反模式，不仅会影响开发效率，而且可能导致程序性能和稳定性问题。因此，我们需要注意这些反模式，避免它们的出现，并积极利用 RESTful API 的特性，设计出更为高效、可靠、易于使用的 API。
在实际开发中，应该深入理解 RESTful API 的设计思想和原则，了解不同的反模式和避免方法，并使这些方法成为我们日常 API 设计的规范。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/64b1f9b548841e9894e51cc2