2. API设计治理基础：RESTful与GraphQL设计原则，错误码规范，响应体结构标准化

在错误处理移植适配之前，必须建立统一的API设计治理基线。RESTful与GraphQL作为当前最主流的两种API范式，其设计原则、错误码规范与响应体结构直接影响错误信息的传递效率与可移植性。本章将系统梳理这两大范式的核心治理要素，为后续事务边界中的错误处理适配奠定基础。

2.1 RESTful设计原则与错误处理基线

RESTful API以资源为中心，通过HTTP动词表达操作意图。其错误处理的核心原则是：利用HTTP状态码表达语义，利用响应体传递细节。

2.1.1 HTTP状态码分层使用规范

2.1.2 RESTful响应体标准化结构

标准化的响应体结构是错误处理可移植的前提。推荐采用信封模式(Envelope Pattern)，将数据与元数据分离：

// 成功响应
{
  "code": 0,
  "message": "success",
  "data": {
    "id": "usr_12345",
    "name": "张三",
    "email": "zhangsan@example.com"
  },
  "requestId": "req_abc123",
  "timestamp": 1712563200000
}

// 错误响应
{
  "code": 40001,
  "message": "参数校验失败",
  "data": null,
  "errors": [
    {
      "field": "email",
      "rule": "email_format",
      "message": "邮箱格式不正确"
    },
    {
      "field": "age",
      "rule": "range",
      "message": "年龄必须在18-120之间"
    }
  ],
  "requestId": "req_def456",
  "timestamp": 1712563201000
}

2.2 GraphQL设计原则与错误处理差异

GraphQL采用单一端点、按需查询的模式，其错误处理机制与RESTful存在显著差异。GraphQL规范要求：无论请求是否部分失败，始终返回200状态码，错误信息嵌入响应体的errors数组中。

2.2.1 GraphQL响应体结构

{
  "data": {
    "user": {
      "id": "usr_12345",
      "name": "张三",
      "orders": null
    }
  },
  "errors": [
    {
      "message": "无法获取用户订单列表",
      "locations": [{"line": 6, "column": 5}],
      "path": ["user", "orders"],
      "extensions": {
        "code": "ORDER_FETCH_ERROR",
        "service": "order-service",
        "timestamp": "2024-04-08T10:00:01Z"
      }
    }
  ]
}

2.3 统一错误码规范设计

错误码是跨范式移植适配的核心桥梁。无论采用RESTful还是GraphQL，错误码必须遵循统一的编码规则，确保在事务边界中能够被正确识别与转换。

2.3.1 错误码分层编码规则

2.3.2 错误类别定义表

2.4 响应体结构标准化对比

在事务边界中，RESTful与GraphQL的响应体结构需要统一抽象。下表展示了两者在关键维度上的对比及适配策略：

2.5 范式适配架构图

在API治理层面，需要构建一个错误处理适配层，将RESTful与GraphQL的错误输出统一为内部标准格式，确保事务边界中的错误处理逻辑与前端范式解耦。

2.6 治理基线检查清单

在进入事务边界错误处理移植适配之前，请确保以下治理基线已落实：