Skip to main content

API 设计与架构演进

从简单的增删改查到支撑复杂业务的系统架构，API 的设计范式和后端的整体架构是在不断演进的。

1. RESTful API 最佳实践​

RESTful 是目前最主流的 API 设计风格。它强调将网络上的所有事物都抽象为资源。

核心原则​

  1. URL 代表资源，使用名词的复数形式，不包含动词。
    • ❌ 错误：/api/getUsers, /api/createArticle
    • ✅ 正确：/api/users, /api/articles
  2. 使用 HTTP Method 表示动作。
    • GET：获取资源
    • POST：创建资源
    • PUT：全量更新资源
    • PATCH：局部更新资源
    • DELETE：删除资源
  3. URL 层级表示资源的层级关系。
    • 获取 ID 为 1 的用户的文章列表：GET /api/users/1/articles
  4. 合理使用 HTTP 状态码。
    • 200 OK：请求成功。
    • 201 Created：资源创建成功。
    • 400 Bad Request：客户端参数错误。
    • 401 Unauthorized：未登录或 Token 失效。
    • 403 Forbidden：已登录，但无权限操作。
    • 404 Not Found：资源不存在。
    • 500 Internal Server Error：服务器内部错误。

标准的返回结构​

无论成功还是失败，最好保持一致的 JSON 结构：

{
  "code": 0,          // 业务状态码，0 表示成功，非 0 表示各种业务错误
  "message": "success", // 给人看的提示信息
  "data": {           // 实际的有效载荷
    "id": 1,
    "name": "John"
  }
}

2. GraphQL：RESTful 的替代者？​

RESTful 的一个痛点是过度获取（Over-fetching）或获取不足（Under-fetching）。前端经常为了渲染一个页面，需要调用多个 REST 接口拼接数据，或者一个接口返回了大量前端不需要的字段。

GraphQL 的优势：

  • 前端可以精确指定需要哪些字段，服务器就只返回哪些字段。
  • 单一入口点（通常只有 /graphql 一个接口），一次请求就能获取所有关联数据。
  • 强类型 schema，前后端约定清晰，自带文档。

3. 架构的演进​

全栈开发者在职业生涯中，通常会经历以下架构的变迁：

阶段一：单体架构 (Monolithic)​

所有的业务逻辑（用户、订单、商品）都写在一个 Node.js 项目里，连接同一个数据库。

  • 优点：开发快、部署简单，适合初创项目。
  • 缺点：代码越来越臃肿，牵一发而动全身；扩展性差。

阶段二：BFF 架构 (Backend For Frontend)​

随着前端设备的多样化（Web、App、小程序），后端提供的通用接口很难同时满足各端的特殊 UI 需求。 BFF 层的作用：在前端和底层微服务之间加一层 Node.js 服务器。这个服务器由前端工程师维护，专门负责调用底层服务的接口，进行数据裁剪、聚合、格式化，然后输出给前端。这让前端获得了极大的自主权。

阶段三：微服务架构 (Microservices)​

将庞大的单体应用拆分成一个个独立的服务（如独立的用户服务、订单服务、支付服务）。

  • 各个服务可以独立开发、独立部署、独立扩展。
  • 服务之间通过 HTTP、gRPC 或消息队列（MQ）进行通信。
  • Node.js 非常适合用来编写轻量级的微服务，尤其是 I/O 密集型的网关服务或 BFF 服务。

4. WebSocket 实时通信​

在全栈开发中，如果遇到聊天室、实时大屏、协同文档等需求，传统的 HTTP 请求-响应模型就不适用了，必须掌握 WebSocket。

  • 全双工通信：客户端和服务器建立连接后，双方都可以主动向对方发送数据。
  • Node.js 生态：最流行的是 Socket.IO 库，它封装了 WebSocket 并在不支持的环境下优雅降级为长轮询。
  • 分布式挑战：当 Node.js 服务多实例部署时，WebSocket 也会面临 Session 共享问题。通常需要引入 Redis 的 Pub/Sub 机制，让连接到不同实例的客户端能够互相通信。