external-api-adapters

外部 API 适配器

当代码需要跨越进程或供应商边界时，请使用此技能。

核心规则

• 将外部 API 隔离在适配器之后。领域和用例代码应依赖端口，而不是 SDK 或 HTTP 客户端细节。
• 在边界处将外部 DTO 转换为内部领域／应用类型。
• 将外部错误规范化为少量应用错误。
• 为每次网络调用设置明确的超时时间。
• 明确制定重试行为，确保重试次数有限，并且对操作安全。
• 将关联 ID、请求 ID、供应商 ID 和分页游标作为结构化证据记录。
• 不要将凭据和原始敏感负载写入日志、快照或抛出的消息。

适配器形态

export interface ErpCustomerGateway {
  fetchCustomer(id: CustomerId): Promise<ExternalCustomerResult>;
}

export class HttpErpCustomerAdapter implements ErpCustomerGateway {
  async fetchCustomer(id: CustomerId): Promise<ExternalCustomerResult> {
    // HTTP or SDK details stay here.
  }
}

优先为每项外部能力或有界集成设置一个适配器。避免使用混合无关操作的大型“供应商客户端”类。

边界检查清单

• 输入在离开应用之前经过验证。
• 输出在进入应用之前经过解析和验证。
• 已配置并测试超时时间。
• 已按操作记录重试策略。
• 非幂等调用具有幂等键，或不自动重试。
• 分页和游标具有确定性的停止条件。
• 明确处理限流响应。
• 日志包含操作、外部系统、请求 ID 和安全标识符。
• 适配器已针对成功、验证失败、超时、可重试失败、不可重试失败和格式错误的响应编写测试。

重试指南

仅在操作具有幂等性或设有幂等键时重试。不要重试验证失败、身份验证失败、授权失败或永久性业务规则响应。

针对暂时性网络故障和 5xx 响应，使用次数少且有上限并带抖动的重试。将重复失败作为带类型的应用错误返回。

错误规范化

将供应商特定的详细信息映射为应用错误：

type ExternalServiceError =
  | { kind: "unavailable"; retryAfterMs?: number; requestId?: string }
  | { kind: "unauthorized"; requestId?: string }
  | { kind: "not-found"; requestId?: string }
  | { kind: "invalid-response"; requestId?: string; reason: string };

除非适配器契约明确暴露 SDK 异常名称或原始 HTTP 状态码，否则应用的其余部分不应据此进行分支处理。

测试指南

• 使用精简的测试样例对映射和错误规范化进行单元测试。
• 使用契约测试验证真实或录制的外部响应结构。
• 编写基于行为的假客户端，而不只是仅用于断言的 Mock。
• 为格式错误、不完整和意外响应添加负面测试样例。
• 当运维团队需要时，验证失败路径中的可观测性字段。

常见错误

• 将外部 DTO 原封不动地传递到应用中。
• 重试非幂等操作。
• 用空数组或 undefined 隐藏部分失败。
• 对所有 4xx 或所有 5xx 响应一概而论。
• 在用例或领域代码中到处添加 SDK 导入。