第2章 参数配置总览：核心参数分类、必填与选填标识、参数值格式约定

适用场景

• 首次接入支付SDK时，需要系统性地了解所有可配置参数。
• 迁移或升级SDK版本时，对比旧版参数是否被弃用或新增。
• 排查初始化失败或支付异常时，认定问题是否落在参数遗漏或格式错误区域。
• 团队内多人协作配置时，统一对必填/选填项的理解。

前置条件

• 已获取当前SDK版本的参数配置清单（通常位于集成文档附录或配置文件模板中）。
• 已明确接入环境（测试/预发布/生产）对应的商户号、AppID、等基础凭据。
• 确定SDK运行平台的参数输入方式：JSON / 属性文件 / 代码初始化块。

操作步骤

1. 阅读参数总览表（见下方表格），熟悉五大核心分类的边界。
2. 标记必填项：将表中必填列标注为M的参数逐条列出，优先完成配置。
3. 确认选填项的影响：对于必填列为O的参数，了解其默认值及省略后的行为变化。
4. 解析值格式：按照格式约定列的要求（如字符串长度、数字范围、日期格式、枚举关键字），准备合法值。
5. 组装参数对象：按SDK要求的嵌套结构（通常是JSON键值对）填入参数并校验。

输入输出物

责任边界

• 后端开发者：负责商户参数、安全参数、接口参数的实际填写与签名运算。
• 前端或客户端开发者：负责回调参数、业务参数的配置（如支付结果通知URL）。
• 技术负责人/架构师：负责审核参数总览表，确认是否满足安全规范与业务需求。
• 测试人员：根据必填和格式约定编写参数校验用例，验证配置完全性。

记录材料

• 《项目参数配置审查表》（包含每项参数的值、来源、审批人、配置日期）
• 参数配置的Git提交记录或版本标记
• 初始化日志截图（成功加载参数后的SDK日志输出）

异常处理

验收标准

• 所有必填参数（表内M）均已赋值且通过SDK初始化校验。
• 选填参数至少按业务需求或推荐默认值配置，无未预见行为。
• 参数值格式严格遵循表格中格式约定：如日期为yyyy-MM-dd HH:mm:ss，金额单位为分（整数），签名类型为RSA2或HMAC-SHA256。
• SDK初始化日志无ERROR或WARN级别的参数相关告警。

核心参数分类总览

下表覆盖支付SDK常见的五个参数域。标记M（Mandatory）为必填，O（Optional）为选填。所有示例以JSON形式呈现。

参数配置JSON示例（完整结构）

{
  "appId": "wx2025abcdef123456",
  "mchId": "1491234567",
  "apiSecret": "dGhpcyBpcyBhIHNlY3JldA==",
  "signType": "RSA2",
  "gatewayUrl": "https://api.pay.example.com/v3",
  "timeout": 30,
  "notifyUrl": "https://yourdomain.com/pay/notify",
  "returnUrl": "https://yourdomain.com/order/result",
  "outTradeNo": "ORD20250315001",
  "totalAmount": 100,
  "currency": "CNY",
  "subject": "示例商品描述"
}

# 假设 SDK 提供 validateConfig 方法
校验结果 = sdk.validateConfig(configObject)
if 校验结果.hasErrors():
    打印 校验结果.errorList
else:
    输出 "参数配置通过"