架构与系统设计 / 系统课时

开放接口规范

开放接口规范

企业支付平台的开放接口必须让不同商户以一致方式接入。本课将统一接口路径、HTTP 方法、字段命名、响应结构与版本管理规则,并通过一个完整的下单请求说明如何设计可长期演进、便于排查且不破坏兼容性的 API。

学习目标

  • 能设计统一、可预测的开放接口路径和请求方法
  • 能定义稳定的请求字段、响应结构与错误码
  • 能在不影响存量商户的前提下管理接口版本

统一资源路径

开放接口建议使用固定前缀隔离内部接口,例如 /open-api。路径表达业务资源,不在路径中堆叠动作动词;需要执行特定业务动作时,再使用资源子路径。

text
POST /open-api/v1/payments
GET  /open-api/v1/payments/{merchantOrderNo}
POST /open-api/v1/payments/{merchantOrderNo}/close
POST /open-api/v1/refunds
GET  /open-api/v1/refunds/{merchantRefundNo}

这里将支付单和退款单视为资源。创建资源使用 POST,查询资源使用 GET,关闭支付单属于对既有资源执行动作,因此使用 /close 子路径。路径中的版本号放在开放接口前缀之后,便于网关按版本路由。

开放接口资源与版本路由关系

请求字段规范

字段统一使用小驼峰命名,并尽量表达业务含义。例如商户号使用 merchantNo,商户订单号使用 merchantOrderNo,不要在同一套接口中混用 merchant_no、mchId 和 merchantCode。

金额字段应明确单位。支付接口可使用最小货币单位的整数,例如人民币 10.50 元传 1050,避免浮点数精度问题。时间字段建议使用带时区的 ISO 8601 字符串,或在接口文档中明确毫秒时间戳,不能两种格式混用。

一次完整的统一下单请求如下:

bash
curl -X POST "https://api.example.com/open-api/v1/payments" \
  -H "Content-Type: application/json" \
  -H "X-Merchant-No: M10001" \
  -H "X-Request-Id: req-20260803-0001" \
  -d '{
    "merchantOrderNo": "ORDER202608030001",
    "amount": 1050,
    "currency": "CNY",
    "payMethod": "WECHAT",
    "subject": "会员充值",
    "notifyUrl": "https://merchant.example.com/payment/notify"
  }'

预期结果:

json
{
  "code": "SUCCESS",
  "message": "success",
  "data": {
    "paymentNo": "<ID>",
    "merchantOrderNo": "ORDER202608030001",
    "status": "PENDING"
  },
  "requestId": "req-20260803-0001"
}

paymentNo 由平台生成,实际值会不同。商户订单号由调用方保证唯一;requestId 用于串联接入方、网关和支付服务日志。

统一响应结构

开放接口无论成功或失败,都应返回稳定的顶层结构。推荐保留 code、message、data 和 requestId。其中 code 面向程序判断,message 面向开发者阅读,data 承载业务结果,requestId 用于故障定位。

HTTP 状态码和业务错误码承担不同职责。参数格式错误可返回 400,认证失败返回 401,无权访问返回 403,资源不存在返回 404,平台内部异常返回 500。业务状态则通过 code 进一步区分,例如 ORDER_NOT_FOUND、DUPLICATE_ORDER 或 CHANNEL_UNAVAILABLE。

json
{
  "code": "DUPLICATE_ORDER",
  "message": "merchantOrderNo already exists",
  "data": null,
  "requestId": "req-20260803-0001"
}

该响应表示请求已到达业务系统,但商户订单号重复。调用方不应只根据 HTTP 200 判断成功,而应同时检查业务 code。

幂等与重试边界

支付和退款创建接口必须支持幂等。最常见做法是以“商户号 + 商户订单号”作为唯一业务键。相同业务键重复请求时,平台返回原订单结果;若关键字段与首次请求不一致,则返回明确的冲突错误,不能再次创建新订单。

网络超时并不等于业务失败。调用方应先使用原订单号查询状态,再决定是否重试。服务端也应记录首次请求的关键字段摘要,防止同一订单号被不同金额或币种复用。

版本管理规则

版本升级应优先保持向后兼容。新增可选字段、增加新的枚举值或补充响应字段,通常可以继续留在 v1;删除字段、改变字段含义、修改金额单位或调整签名算法,则应发布 v2。

版本切换需要同时维护文档、网关路由、监控指标和下线计划。旧版本下线前,应统计仍在调用的商户,提供迁移窗口,并对即将废弃的版本返回可识别的告警头或通知,而不是直接中断服务。

常见错误

不要把所有业务动作都设计成 /createPayment、/queryPayment、/closePayment,这种路径难以形成统一资源模型。不要在成功和失败时返回完全不同的 JSON 结构,否则接入方必须编写多套解析逻辑。也不要复用同一个错误码表达多个原因,否则监控和自动重试策略无法准确执行。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

开放接口规范

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通