基础指南

系统集成与接口契约

设计跨系统的数据流、接口、错误处理与一致性边界。

更新于 2026-10-14

本页目录

契约先于联调

接口契约需要约定谁调用、传什么、返回什么、如何鉴权以及失败如何处理。成功响应只是其中一部分。对外契约版本与内部代码版本分别维护，兼容性由消费者实际使用的字段与行为决定。

本文路径为设计示例，本网站并未提供这些在线接口。

{
  "error": {
    "code": "SOURCE_UNAVAILABLE",
    "message": "资料暂不可用，请稍后重试或转人工",
    "retryable": true,
    "trace_id": "trace-demo-101"
  }
}

错误码供程序判断，用户信息便于采取下一步，内部详情留在受控日志。HTTP 401 表示认证缺失或无效，403 表示已认证但无权限；对资源存在性敏感时，可制定统一 404 策略并保持各接口一致。

调用链总时限应大于各必要阶段之和，并为降级留余量。对瞬时失败使用有限重试和退避；参数错误和无权限不重试。写请求在超时后状态未知，先按业务幂等键查结果，不能盲目再次创建。

幂等键与用户、操作类型和请求摘要绑定；同键同请求返回原结果，同键不同内容拒绝。跨系统写入失败需要补偿或人工对账，数据库事务不能跨越所有外部系统。

用桩服务先覆盖成功、限流、超时、重复和畸形响应，再做真实环境验证。消费者契约测试检查必需字段、枚举、空值和错误码。新增必填字段、改变语义与删字段都需要明确版本迁移。

编写契约、错误表、重试矩阵和重复请求用例。参考 OpenAPI 官方规范选择团队工具链支持的明确版本，不盲目使用 latest。下一步进入API 实现。

本页为基础指南；生产操作需结合实际版本、授权环境与审核证据验证。