码掌柜 开发文档
版本 V2.0.0 · 2026年6月
版本历史
- 全面重构文档模板
- 新增接口文档模块
- 优化部署流程说明
- 新增微信支付接口
- 修复签名验证问题
- 更新SDK版本
- 新增QQ钱包支付
- 优化异步通知机制
- 完善错误码说明
- 初始版本发布
- 支持支付宝支付
- 基础API接口
引言
编写目的
本文档旨在为码掌柜支付系统的开发团队提供完整的技术参考和开发指南，涵盖系统架构、接口规范、开发流程及部署方案等核心内容，确保团队成员能够快速理解系统设计并高效参与开发工作。
项目背景
码掌柜支付系统是一套高效、安全、稳定的聚合支付解决方案，支持支付宝、微信支付、QQ钱包等多种支付方式的统一接入，为商户提供便捷的支付对接体验。
术语定义
| 术语 | 说明 |
|---|---|
商户ID (pid) | 系统分配给商户的唯一标识符 |
签名 (sign) | 用于验证请求合法性的加密字符串 |
异步通知 (notify_url) | 支付完成后服务器主动推送支付结果 |
同步跳转 (return_url) | 支付完成后页面跳转回商户网站 |
商户订单号 (out_trade_no) | 商户系统内部的订单编号 |
平台订单号 (trade_no) | 支付平台生成的订单编号 |
功能说明
码掌柜支付系统提供完整的解决方案，包含以下核心功能模块：
页面跳转支付
用户通过页面跳转完成支付流程，适用于PC端和移动端H5场景
API接口支付
服务端直接调用接口获取支付二维码或链接，适用于扫码支付场景
订单查询
支持按商户订单号或系统订单号查询订单状态和详情
异步通知
支付完成后自动向商户服务器推送支付结果，确保交易状态同步
签名验证
采用MD5签名算法确保请求和通知的合法性，防止数据篡改
错误处理
完善的错误码体系和异常处理机制，便于问题定位和排查
业务流程
1商户发起请求
→
2签名验证
→
3创建订单
→
4用户支付
→
5异步通知
→
6商户确认
技术架构
系统架构
客户端（浏览器 / 移动端）
Nginx 反向代理 / 负载均衡
支付网关服务
订单管理服务
MySQL 主从
Redis 缓存
技术栈
模块依赖
| 模块 | 职责 | 依赖 |
|---|---|---|
| 支付网关 | 处理支付请求，路由至对应支付渠道 | 订单模块, 签名模块 |
| 订单管理 | 订单创建、查询、状态更新 | 数据库, 缓存 |
| 签名验证 | 请求签名生成与校验 | 商户配置 |
| 异步通知 | 支付结果推送与重试 | 订单模块, 签名模块 |
开发规范
编码规范
缩进统一使用2个空格缩进，禁止使用Tab
命名变量使用camelCase，类名使用PascalCase，常量使用UPPER_SNAKE_CASE
注释公共方法必须添加JSDoc注释，复杂逻辑需添加行内注释
类型TypeScript严格模式，禁止使用any类型
Git 工作流
main生产分支develop开发分支feature/*功能分支hotfix/*热修复分支代码审查
- 所有代码合并前必须经过至少一位团队成员审查
- 审查重点：逻辑正确性、安全性、性能、代码风格
- 使用Pull Request进行代码审查，确保CI通过后方可合并
- 关键模块（支付、签名）需由技术负责人二次审查
接口文档
所有接口均使用 UTF-8 编码，签名算法与支付宝签名算法相同。点击接口可展开查看详细参数说明。
POST
/submit.php页面跳转支付接口，商户通过此接口发起支付请求，用户完成支付后跳转回商户页面。
请求参数
| 参数名 | 类型 | 必填 | 示例值 | 描述 |
|---|---|---|---|---|
pid | Int | 必填 | 1000 | 商户ID |
type | String | 必填 | alipay | 支付方式：alipay/qqpay/wxpay |
out_trade_no | String | 必填 | 20160806151343349 | 商户订单号 |
notify_url | String | 必填 | https://example.com/notify | 服务器异步通知地址 |
return_url | String | 必填 | https://example.com/return | 页面跳转通知地址 |
name | String | 必填 | 商品A | 商品名称 |
money | String | 必填 | 1.00 | 商品金额 |
sign | String | 必填 | 202cb962ac59075b964b07152d234b70 | 签名字符串 |
sign_type | String | 必填 | MD5 | 签名类型，默认MD5 |
响应示例
{
"code": 200,
"msg": "成功",
"data": {
"trade_no": "20260601151343349021",
"pay_url": "https://pay.example.com/order/xxx"
}
}POST
/mapi.phpAPI接口支付，适用于服务端直接调用，返回支付二维码或支付链接。
请求参数
| 参数名 | 类型 | 必填 | 示例值 | 描述 |
|---|---|---|---|---|
pid | Int | 必填 | 1000 | 商户ID |
type | String | 必填 | wxpay | 支付方式：alipay/qqpay/wxpay |
out_trade_no | String | 必填 | 20160806151343349 | 商户订单号 |
notify_url | String | 必填 | https://example.com/notify | 服务器异步通知地址 |
return_url | String | 必填 | https://example.com/return | 页面跳转通知地址 |
name | String | 必填 | 商品B | 商品名称 |
money | String | 必填 | 10.00 | 商品金额 |
sign | String | 必填 | 202cb962ac59075b964b07152d234b70 | 签名字符串 |
sign_type | String | 必填 | MD5 | 签名类型，默认MD5 |
响应示例
{
"code": 200,
"msg": "获取成功",
"money": "10.00",
"type": "wxpay",
"qrcode": "wxp://f2f15IaTGck0xvm7...",
"code_url": "Payewm.jpg",
"trade_no": "20260601151343349021",
"out_trade_no": "20160806151343349"
}GET
/notify_url支付结果异步通知，支付完成后系统会向商户设置的notify_url发送通知。
通知参数
| 参数名 | 类型 | 必填 | 示例值 | 描述 |
|---|---|---|---|---|
pid | Int | 必填 | 1000 | 商户ID |
trade_no | String | 必填 | 20260601151343349021 | 平台订单号 |
out_trade_no | String | 必填 | 20160806151343349 | 商户订单号 |
type | String | 必填 | alipay | 支付方式 |
name | String | 必填 | 商品A | 商品名称 |
money | String | 必填 | 1.00 | 商品金额 |
trade_status | String | 必填 | TRADE_SUCCESS | 支付状态，仅TRADE_SUCCESS为成功 |
sign | String | 必填 | 202cb962ac59075b964b07152d234b70 | 签名字符串 |
sign_type | String | 必填 | MD5 | 签名类型 |
POST
/api/findorder单笔订单查询接口，商户可通过此接口查询订单状态。
请求参数
| 参数名 | 类型 | 必填 | 示例值 | 描述 |
|---|---|---|---|---|
order_no | String | 必填 | 20160806151343349 | 需要查询的订单号 |
type | Int | 必填 | 1 | 订单号类型：1=商户订单号，2=系统订单号 |
响应示例
{
"code": 200,
"msg": "获取成功",
"data": {
"id": 1,
"trade_no": "20260601151343349021",
"out_trade_no": "20160806151343349",
"type": "alipay",
"money": "1.00",
"status": "TRADE_SUCCESS",
"addtime": "2026-06-01 15:13:43"
}
}错误码说明
| 错误码 | 说明 |
|---|---|
200 | 请求成功 |
400 | 请求参数错误 |
401 | 商户认证失败 |
403 | 签名验证失败 |
404 | 接口不存在 |
500 | 服务器内部错误 |
1001 | 商户不存在或被禁用 |
1002 | 商户余额不足 |
1003 | 订单号重复 |
1004 | 金额格式错误 |
1005 | 支付方式不支持 |
测试计划
测试策略
单元测试
覆盖核心业务逻辑，目标覆盖率 ≥ 80%
集成测试
验证模块间交互，重点测试支付流程
端到端测试
模拟真实用户场景，验证完整支付链路
测试用例
| 用例编号 | 测试场景 | 预期结果 | 优先级 |
|---|---|---|---|
| TC-001 | 正常支付流程 | 支付成功，收到异步通知 | P0 |
| TC-002 | 签名验证失败 | 返回签名错误提示 | P0 |
| TC-003 | 重复订单号提交 | 返回订单号重复错误 | P1 |
| TC-004 | 金额格式错误 | 返回参数错误提示 | P1 |
| TC-005 | 异步通知重试 | 失败后自动重试3次 | P1 |
| TC-006 | 并发支付请求 | 订单数据一致性 | P2 |
测试环境
环境
测试服务器 (test-api.mzg.com)
数据库
MySQL 8.0 测试库
缓存
Redis 7.0 测试实例
商户测试号
pid: 1000, key: test_key_123
部署指南
环境要求
| 组件 | 最低版本 | 推荐版本 |
|---|---|---|
| Node.js | 16.x | 18.x LTS |
| MySQL | 5.7 | 8.0 |
| Redis | 6.0 | 7.0 |
| Nginx | 1.18 | 1.24 |
| Docker | 20.10 | 24.0 |
部署步骤
1
拉取代码
git clone https://github.com/mzg/server.git && cd server
2
安装依赖
npm install --production
3
配置环境变量
cp .env.example .env && vim .env
4
初始化数据库
npm run db:migrate && npm run db:seed
5
构建项目
npm run build
6
启动服务
npm run start:prod
配置说明
| 配置项 | 说明 | 默认值 |
|---|---|---|
PORT | 服务监听端口 | 3000 |
DB_HOST | 数据库地址 | localhost |
DB_PORT | 数据库端口 | 3306 |
REDIS_HOST | Redis地址 | localhost |
REDIS_PORT | Redis端口 | 6379 |
LOG_LEVEL | 日志级别 | info |
运维监控
健康检查
GET /health
监控面板
Grafana :3001
日志收集
ELK Stack
告警通知
钉钉/企业微信
附录
常见问题 (FAQ)
签名验证总是失败怎么办？
1. 检查商户密钥是否正确；2. 确认参数排序规则（按字母升序）；3. 验证编码方式（UTF-8）；4. 确保 sign_type 与签名算法一致；5. 检查是否遗漏了空值参数。
收不到异步通知怎么办？
1. 确保 notify_url 可从外网访问；2. 检查服务器防火墙设置；3. 确保接口返回了 "success" 字符串；4. 查看系统重试记录；5. 检查 SSL 证书是否有效。
如何进行支付测试？
1. 在开发环境注册测试商户；2. 使用测试密钥进行签名；3. 调用支付接口使用 0.01 元金额测试；4. 验证异步通知是否正常接收；5. 确认订单状态更新正确。
支持哪些支付方式？
目前支持：支付宝（alipay）、微信支付（wxpay）、QQ钱包（qqpay）。后续将陆续接入银联、云闪付等更多支付渠道。