API集成检查表

0）快速浏览（谁在做什么）

• 集成所有者已指定
• 电话联系（24 × 7/奴隶。时钟）拼出
• 同意的SLO/SLA和发行支持窗口
• 状态页面和事件渠道（电子邮件/Slack/Webhook）

1）可用性,环境,版本

• 已访问sandbox/staging/production
• API版本确认："/v1"/标题 "X-API-Version"
• Allowlist IP和网络规则配置
• 时钟和TZ：在UTC, NTP同步
• 通过SemVer和版本矩阵验证了SDK/客户端兼容性

2）身份验证和令牌

• 该机制是一致的：OAuth2 Client Credentials/Auth Code+PKCE/API Key/mTLS
• Access Token生命周期和Refresh Token轮换设置
• 对于API Key：秘密显示一次,保存在秘密管理器
• JWKS/JTI/'kid'已检查,包括时钟skew ± 5分钟
• "授权"标题不合理（修订版）

bash curl -sS -H "Authorization: Bearer $TOKEN" https://api. example. com/v1/ping

3）安全和隐私

[] TLS 1.2 +/HSTS，可选mTLS

• PII最小化：我们只发送正确的口罩
• 保留和处置政策（GDPR/DSAR）已记录
• Secret rotation：主动/下一键,滚动计划
• 防盗：kapcha/密钥创建速度/注册限制

4）限制，配额和后缀

• 宣布"X-RateLimit-"/"X-Cota-"标题
• 客户尊重429和"Retry-After"
• Retrai仅适用于5xx/408/429，指数backoff+jitter
• 设定试验/时间限制（例如，≤ 5次试验，≤ 60 c累计）

5）相似性和冲突

• 所有写作操作均随"Idempotency-Key"一起发送（TTL ≥ 24-72小时）
• 重复→冲突409 IDEMP_REPLAY正在处理
• ETag/'If-Match"用于竞争性更新的功能已启用（如果可用）

bash curl -X POST /v1/payments \
-H "Idempotency-Key: pay-<uuid>" \
-d '{"amount":"12. 34","currency":"EUR"}'

6）分割和增量三角洲

• 使用cursor/keyset分区（"next_cursor"，"has_more"）
• 稳定排序'（updated_at、id）'已记录
• 增量卸载：watermark或change token
• 重迭窗口（overlap 1-2 min）和dedup by '（id, version/seq）'

7）错误格式和诊断

• 单一格式"application/problem+json" （RFC 7807）
• 字段支持：'error_code'、'trace_id'、'retriable'、'detail'
• 描述了错误映射和客户端操作（runbook）

json
{
"type":"https://docs. example. com/errors/validation_failed",
"title":"Validation failed",
"status":422,
"error_code":"VAL_001",
"trace_id":"a1b2c3",
"retriable":false
}

8）Webhooks： 握手和重播

• 确认成功-任何2 xx；enqueue后快速ACK

[] Подпись HMAC (`X-Signature: sha256=...`), `X-Webhook-Id`, `X-Retry`

• 撤退政策：backoff+Jitter，最长24-72小时
• DLQ+Replay：可用和验证
• Dedup Storage在接收器、TTL ≥中继窗口

9）可观察性和跟踪性

• 包括客户端/SDK中的OpenTelemetry hooks
• 整个链条上的"trace_id"/"X-Request-ID"相关性

[] Дашборды: `requests_total`, `errors_total{status}`, `latency_p95`, `retry_count`, `429_rate`

• 警报：5xx/429激增，p95上升，成功率下降，webhook脱落

promql rate(http_requests_total{status=~"5.."}[5m]) / rate(http_requests_total[5m])

10）生产力和可持续性

• 连接池,保持活力,在可能的情况下HTTP/2/3
• 并发是有限的（后压）,客户的队列不是"膨胀"
• circuit-breaker/timeout/fallback策略设置
• 负载测试：爆发10 ×，长连接，冷启动

11）数据,货币,时间

• 格式：ISO-8601 UTC,金钱-十进制字符串/小单位,本地独立于环境
• 编码/语言是一致的（例如，消息的"接受语言"，但机器的"error_code"）
• 四舍五入政策/佣金记录在桉

12）核对和报告（重新计算）

• 与基准金额的每日/每小时核对
• 焊接的API/卸载已测试（CSV/JSON，清单/散列）
• 差异-在带有"trace_id"链接的字幕中'

13）合规和法律方面

• 已接受API使用条款（公平使用/出口控制）
• PII/数据持有者-定义了角色和存储区域
• 在事件中包括法律保留/审核操作日志

14）文档和开发门户

• OpenAPI/AsyncAPI是最新的，"复制粘贴"示例是
• SDK （TS/Py/Java/Go/.NET）-版本一致,Cookbook可用
• Try-it playground工作正常,沙键处于活动状态
• 在门户网站上可以看到Changelog/解密/路由图

15）测试： 功能,负面,溷乱

功能性

• CRUD/关键脚本已通过（快乐路径）
• 分离/游标/增量增量

负面

• 401/403/404/409/422/429/5xx和"Retry-After"处理'
• 错误的webhook签名，过期令牌，大身体

溷乱

• Drop 10-30%的事件,reorder,延迟1-10分钟
• 依存关系禁用（PSP/KYC） →正确的后退/错误

16）接收和启动（直播）

• 最终的PRR（制作就绪评论）通过
• 金丝雀包容：10% → 25% → 50% → 100%
• 通过SLO信号自动回滚（错误/潜在性/429）
• 事件联系矩阵和升级路径已发布
• 飞行员后的CAPA backlog形成

17）运营和支持

• 运行手册/花花公子："5xx spike"，"429 storm"，"webhook backlog"，"timeout"
• SLO/Error Budget的定期报告
• 按计划轮换机密和钥匙
• 版本删除/迁移计划已商定（日落日期）

18）工件模板

env-config模板

yaml api:
base_url: https://api. example. com/v1 timeout_ms: 10000 retries: { max: 5, strategy: expo-jitter }
auth:
kind: oauth2 token_url: https://auth. example. com/oauth2/token scopes: [wallet:read, wallet:write]
webhooks:
secret_ref: secret/webhook-hmac parallelism: 10 max_body_kb: 256

Retrae Policy（伪）

json
{"initial":1,"max":60,"factor":2. 0,"jitter":0. 2,"retriable":["5xx","408","429"]}

19）最终签名支票清单"

• 已准备好环境/版本/密钥/allowlist
• Auth/JWT/keys/mTLS配置和测试
• 已实现限额/配额/恢复率/平均水平
• 分离/游标/增量在数据上运行
• Webhooks：签名、重播、DLQ/Replay验证
• "problem+json"、"trace_id"错误粘贴到所有日志中
• Dashbords/Alertes组装，OTel包括
• 通过负载/阴性/混沌测试
• 核对和报告收敛,runbooks正式化
• PRR/金丝雀/滚回计划准备就绪，电话联系人列出

底线

此表单关闭了API集成的技术、操作和合规方面。通过自上而下的项目，自动检查极限，等效性和网络图书，包括可观察性和回滚计划-您的发布将可以预见，在生产中不会出现"惊喜"。