约定原则
接口设计遵循三个原则:必要字段最小化、错误信息可定位、版本变化可预期。请求头承担身份、凭据、路由和版本信息,请求体只放业务字段,网关读取请求头完成判断,不解析业务内容。
调用方按请求头组织调用,不必关心网关内部模块如何排列,也不必为不同信源改写业务代码。
字段命名和含义在接入时固定,后续新增字段保持向后兼容。调用方不需要按信源分别适配请求结构,减少重复开发。
请求结构
请求头中的字段各有明确用途,缺少关键字段时请求在入口或鉴权环节即被拒绝。
请求编号同时用于幂等判断和审计关联,调用方应在发起请求时生成并保存。协议版本影响字段解释方式,跨版本调用需要按对应版本组织请求头。
| 部分 | 字段 | 说明 |
|---|---|---|
| 请求头 | 调用方标识 | 已登记的主体或系统标识 |
| 请求头 | 凭据 | 网关签发的调用凭据 |
| 请求头 | 路由键 | 目标信源或能力标识 |
| 请求头 | 请求编号 | 调用方生成的唯一编号 |
| 请求头 | 协议版本 | 调用方使用的接口版本 |
| 请求体 | 业务字段 | 由调用方与信源约定 |
返回与错误
成功返回包含请求编号、信源标识、状态和业务响应。失败返回错误码、错误说明和请求编号,不返回信源业务正文。
错误说明用于快速判断处理方向,不包含信源内部细节。需要进一步定位时,凭请求编号查询审计记录,比反复重试更有效。
| 错误类型 | 说明 | 处理方式 |
|---|---|---|
| 请求格式错误 | 字段缺失或格式不符 | 修正请求后重新提交 |
| 凭据无效 | 凭据过期或被停用 | 更新凭据 |
| 无权限 | 调用方不在授权范围 | 调整授权范围 |
| 无可用信源 | 路由条件没有匹配结果 | 核对路由键和信源状态 |
| 信源超时 | 信源在规定时间内未返回 | 按业务规则处理,不重复切换 |
| 信源错误 | 信源返回可识别错误 | 保留信源响应并记录 |
版本与幂等
接口按版本号管理字段增减。新增字段保持向后兼容;删除字段或改变含义时提升主版本号。
相同请求编号在有效期内只处理一次。调用方超时后使用同一编号重试,避免重复写入审计记录。
有效期的长度按业务约定设置,调用方应在约定范围内完成重试。超过有效期后同一编号不再视为重复请求,需要重新发起。
对接建议
对接阶段把字段、凭据和错误处理约定清楚,后续运行会顺畅很多。
对接完成后保留一份字段与错误码对照,便于运行阶段快速查阅。
- 先用小范围调用验证请求头字段和凭据配置。
- 请求编号由调用方生成并保持唯一,超时重试沿用同一编号。
- 协议版本按调用方实际情况选择,避免跨版本混用字段。
- 错误码按类型处理,不对同一请求反复重试。