接口与协议

信源网关的接口按请求头、请求体、返回体和错误体四部分约定。请求只携带路由与鉴权所需字段,业务字段由调用方与信源约定,网关不解释业务含义,也不改写请求内容。调用方按字段约定组织请求,即可在不同信源之间切换。

约定原则

接口设计遵循三个原则:必要字段最小化、错误信息可定位、版本变化可预期。请求头承担身份、凭据、路由和版本信息,请求体只放业务字段,网关读取请求头完成判断,不解析业务内容。

调用方按请求头组织调用,不必关心网关内部模块如何排列,也不必为不同信源改写业务代码。

字段命名和含义在接入时固定,后续新增字段保持向后兼容。调用方不需要按信源分别适配请求结构,减少重复开发。

请求结构

请求头中的字段各有明确用途,缺少关键字段时请求在入口或鉴权环节即被拒绝。

请求编号同时用于幂等判断和审计关联,调用方应在发起请求时生成并保存。协议版本影响字段解释方式,跨版本调用需要按对应版本组织请求头。

部分字段说明
请求头调用方标识已登记的主体或系统标识
请求头凭据网关签发的调用凭据
请求头路由键目标信源或能力标识
请求头请求编号调用方生成的唯一编号
请求头协议版本调用方使用的接口版本
请求体业务字段由调用方与信源约定

返回与错误

成功返回包含请求编号、信源标识、状态和业务响应。失败返回错误码、错误说明和请求编号,不返回信源业务正文。

错误说明用于快速判断处理方向,不包含信源内部细节。需要进一步定位时,凭请求编号查询审计记录,比反复重试更有效。

错误类型说明处理方式
请求格式错误字段缺失或格式不符修正请求后重新提交
凭据无效凭据过期或被停用更新凭据
无权限调用方不在授权范围调整授权范围
无可用信源路由条件没有匹配结果核对路由键和信源状态
信源超时信源在规定时间内未返回按业务规则处理,不重复切换
信源错误信源返回可识别错误保留信源响应并记录

版本与幂等

接口按版本号管理字段增减。新增字段保持向后兼容;删除字段或改变含义时提升主版本号。

相同请求编号在有效期内只处理一次。调用方超时后使用同一编号重试,避免重复写入审计记录。

有效期的长度按业务约定设置,调用方应在约定范围内完成重试。超过有效期后同一编号不再视为重复请求,需要重新发起。

对接建议

对接阶段把字段、凭据和错误处理约定清楚,后续运行会顺畅很多。

对接完成后保留一份字段与错误码对照,便于运行阶段快速查阅。

  • 先用小范围调用验证请求头字段和凭据配置。
  • 请求编号由调用方生成并保持唯一,超时重试沿用同一编号。
  • 协议版本按调用方实际情况选择,避免跨版本混用字段。
  • 错误码按类型处理,不对同一请求反复重试。

查看转发规则

了解路由条件与路径选择方式,评估调用分布。

查看转发