后端如何设计开放平台 API 给第三方调用

开放平台 API 的设计重点不是"多写几个接口"，而是把鉴权、限流、版本、错误码、审计这五件事当成一个对外的产品来做。内部 API 的默认假设是"调用方可信、会跟着一起升级"，开放平台 API 的默认假设必须反过来：调用方不可信、网络不可控、老版本客户端可能三五年都不升级。

开放平台 API 和内部 API 到底有什么区别？

结论：内部 API 优化的是开发效率，开放平台 API 优化的是契约稳定性，后者的每一次不兼容变更都会直接导致第三方线上故障。

具体差异有三点。第一，鉴权从"内网 + 网关白名单"变成"公网 + 应用身份 + 签名"，必须在应用层再校验一次。第二，升级节奏不再同步，第三方不会因为你发了 v2 就改造代码，所以同一接口的多版本要长期并存。第三，调用方行为不可预测，单个 AppKey 可能突发把 QPS 打到几万，所以限流不是可选项，是准入前提。

落到工程上就是一句话：先定契约（接口签名、错误码、限流规则），再写实现，契约一旦公布就只做加法。

第三方调用怎么鉴权？AppKey 签名还是 OAuth2？

结论：服务端对服务端（M2M）的调用用 AppKey + AppSecret + HMAC-SHA256 签名；需要"代用户操作数据"的场景用 OAuth2 授权码模式拿 access_token。

签名校验的具体步骤：调用方收集业务参数，加上 appkey、timestamp（秒级 Unix 时间戳）、nonce（16 位随机字符串），排除 sign 字段后按参数名 ASCII 升序拼成 k1=v1&k2=v2，用 AppSecret 做 HMAC-SHA256 并转十六进制大写，作为 sign 一起发送。

服务端要校验三件事：时间戳与服务器当前时间偏差不超过 300 秒；nonce 在 Redis 中以 5 分钟 TTL 做去重；签名比对用常量时间比较，防止时序攻击。AppSecret 只允许存放在调用方服务端，绝不能下发到 App、小程序或前端 JS。

如果走 OAuth2，建议 access_token 有效期设为 7200 秒，refresh_token 30 天，并且 scope 按业务能力细分（如 order.read、order.write），避免一个 token 拿到全部权限。

限流和配额怎么定才合理？

结论：按 AppKey 维度做三层限流——单接口 QPS、应用总 QPS、日调用量配额，三层任一触发即拒绝。

实现上推荐令牌桶或滑动窗口，用 Redis + Lua 脚本保证原子性。示例档位：免费应用 10 QPS / 1000 次每日，企业应用 100 QPS / 10 万次每日，可按商务合同单独配置。超限时返回 HTTP 429，响应头带上 X-RateLimit-Limit、X-RateLimit-Remaining、X-RateLimit-Reset，让调用方能自己做退避重试。

注意点：限流维度要能区分"读接口"和"写接口"，写接口通常要单独收紧；同时要留一个"熔断开关"，某个 AppKey 明显异常（比如成功率跌破 50%）时能一键封禁，而不是等它把整个网关拖垮。

版本管理怎么做才不会把老用户搞崩？

结论：版本号放在 URL 路径里，形如 /openapi/v1/order/create，不要藏在 Header 或查询参数里。

原因是路径版本对日志、网关路由、监控聚合、文档生成都最友好，排查问题时一眼能看出走的是哪版。

兼容规则要写死在文档里：**新增字段是兼容的，删除字段、修改字段类型、收紧取值范围、改变默认行为都是不兼容的**。大版本之间必须并存，旧版本至少保留 12 个月，下线前提前 6 个月发公告，并给调用方提供"近 30 天该 AppKey 是否仍在调用旧版本"的可见数据，避免误伤。

错误码和幂等要怎么设计？

结论：错误码必须分段、可检索、且响应中一定带 request_id；所有写接口必须支持幂等键。

推荐响应结构：{ "code": 40001, "message": "invalid signature", "request_id": "a1b2c3d4", "detail": {...} }。错误码分段建议：0 表示成功；400xx 是调用方错误（40001 签名错误、40002 参数缺失、40003 权限不足）；429xx 是限流（42901 超出 QPS）；500xx 是服务方错误。HTTP 状态码与业务 code 要同时正确，不要所有错误都返回 200。

幂等方面，写接口要求调用方传 client_request_id，服务端用唯一索引或 Redis SETNX 保证同一个键在 24 小时内只被真正处理一次，重复请求直接返回首次结果。这对支付、下单、退款类接口是硬要求。

文档、沙箱、SDK 要投入多少？

结论：开放平台大约一半的工作量在代码之外，文档、沙箱、SDK、控制台缺一不可。

沙箱环境要有独立域名和独立数据，AppKey 与生产环境完全隔离；接口描述文件用 OpenAPI 3.0 维护，文档自动生成；至少提供 Java、Python、Go、Node 四种语言的 SDK，把签名、重试、限流退避都封装掉——调用方少写一行签名代码，线上就少一批"签名错误"工单。控制台要能让第三方自助完成：申请应用、查看配额、查询调用日志、按 request_id 定位问题。

上线之后还要盯什么？

结论：开放平台上线不是终点，审计与可观测才是长期成本。

关键动作有三条：调用审计日志（含 AppKey、接口、入参摘要、耗时、结果码）保留 180 天，便于纠纷追溯；按 AppKey 维度监控成功率与 P99 延迟，掉点时能第一时间定位到具体调用方；所有变更走"公告 → 新旧双跑 → 下线"三步，不做静默修改。做到这几点，第三方接入的工单量会明显下降，平台也才具备持续扩容的基础。