4、错误处理设计原则：面向失败的设计、优雅降级、幂等性、可观测性在API契约中的体现

在缓存一致性治理中，错误处理不是事后补救，而是必须前置到API契约设计阶段的核心能力。本节围绕四个关键原则——面向失败的设计、优雅降级、幂等性和可观测性——展开，阐述它们如何在OpenAPI规范中落地为可执行、可验证的契约规则。

4.1 面向失败的设计：将故障视为常态

分布式系统中，网络抖动、缓存节点宕机、后端超时是常态而非异常。面向失败的设计要求API契约明确声明：每个操作都可能失败，且失败模式是可枚举、可区分的。

4.2 优雅降级：在部分失效时保持可用

优雅降级的核心思想是：当依赖组件不可用时，系统不崩溃，而是返回有意义的降级结果。在缓存一致性场景中，降级策略必须在API契约中显式声明，让调用方知道何时会收到降级数据。

以下是一个OpenAPI契约中显式降级的示例片段：

paths:
  /api/v1/user/{id}/profile:
    get:
      summary: 获取用户资料（支持降级）
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: 正常响应或降级响应
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/UserProfile'
                  degraded:
                    type: boolean
                    description: 是否为降级数据
                    example: false
                  source:
                    type: string
                    enum: [cache, local_cache, database, default]
                    description: 数据来源
        '503':
          description: 所有数据源均不可用
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: ALL_SOURCES_DOWN
                message: "所有数据源均不可用，返回默认值"
                degraded: true
                default_data:
                  name: "未知用户"
                  avatar: "default.png"

4.3 幂等性：保证重复请求不破坏一致性

在缓存一致性治理中，幂等性是指：同一个写操作无论执行一次还是多次，对缓存和数据库的最终状态影响相同。网络重试、消息重复消费是分布式系统的常态，API契约必须显式声明幂等性语义。

4.4 可观测性：让错误可见、可追踪、可分析

可观测性不是事后日志，而是API契约的一部分。每个错误响应都必须包含足够的信息，让调用方和运维人员能够快速定位问题根因。

在OpenAPI契约中，可观测性通过以下三个维度落地：

• 结构化错误响应：统一使用 ErrorResponse Schema，包含 trace_id、span_id、timestamp、code、message、details 字段。
• 链路追踪标识：要求调用方传入 X-Request-ID 或 X-Trace-ID 头部，并在响应中回传，实现端到端追踪。
• 缓存指标暴露：在响应头中增加 X-Cache-Status（HIT/MISS/STALE/DEGRADED），让调用方感知缓存状态。

components:
  schemas:
    ErrorResponse:
      type: object
      required:
        - code
        - message
        - trace_id
        - timestamp
      properties:
        code:
          type: string
          description: 业务错误码，如 CACHE_MISS, VERSION_CONFLICT
        message:
          type: string
          description: 人类可读的错误描述
        trace_id:
          type: string
          description: 全链路追踪ID，用于关联日志
        span_id:
          type: string
          description: 当前服务节点ID
        timestamp:
          type: string
          format: date-time
          description: 错误发生时间
        details:
          type: object
          description: 可选的详细错误信息
          properties:
            cache_key:
              type: string
            expected_version:
              type: string
            actual_version:
              type: string

4.5 四原则在OpenAPI契约中的综合落地

将面向失败的设计、优雅降级、幂等性、可观测性四个原则整合到一份OpenAPI契约中，形成完整的错误处理规范：