架构与系统设计 / 系统课时
开放接口规范
开放接口规范
企业支付平台的开放接口必须让不同商户以一致方式接入。本课将统一接口路径、HTTP 方法、字段命名、响应结构与版本管理规则,并通过一个完整的下单请求说明如何设计可长期演进、便于排查且不破坏兼容性的 API。
学习目标
- 能设计统一、可预测的开放接口路径和请求方法
- 能定义稳定的请求字段、响应结构与错误码
- 能在不影响存量商户的前提下管理接口版本
统一资源路径
开放接口建议使用固定前缀隔离内部接口,例如 /open-api。路径表达业务资源,不在路径中堆叠动作动词;需要执行特定业务动作时,再使用资源子路径。
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 字符串,或在接口文档中明确毫秒时间戳,不能两种格式混用。
一次完整的统一下单请求如下:
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"
}'预期结果:
{
"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。
{
"code": "DUPLICATE_ORDER",
"message": "merchantOrderNo already exists",
"data": null,
"requestId": "req-20260803-0001"
}该响应表示请求已到达业务系统,但商户订单号重复。调用方不应只根据 HTTP 200 判断成功,而应同时检查业务 code。
幂等与重试边界
支付和退款创建接口必须支持幂等。最常见做法是以“商户号 + 商户订单号”作为唯一业务键。相同业务键重复请求时,平台返回原订单结果;若关键字段与首次请求不一致,则返回明确的冲突错误,不能再次创建新订单。
网络超时并不等于业务失败。调用方应先使用原订单号查询状态,再决定是否重试。服务端也应记录首次请求的关键字段摘要,防止同一订单号被不同金额或币种复用。
版本管理规则
版本升级应优先保持向后兼容。新增可选字段、增加新的枚举值或补充响应字段,通常可以继续留在 v1;删除字段、改变字段含义、修改金额单位或调整签名算法,则应发布 v2。
版本切换需要同时维护文档、网关路由、监控指标和下线计划。旧版本下线前,应统计仍在调用的商户,提供迁移窗口,并对即将废弃的版本返回可识别的告警头或通知,而不是直接中断服务。
常见错误
不要把所有业务动作都设计成 /createPayment、/queryPayment、/closePayment,这种路径难以形成统一资源模型。不要在成功和失败时返回完全不同的 JSON 结构,否则接入方必须编写多套解析逻辑。也不要复用同一个错误码表达多个原因,否则监控和自动重试策略无法准确执行。