编写Node.js REST API的10个最佳实践

在本文中，我们将探讨编写高效、可靠的 Node.js REST API 的 10 个最佳实践。Node.js 是一个基于事件驱动的异步 JavaScript 运行时，特别适合构建可扩展的网络应用程序。通过遵循这些实践，您可以提升 API 的性能、可维护性和安全性。

使用 HTTP 方法和 API 路由

在设计 RESTful API 时，合理使用 HTTP 方法（如 POST、PUT、GET、PATCH 和 DELETE）是关键。每种方法对应特定的操作：

• POST：用于创建资源，例如 POST /user。
• PUT：用于更新资源，例如 PUT /user/:id。
• GET：用于检索资源，例如 GET /user/:id。
• DELETE：用于删除资源，例如 DELETE /user/:id。

此外，API 路由应始终使用名词作为资源标识符，而非动词。例如，创建用户的路由应为 POST /user，而非 POST /createUser。

正确使用 HTTP 状态码

在处理请求时，返回正确的 HTTP 状态码可以帮助客户端快速了解请求的结果：

• 2xx：请求成功，例如 200 OK 或 201 Created。
• 4xx：客户端错误，例如 400 Bad Request 或 404 Not Found。
• 5xx：服务器错误，例如 500 Internal Server Error。

在 Express 中，可以通过以下方式设置状态码：

res.status(500).send({ error: '发生了内部服务器错误' });

此外，可以通过 HTTP 头部附加元数据，例如资源的缓存信息或版本信息。

为 Node.js REST API 选择合适的框架

根据项目需求选择适合的框架至关重要。以下是一些常见的框架：

• Express：轻量级且灵活，适合大多数场景。
• Koa：由 Express 团队开发，支持更现代的中间件机制。
• Hapi：专注于配置驱动的开发，适合复杂的企业级应用。

选择框架时，应根据项目的复杂性、团队的技术栈以及性能需求进行权衡。

黑盒测试你的 Node.js REST API

黑盒测试是一种在不了解应用程序内部结构的情况下验证功能的方法。它可以确保 API 的整体行为符合预期，而无需模拟或删除依赖关系。

以下是一个使用 supertest 和 mocha 进行黑盒测试的示例：

const request = require('supertest');
describe('GET /user/:id', function () {
 it('returns a user', function (done) {
 request(app)
 .get('/user/1')
 .set('Accept', 'application/json')
 .expect(200, { id: '1', name: 'John Doe' }, done);
 });
});

在测试中，尽量减少对系统状态的假设。如果需要，可以通过以下方式填充测试数据：

• 使用生产数据的子集。
• 创建专门的测试数据集。

执行基于 JWT 的无状态身份验证

REST API 通常是无状态的，因此身份验证也应无状态。JSON Web Token (JWT) 是一种理想的解决方案。JWT 由以下三部分组成：

1. Header：包含令牌类型和加密算法。
2. Payload：包含用户信息和其他声明。
3. Signature：用于验证令牌的真实性。

以下是一个简单的 JWT 实现示例：

const jwt = require('jsonwebtoken');
const token = jwt.sign({ id: 1, name: 'John Doe' }, 'your-secret-key', { expiresIn: '1h' });

在访问受保护的端点时，客户端需要在 Authorization 头部中提供令牌。

使用有条件请求

有条件请求通过特定的 HTTP 头部（如 If-Modified-Since 和 If-None-Match）来优化资源的传输。例如：

• If-Modified-Since：检查资源是否自上次请求后被修改。
• If-None-Match：通过 ETag 检查资源版本。

以下是一个示例流程：

1. 客户端首次请求资源时，服务器返回资源及其版本信息（如 ETag）。
2. 客户端再次请求时，附带版本信息。如果资源未修改，服务器返回 304 Not Modified，而非完整的资源。

接受速率限制

速率限制用于控制 API 的请求频率，防止滥用。可以通过以下 HTTP 头部告知客户端剩余的请求额度：

• X-Rate-Limit-Limit：允许的最大请求数。
• X-Rate-Limit-Remaining：剩余的请求数。
• X-Rate-Limit-Reset：限制重置的时间。

通过速率限制，可以有效保护 API 的稳定性。

创建正确的 API 文档

清晰的 API 文档能够帮助开发者快速上手并正确使用您的 API。以下工具可以帮助生成文档：

• Swagger：支持 OpenAPI 规范，功能强大。
• Postman：提供 API 文档和测试功能。
• API Blueprint：一种基于 Markdown 的文档格式。

确保文档包含所有端点的详细说明、示例请求和响应。

不要错过 API 的未来

近年来，GraphQL 和 Falcor 等查询语言逐渐流行。它们通过定义类型和字段，提供了更灵活的查询方式。例如，GraphQL 允许客户端仅请求所需的数据，从而避免冗余。

以下是一个简单的 GraphQL 查询示例：

{
 user(id: "1") {
 name
 email
 }
}

相比传统 REST API，这些查询语言在复杂数据场景下具有显著优势。

总结

通过遵循以上 10 个最佳实践，您可以显著提升 Node.js REST API 的质量和用户体验。从合理使用 HTTP 方法到采用现代化的查询语言，每一步都能帮助您构建高效、可维护的 API。如果您有其他建议或问题，欢迎分享！

原文链接: https://blog.risingstack.com/10-best-practices-for-writing-node-js-rest-apis/