使用 Node.js 与 Express.js 进行 API 设计的最佳实践

Source: Dev.to

1. 使用 RESTful 与一致的端点设计

一个设计良好的 API 应该是 可预测的。

✅ 遵循 REST 约定

• 使用 名词 而不是动词，让 HTTP 方法来完成工作。

Bad ❌

POST /createUser
GET /getUsers

Good ✅

POST   /users
GET    /users
GET    /users/:id
PUT    /users/:id
DELETE /users/:id

✅ 保持命名一致

选择一种风格并坚持使用：

• /users/:id/subscriptions
• /fundraisers/:id/payments

一致性提升 可读性、上手速度以及长期维护。

2. 始终为你的 API 设定版本

API 会演进。破坏性更改是不可避免的。

✅ 使用基于 URL 的版本控制

/api/v1/users
/api/v2/users

这可以实现：

• 向后兼容
• 安全的重构
• 并行客户端支持

除非你确信它们永远不会改变（实际上会改变），否则不要发布未设版本的 API。

3. 将路由、控制器和业务逻辑分离

Express.js 最常见的错误之一是 臃肿的控制器。

❌ 避免这样写

app.post("/users", async (req, res) => {
  // validation
  // database logic
  // business rules
  // response formatting
});

✅ 推荐的结构

src/
 ├── routes/
 ├── controllers/
 ├── services/
 ├── models/
 └── middlewares/

示例

// routes/user.routes.js
router.post("/", userController.createUser);

// controllers/user.controller.js
exports.createUser = async (req, res) => {
  const user = await userService.create(req.body);
  res.status(201).json(user);
};

这可以提升：

• 可测试性
• 代码复用
• 可读性

4. 标准化 API 响应

客户端不应猜测你的响应格式。

✅ 推荐的响应结构

{
  "success": true,
  "message": "User created successfully",
  "data": {}
}

❌ 避免随意的响应

{ "user": {} }

{ "result": {} }

一致性提升：

• 前端集成
• 调试
• 文档清晰度

5. 集中处理错误

Do not repeat try‑catch logic everywhere.

✅ 集中错误中间件

app.use((err, req, res, next) => {
  res.status(err.status || 500).json({
    success: false,
    message: err.message || "Internal Server Error"
  });
});

✅ 使用自定义错误类

throw new ApiError(404, "User not found");

这确保了：

• 控制器简洁
• 错误信息有意义
• 正确的 HTTP 状态码

6. 及早验证请求

永远不要信任客户端输入。

✅ 使用验证中间件（Joi / Zod / express‑validator）

body("email").isEmail()

验证：

• 请求体
• 查询参数
• URL 参数

这可以防止：

• 数据库中的无效数据
• 不必要的崩溃
• 安全漏洞

7. 使用正确的 HTTP 状态码

状态码是你的 API 合约的一部分。

正确使用可提升 调试和客户端逻辑。

8. Secure Your API by Default 🔐

✅ Essential security practices

• 使用 helmet 设置 HTTP 头部
• 正确启用 CORS
• 生产环境中绝不暴露堆栈跟踪
• 使用环境变量（dotenv）
• 对敏感端点进行速率限制

app.use(helmet());

安全不是可选项——尤其是对于公共 API。

9. 实现分页、过滤和排序

切勿一次返回成千上万条记录。

✅ 示例

GET /users?page=1&limit=20

好处：

• 响应更快
• 内存使用更低
• 客户端性能更佳

10. 为你的 API 编写文档（认真对待）

未文档化的 API 是 破碎的 API。

✅ 使用 Swagger / OpenAPI

• 让新人快速上手
• 充当活的合同
• 改善协作

你的未来的自己（以及前端团队）会感谢你的。

11. 为关键端点编写测试

你不需要 100 % 的覆盖率——但确实需要信心。

关注：

• 身份验证
• 支付
• Webhook
• 核心业务逻辑

使用以下工具：

• Jest
• Supertest

测试让重构从恐惧转为信心。

结论：为人类而非仅为机器设计 API

优秀的 API 具备：

• 可预测
• 安全
• 一致
• 易于演进

Node.js 和 Express.js 为你提供灵活性——运用这些实践，你的 API 将能够优雅扩展。

灵活性 — 纪律是让 API 可扩展的关键

🚀 最终提示

“如果一个 API 使用起来很困难，那它可能真的很难用。”

以同理心进行设计。带着目标去构建。