4. RESTful API 设计原则：资源命名、HTTP 方法语义、状态码使用、版本控制策略

RESTful API 是微服务与前后端分离架构的事实标准。在 Go 与 NestJS 混合架构中，契约压测的起点就是一套稳定、可预测的 API 设计。本章从资源命名、HTTP 方法语义、状态码使用、版本控制四个维度，建立可被压测工具直接验证的 API 契约规范。

4.1 资源命名：名词复数 + 层级路径

REST 的核心是“资源”（Resource），而非“动作”。资源命名应遵循以下规则：

• 使用名词复数：/users、/orders、/products，避免动词如 /getUsers。
• 层级关系用斜杠表达：/users/{id}/orders 表示用户下的订单集合。
• 查询参数用于过滤/排序/分页：/orders?status=paid&page=1&size=20。
• 禁止在路径中使用动词：/users/activate 应改为 PATCH /users/{id}/status。

4.2 HTTP 方法语义：CRUD 映射

每个 HTTP 方法对应一种标准操作语义，压测脚本直接依赖此语义构造请求。下表列出核心方法及其在契约中的行为约束：

4.3 状态码使用：精确表达结果

状态码是契约压测断言的核心依据。错误的状态码选择会导致压测误判。以下是在 Go/NestJS 服务中必须遵守的状态码规范：

• 2xx 成功：
  • 200 OK：GET、PUT、PATCH 成功返回资源。
  • 201 Created：POST 创建成功，响应头应包含 Location。
  • 204 No Content：DELETE 成功，或更新操作无需返回体。
• 4xx 客户端错误：
  • 400 Bad Request：请求体校验失败、参数格式错误。
  • 401 Unauthorized：未提供或无效认证凭证。
  • 403 Forbidden：已认证但无权限。
  • 404 Not Found：资源不存在。
  • 409 Conflict：资源状态冲突（如重复创建、版本冲突）。
  • 422 Unprocessable Entity：业务逻辑校验失败。
• 5xx 服务端错误：
  • 500 Internal Server Error：未捕获异常，压测中应视为严重缺陷。
  • 503 Service Unavailable：限流或熔断触发。

4.4 版本控制策略：路径前缀 vs 请求头

API 版本控制是契约演进的基础。在 Go 与 NestJS 混合部署中，推荐以下两种策略：

4.5 契约示例：Go 与 NestJS 对照

以下展示一个用户资源在 Go（Gin）和 NestJS 中遵循相同契约的实现片段：

// Go (Gin) — 用户资源
r.GET("/api/v1/users/:id", handler.GetUser)      // 200 | 404
r.POST("/api/v1/users", handler.CreateUser)       // 201 | 400 | 409
r.PUT("/api/v1/users/:id", handler.UpdateUser)    // 200 | 400 | 404
r.DELETE("/api/v1/users/:id", handler.DeleteUser) // 204 | 404

// NestJS (TypeScript) — 用户资源
@Controller('api/v1/users')
export class UsersController {
  @Get(':id')           // 200 | 404
  findOne(@Param('id') id: string) {}

  @Post()               // 201 | 400 | 409
  create(@Body() dto: CreateUserDto) {}

  @Put(':id')           // 200 | 400 | 404
  update(@Param('id') id: string, @Body() dto: UpdateUserDto) {}

  @Delete(':id')        // 204 | 404
  remove(@Param('id') id: string) {}
}

4.6 版本演进策略

当 API 需要破坏性变更时，遵循以下步骤保证压测闭环不中断：

1. 新版本路径：创建 /api/v2/users，旧版本 /api/v1/users 继续运行。
2. 双版本压测：压测脚本同时覆盖 v1 和 v2 的关键路径，对比响应时间与错误率。
3. 弃用通知：在 v1 响应头中添加 Deprecation: true 和 Sunset: Sat, 31 Dec 2025 23:59:59 GMT。
4. 下线验证：压测确认 v1 流量归零后，移除路由并更新契约文档。