3. API 设计基础：RESTful 设计规范、资源建模、HTTP 方法语义、状态码选择

RESTful API 是当前微服务架构中最主流的交互范式。本章从 资源建模、HTTP 方法语义、状态码选择 三个核心维度，结合领域驱动设计中的聚合与实体概念，讲解如何设计出语义清晰、可治理的 API 边界。

3.1 资源建模：从领域实体到 URI 设计

资源是 REST 架构的核心抽象。资源建模的第一步是将领域模型中的聚合根和实体映射为 URI 路径，将值对象或子资源映射为嵌套路径或查询参数。

3.2 HTTP 方法语义与幂等性

每个 HTTP 方法在 RESTful API 中都有明确的语义约定。正确使用方法语义是 API 可治理性的基础，尤其要关注幂等性和安全性。

3.3 状态码选择：精确表达处理结果

状态码是 API 响应语义的重要组成部分。选择正确的状态码可以减少客户端对响应体的依赖，提升调用方对错误类型的快速识别能力。

3.3.1 成功类状态码

3.3.2 客户端错误类状态码

3.3.3 服务端错误类状态码

3.4 响应体结构规范

统一的响应体结构可以降低客户端解析成本。建议为成功响应和错误响应分别定义标准格式。

3.4.1 成功响应结构

{
  "data": { ... },           // 核心资源数据
  "meta": {                  // 元数据（可选）
    "page": 1,
    "pageSize": 20,
    "total": 156
  }
}

3.4.2 错误响应结构

{
  "error": {
    "code": "ORDER_AMOUNT_EXCEEDS_LIMIT",
    "message": "订单金额超出单笔限额",
    "details": {
      "maxAmount": 50000,
      "currentAmount": 65000
    },
    "traceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

3.5 版本管理策略

API 版本管理是治理事务边界的重要环节。推荐使用 URI 路径版本 作为主要版本策略，配合 请求头版本 做细粒度兼容。