| id | integrate-an-external-api |
|---|---|
| type | playbook |
| title | 接入外部 API |
| summary | 用类型边界封装第三方 API，并安全处理凭据、超时、重试和确定性测试。 |
| lang | zh-CN |
| content_version | 1 |
| status | reviewed |
| reviewed_on | 2026-09-02 |
- 记录供应商、端点、发送的数据、凭据负责人、成本上限、速率限制和允许的副作用；
- 用小而明确的类型接口封装供应商代码，并验证所有响应；模型输出同样是不可信数据；
- 凭据不得进入源码，日志和错误信息必须脱敏；
- 分别设置连接和响应超时；只对暂时性、幂等操作做有上限的退避重试；
- 使用确定性的假传输测试超时、畸形数据、限流和部分失败，真实联网测试保持显式选择；
- 在受控环境检查成本、延迟、日志和用户可见的降级行为，再开放生产流量。