4. 闭环接口设计原则：接口幂等性设计、接口版本控制、请求-响应模型、错误码规范

在倒排索引缓存一致性闭环系统中，接口是各组件（索引构建、缓存更新、一致性校验、回源修复）之间通信的契约。设计不当的接口会导致数据不一致、重复更新、版本混乱以及难以排查的故障。本节围绕四个核心原则展开，确保闭环接口在生产环境中具备高可用性与可维护性。

4.1 接口幂等性设计

幂等性（Idempotency）是指无论调用一次还是多次，系统状态保持不变。在分布式缓存一致性场景中，网络抖动、超时重试、消息重复消费是常态，非幂等接口会引发数据覆盖、计数错误或索引重复构建。

4.1.1 幂等实现策略对比

4.1.2 幂等接口设计示例

// 请求体示例：携带幂等键
POST /api/v1/cache/update
{
  "idempotent_key": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "doc_id": "doc_10086",
  "shard_id": 3,
  "content": "更新后的倒排索引数据",
  "version": 42
}

// 服务端处理逻辑（伪代码）
if (existsInIdempotentTable(idempotent_key)) {
    return { "code": 0, "msg": "已处理", "data": previousResult }
}
// 执行实际更新
result = updateCache(doc_id, shard_id, content, version)
saveIdempotentKey(idempotent_key, result)
return { "code": 0, "msg": "成功", "data": result }

4.2 接口版本控制

缓存一致性闭环涉及多个子系统协同升级，接口版本控制是避免兼容性灾难的基石。版本控制策略决定了新旧接口能否平滑过渡。

4.2.1 版本控制策略

• URI路径版本（/v1/、/v2/）： 最直观，适合大版本升级，但URL会变长。
• 请求头版本（Accept-Version: 2.0）： 保持URI整洁，适合内部微服务调用。
• 查询参数版本（?version=2）： 简单但容易被缓存污染，不推荐生产使用。
• 兼容性扩展字段： 在请求体中增加version字段，服务端按版本路由逻辑。

4.2.2 版本兼容性矩阵

4.3 请求-响应模型

统一的请求-响应模型是接口可观测性的基础。闭环接口需要明确区分正常流程、异常流程与边界情况。

4.3.1 统一请求模型

{
  "request_id": "全局唯一请求ID，用于链路追踪",
  "version": "接口版本号，如 2.0",
  "timestamp": 1712345678000,
  "source": "调用方标识，如 index_builder / cache_updater",
  "data": {
    // 业务参数，不同接口不同
  },
  "ext": {
    // 扩展字段，用于灰度、调试、元数据传递
  }
}

4.3.2 统一响应模型

{
  "code": 0,           // 0表示成功，非0表示错误
  "msg": "success",    // 人类可读的消息
  "request_id": "与请求一致，用于追踪",
  "timestamp": 1712345678123,
  "data": {
    // 业务返回数据
  },
  "error_detail": {    // 仅在code非0时返回
    "error_code": "CACHE_UPDATE_FAILED",
    "error_stack": "可选，调试时开启",
    "retryable": true  // 是否可重试
  }
}

4.3.3 请求-响应模型设计原则

• 必填字段最小化： 只要求调用方必须提供核心业务参数，降低接入成本。
• 响应结构固定： 无论成功失败，响应JSON结构保持一致，方便客户端统一解析。
• 链路追踪贯穿： request_id 必须从请求透传到响应，并写入日志，便于排查一致性闭环中的调用链。
• 超时与重试标识： 响应中明确告知调用方是否可重试（retryable字段），避免盲目重试导致雪崩。

4.4 错误码规范

错误码是接口调试与故障定位的第一道防线。混乱的错误码体系会让运维人员在海量日志中迷失方向。

4.4.1 错误码分层结构

采用三段式错误码：模块码(2位) + 场景码(2位) + 具体码(2位)，例如 040201。

4.4.2 错误码使用规范

• 0 永远代表成功： 任何非0值都表示异常，客户端只需判断 code !== 0 即可进入错误处理。
• 错误码不可重复： 每个错误码在全局唯一，避免歧义。
• 错误码与HTTP状态码解耦： 所有请求都返回200 HTTP状态码，错误信息放在响应体中。避免HTTP 500被网关拦截导致无法获取错误详情。
• 错误码文档化： 每个错误码必须在接口文档中列出，并附带触发条件与处理建议。

4.5 闭环接口设计总览

下图展示了倒排索引缓存一致性闭环中，接口幂等性、版本控制、请求-响应模型与错误码规范如何协同工作：

4.6 接口设计检查清单

在完成接口设计后，建议对照以下清单进行自查：

1. 幂等性： 每个写接口是否都定义了幂等键？幂等键的存储与过期策略是否明确？
2. 版本控制： 当前接口版本号是否在请求中显式传递？新旧版本是否同时在线？
3. 请求-响应模型： 请求体是否包含 request_id 和 version？响应体是否包含 code、msg、request_id？
4. 错误码规范： 所有非0错误码是否都在错误码表中注册？错误码是否包含可重试标识？
5. 文档与测试： 接口文档是否包含请求示例、响应示例、错误码列表？是否编写了幂等性测试用例？