第4章 支付网关URL配置：生产与测试环境地址、超时设置、重试策略参数

4.1 适用场景

本章适用于以下三类典型场景，开发、测试、运维人员需根据所处阶段选择对应配置路径：

• 新接入支付网关：首次对接支付机构，需要同时配置生产环境（Production）和测试环境（Sandbox）的网关URL，并设定基础的超时与重试参数。
• 环境切换/扩容：从测试环境迁移至生产环境，或生产环境网关地址发生变更（如域名升级、机房迁移），需要更新URL并验证连通性。
• 性能调优/SLA整改：现有超时或重试策略导致频繁超时、重复扣款或响应过慢，需要依据业务SLA重新校准参数。

4.2 前置条件

开始配置前，必须完成以下准备工作，缺少任何一项都将导致配置中断或安全风险：

4.3 操作步骤

按照以下 7 个步骤依次执行，每一步完成后请在第 4.6 节“记录材料”中对应的检查项打勾。

1. 获取并校验网关配置参数
   从支付机构官方文档或技术支持处获取最新的生产环境与测试环境 baseUrl。校验参数格式：生产地址必须使用 HTTPS 协议，测试地址通常包含 “sandbox” “test” “staging” 等标识。
   

   # 标准地址格式示例
   生产环境: https://api.paygateway.com/v1
   测试环境: https://sandbox.paygateway.com/v1

2. 选择运行环境并初始化 SDK
   通过环境变量或配置文件传入 PAY_ENV 参数，SDK 根据该参数加载对应的地址模板。严禁在代码中硬编码环境地址。
   

   # 环境变量方式（推荐）
   export PAY_ENV=sandbox
   export PAY_MERCHANT_ID=mch_2024001
   export PAY_=sk_test_xxxxxxxx

3. 配置网关 URL 地址
   将步骤 1 获取的 baseUrl 填入配置项 gateway.baseUrl，并确认路径末尾不携带多余斜杠。生产与测试环境必须使用独立的配置文件或配置命名空间。
   

   {
     "environment": "sandbox",
     "gateway": {
       "baseUrl": "https://sandbox.paygateway.com/v1",
       "apiPath": "/payments"
     }
   }

4. 设置超时参数
   根据网络延迟和接口响应时间填写三项超时值，单位为毫秒。建议初始值：connectTimeout=15000，readTimeout=30000，writeTimeout=15000。
   

   {
     "gateway": {
       "connectTimeout": 15000,
       "readTimeout": 30000,
       "writeTimeout": 15000
     }
   }

5. 配置重试策略
   设置最大重试次数、初始间隔和退避算法。生产环境建议 maxRetries=3，测试环境建议 maxRetries=1 以快速暴露问题。
   

   {
     "retry": {
       "maxRetries": 3,
       "initialInterval": 1000,
       "multiplier": 2.0,
       "maxInterval": 10000,
       "backoffStrategy": "exponential"
     }
   }

6. 执行连通性验证
   使用 SDK 自带的健康检查接口或 curl 命令测试网关是否可达。验证通过后进入下一步，失败则返回步骤 1 排查。
   

   # 使用 curl 验证连通性（测试环境示例）
   curl -v https://sandbox.paygateway.com/v1/health \
     -H "X-Merchant-Id: mch_2024001" \
     -H "X-: sk_test_xxxxxxxx"

7. 固化配置参数
   将验证通过的配置写入配置中心（如 Apollo、Nacos、Consul）或本地配置文件，标注配置版本号和生效时间，触发相关团队知会。

4.4 输入输出物

下表列出配置过程的输入参数与输出成果，两者需在配置完成后归档至项目配置库。

4.5 责任边界

明确各角色在网关URL配置任务中的职责范围，避免出现“无人负责”或“重复负责”的情况。

4.6 记录材料

配置过程中必须记录以下材料，作为后续审计、排障和回滚的依据：

• 环境地址变更记录：包含变更日期、变更原因、旧地址、新地址、审批人。
• 超时参数调整记录：每次修改 connectTimeout / readTimeout / writeTimeout 的取值、依据（如SLA或压测报告）和生效时间。
• 重试策略配置记录：maxRetries、initialInterval、backoffStrategy 的取值，以及幂等性验证结果。
• 连通性测试结果：测试日期、测试环境、请求耗时、HTTP状态码、响应体前200字符。
• 配置版本号与回滚方案：每次固化配置前需在 CHANGELOG 中记录版本号，并标明上一版本的回滚命令或步骤。

# CHANGELOG 配置变更条目示例
## [2024-09-20] v2.3.1 - 生产网关URL迁移
- 变更前: https://legacy.paygateway.com/v1
- 变更后: https://api.paygateway.com/v1
- 超时: connectTimeout 15000 → 20000
- 回滚: 执行 `git revert v2.3.1` 并重新部署配置中心

4.7 异常处理

配置过程中可能遇到以下异常情况，请对照处理：

[DEBUG] [PaySDK] Loaded config - environment: sandbox, baseUrl: https://sandbox.paygateway.com/v1, connectTimeout: 15000

4.8 验收标准

完成配置后，按照以下标准逐项验收，全部通过方可视为本章内容交付完毕：

• URL可达性验收：生产环境和测试环境的 baseUrl 均可通过 HTTPS 返回 HTTP 200 或 401（有身份校验时），且响应时间 ≤ 5s。
• 超时配置验收：使用模拟延迟工具（如 tc qdisc）注入 20s 延迟，SDK 在配置的 connectTimeout 阈值内准确抛出超时异常，且日志记录完整。
• 重试策略验收：向测试网关发送会返回 503 的请求，验证 SDK 按照配置的 maxRetries 和 backoffStrategy 执行重试，且重试间隔符合指数退避曲线。
• 环境隔离验收：生产环境的配置文件中不得出现 sandbox、test、staging 等关键词；测试环境的配置不得引用生产环境的密钥或地址。
• 文档完整性验收：第 4.6 节所列的 5 类记录材料已全部归档，且 CHANGELOG 条目包含回滚方案。
• 回归测试通过：使用支付 SDK 的集成测试套件对配置后的网关发起一笔 1 元小额支付（测试环境），确认完整调用链正常。