在 Web 前端开发中，Node.js 的应用越来越广泛，如何设计好 Node.js 中的 API 是一个开发者需要掌握的技能。
本文主要介绍 Node.js 中 API 设计的最佳实践，内容详细，旨在提供深度学习以及指导意义。同时，本文将结合示例代码供读者参考。
1. 选择合适的 API 类型
在设计 API 时，需要选择合适的 API 类型。根据数据传输方式，常见的 API 类型有：
- RESTful API：常用于数据查询和展示，以HTTP+URI为传输协议。
- GraphQL API：常用于数据写入，具有完全自定义的查询和数据格式。
- WebSocket API: 建立长连接，支持全双工通信。
开发者根据实际需求来选择合适的 API 类型，可根据前后端的沟通协作流程来决定使用哪种 API类型。
2. API 接口设计
在设计 API 接口时，需要注意以下几个方面：
2.1. RESTful API 接口设计
在设计 RESTful API 时，需要注意以下几点：
- URL 设计应该基于资源。例如，
/orders/123中的 “123” 是订单的 ID。 - 使用 HTTP 动词来描述请求行为。例如，GET、POST、PUT、DELETE 来分别表示获取、创建、更新、删除资源。
- 只处理 HTTP 状态码，不返回其他信息。
下面是一个搜索商品的 API 接口示例：
HTTP Method: GET URL: /products?keyword="laptop"&page=1&pageSize=10
2.2. GraphQL API 接口设计
在设计 GraphQL API 时，需要注意以下几点：
- 统一定义查询和变更操作。
- 查询操作应该能够指定需要的字段和关系，以减小网络负载。
- 变更操作应该尽可能细粒度，才能确保易于回滚。
下面是一个搜索商品的 GraphQL API 接口示例：
type Query {
product(name : String!) : Product
}
type Product {
id : ID!
name : String!
}2.3. WebSocket API 接口设计
在设计 WebSocket API 时，需要注意以下几点：
- 建立长连接，并实现心跳机导致长连接的保持。
- 使用自定义通信协议，能够定义自己的请求响应序列。
- 采用二进制协议传输数据，可以加速通信速度。
下面是一个 WebSocket API 的示例代码：
-- -------------------- ---- ------- ----- --------- - -------------- ----- -- - --- --------------------------------- ------------- -------- -- - --------------------- --- ---------------- -------- ------ - ------------------ --- -------------- -------- -- - ----------------------- -- ------ --------- --- -------------- -------- ----- - ------------------------ ------ - - ------------- ---
3. 返回格式设计
在设计 API 返回格式时，需要注意以下几个方面：
3.1. 返回数据格式
在 RESTful API 中，推荐使用 JSON 格式来存储数据，并按照资源描述嵌套组织，以便快速渲染数据。
在 GraphQL API 中，由于查询可以自定义所需字段，因此可以使用 JSON 格式返回数据。
在 WebSocket API 中，可以使用自定义传输协议来定义数据格式，以适应应用程序需要。
3.2. 返回错误格式
在设计 API 返回错误格式时，要采用统一的错误格式，以便于后续代码处理。
下面是一个 RESTful API 返回错误的格式示例：
{
"status": "error",
"error": {
"code": "INVALID_PARAS",
"info": "Please check the params are correctly specified."
}
}3.3. 返回头设计
在设计 API 返回头时，需要符合 HTTP 协议标准，以便于和客户端和服务器的认证、缓存等方面的交互。
下面是一个 RESTful API 返回头的示例：
HTTP/1.1 200 OK Access-Control-Allow-Origin: * Content-Encoding: gzip Content-Type: application/json Cache-Control: max-age=0, must-revalidate, no-cache
总结
本文介绍了在 Node.js 中的API 设计的最佳实践，并提供了三种常见的 API 类型的示例代码。开发者根据实际需求来选择合适的 API 类型，并且需要注意 API 接口、返回格式的设计，以便于开发者处理。
来源：JavaScript中文网 ，转载请注明来源 https://www.javascriptcn.com/post/646dad14968c7c53b0c50ec8