2、RESTful API设计：资源建模、HTTP方法语义、状态码设计、版本控制策略、OpenAPI规范

聊到微服务间的通信，RESTful API 绝对是绕不开的话题。我个人习惯把 REST 看作是服务之间的「普通话」——大家都懂，但能不能说利索，就看设计功底了。这一章，咱们就掰开揉碎聊聊怎么把这门「普通话」说地道。

2.1 资源建模：别把API设计成RPC

很多新手容易犯一个错：把 REST API 设计成了远程过程调用。你想想看，/getUserById、/createOrder 这种 URL，看着像不像在调用函数？这其实违背了 REST 的核心思想——资源导向。

资源建模的核心就一句话：用名词表示资源，用 HTTP 方法表示操作。

好的例子：

  • GET /users/{id} — 获取用户资源
  • POST /orders — 创建订单资源
  • DELETE /products/{id} — 删除产品资源

坏的例子：

  • GET /getUser?id=123
  • POST /createOrder
  • POST /deleteProduct

我在项目中遇到过团队把 URL 写成 /api/v1/deleteUser，理由是「前端好理解」。嗯，这里要注意：前端好理解 ≠ 架构好设计。一旦服务多了，这种 RPC 风格的 API 会让维护成本直线上升。

资源建模还有几个关键点：

  • 层级关系用路径表达：比如 GET /users/{userId}/orders 表示某个用户的订单列表
  • 复数名词是惯例：/users 而不是 /user，虽然小细节，但统一很重要
  • 避免过深的嵌套：超过三级嵌套就该考虑是否合理了，比如 /a/b/c/d/e 这种，我建议用查询参数扁平化

我的小技巧：设计资源时，先画一张实体关系图。把服务里的核心实体列出来，再考虑它们之间的关联。资源模型其实就是这张图的「投影」。

2.2 HTTP方法语义：别让POST干所有事

说实话，我见过最离谱的 API 设计，是整个服务只用 POST 和 GET 两个方法。创建用 POST，查询用 GET，更新和删除？统统用 POST 加个 action 参数。这其实是在「用 HTTP 协议的外壳，包着 RPC 的内核」。

HTTP 方法有明确的语义，咱们得尊重它：

方法 语义 幂等性 安全性 典型场景
GET 获取资源 是 是 查询列表、获取详情
POST 创建资源 否 否 新增订单、提交表单
PUT 全量替换 是 否 更新用户全部信息
PATCH 部分更新 否 否 修改用户邮箱
DELETE 删除资源 是 否 删除商品

这里有个容易踩的坑：PUT 和 PATCH 的区别。我曾经在项目中用 PUT 做部分更新，结果客户端漏传字段，直接把用户的其他信息清空了。那次事故之后，我定了个规矩：全量更新用 PUT，部分更新必须用 PATCH。

避坑指南：我曾经接手过一个遗留系统，所有写操作都用 POST，连删除也是 POST /deleteItem。结果幂等性没法保证，重试机制完全不敢开。重构时花了整整两周才改完。所以从一开始就选对方法，后面能省很多事。

2.3 状态码设计：别只返回200和500

你想想看，如果一个 API 永远只返回 200，然后 body 里写 {"code": 1, "msg": "成功"} 或 {"code": -1, "msg": "失败"}，那 HTTP 状态码还有什么意义？

我个人习惯把 HTTP 状态码分成几类来用：

  • 2xx 成功族：
    • 200 OK — GET、PUT、PATCH 成功
    • 201 Created — POST 创建成功，记得返回 Location 头
    • 204 No Content — DELETE 成功，不需要返回 body
  • 4xx 客户端错误族：
    • 400 Bad Request — 参数校验失败
    • 401 Unauthorized — 未认证
    • 403 Forbidden — 已认证但无权限
    • 404 Not Found — 资源不存在
    • 409 Conflict — 资源冲突（比如重复创建）
    • 422 Unprocessable Entity — 语义错误（比如邮箱格式不对）
  • 5xx 服务端错误族：
    • 500 Internal Server Error — 未预期的异常
    • 502 Bad Gateway — 上游服务挂了
    • 503 Service Unavailable — 服务过载或维护中

一个实用的错误响应结构：

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "用户 ID 12345 不存在",
    "details": "请检查用户 ID 是否正确",
    "timestamp": "2024-01-15T10:30:00Z",
    "traceId": "abc-123-def-456"
  }
}

为什么要带 traceId？我在排查线上问题时，经常遇到客户端说「报错了」，但不知道是哪次请求。有了 traceId，直接去日志系统一查，问题定位快得多。

2.4 版本控制策略：别让升级变成灾难

服务一多，API 版本控制就是个躲不开的问题。我见过最粗暴的方式：直接在 URL 里写 /v1/、/v2/，然后老版本直接下线，客户端全部强制升级。结果呢？总有那么几个客户端没来得及升级，线上直接报 404。

常见的版本控制策略有三种：

策略 实现方式 优点 缺点
URL 路径 /api/v1/users 简单直观，容易路由 URL 不够优雅，版本多了难维护
请求头 Accept: application/vnd.myapp.v1+json URL 干净，符合 REST 风格 调试不方便，网关配置复杂
查询参数 /api/users?version=1 实现灵活 容易被忽略，缓存不友好

我个人习惯用 URL 路径 + 请求头兜底 的组合策略。对外暴露的 API 用 /v1/ 路径，方便客户端理解；内部服务间调用则用请求头方式，保持 URL 干净。

我的经验：版本号不要轻易废弃。我一般会同时维护三个版本：当前版本（v2）、上一个版本（v1）、下一个版本（v3 开发中）。v1 标记为 deprecated 后，至少保留 6 个月再下线。给客户端留足迁移时间。

2.5 OpenAPI规范：API的「活文档」

说白了，OpenAPI 就是一份机器可读的 API 说明书。以前我们写 API 文档用 Word、用 Wiki，结果代码改了文档没更新，前端同学拿着过期的文档调接口，调一天都调不通。

OpenAPI 规范（以前叫 Swagger）解决了这个问题：文档即代码，代码即文档。

一个典型的 OpenAPI 定义长这样：

openapi: 3.0.0
info:
  title: 用户服务 API
  version: 1.0.0
paths:
  /users/{userId}:
    get:
      summary: 获取用户详情
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 成功返回用户信息
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '404':
          description: 用户不存在
components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        email:
          type: string

使用 OpenAPI 有几个实实在在的好处：

  • 自动生成客户端 SDK：前端、Android、iOS 都能一键生成调用代码
  • 接口测试自动化：Postman、Insomnia 直接导入，省去手动配置
  • 契约测试：服务提供者和消费者基于同一个规范做验证

避坑指南：我曾经在一个项目里，团队各自写 OpenAPI 文件，结果 A 服务定义的 User 对象有 10 个字段，B 服务引用的 User 只有 5 个字段。联调时才发现字段对不上。后来我们统一用 $ref 引用公共的 schema 文件，才解决了这个问题。

嗯，关于 RESTful API 设计，核心就这些。资源建模是骨架，HTTP 方法是动作，状态码是反馈，版本控制是保障，OpenAPI 是说明书。把这五块做好了，微服务间的通信至少不会出大乱子。

← 上一章 📖 返回目录 下一章 →