📚 课程目录第1章支付SDK能力概览与接入前的技术评估

1. 支付SDK能力概览与接入前的技术评估

1.1 能力概览

支付SDK是企业对接线上收银、资金结算、分账与退款的核心技术组件。在开始集成之前，必须首先明确SDK的能力边界：它支持哪些支付渠道，提供哪些功能矩阵，以及在什么技术环境下运行。

  核心原则： 不是所有SDK都适合所有场景。选择前应完成能力匹配、依赖检查和选型边界确认，否则后期会因功能缺失或版本冲突导致返工。

1.1.1 支持支付渠道

主流支付SDK通常覆盖以下渠道（以国内通用聚合支付为例）：

支付宝 + 微信支付（必选核心渠道）
银联云闪付 / 银联网关（合规备选）
QQ钱包 / 京东支付 / 百度钱包（辅助渠道，视业务区域）
境外渠道：海外银行卡、PayPal、iDEAL、Sofort（仅针对跨境场景）

1.1.2 功能矩阵

能力域	能力项	说明
支付	扫码支付 / 公众号/小程序支付 / App内支付 / H5支付 / 刷脸支付	支持同步（支付即返回）与异步（回调通知）两种结算模式
退款	全额 / 部分退款，原路退回	需支持重入幂等和退款状态反查
对账	每日交易明细文件下载 / 实时流水同步	用于商户侧财务系统对平
签约	委托代扣 / 免密签约 / 协议支付	用于周期性扣款场景（会员订阅、水电缴费）
风控	交易评分、频次限制、黑名单	可选能力，部分SDK内置基础规则引擎

1.2 技术选型边界

技术选型边界决定了SDK能否在你当前的技术栈中正确编译、运行并保持长期可维护性。常见的边界评估维度包括：

语言 & 运行时版本：Java 8/11/17、PHP 7.4/8.x、Python 3.6+、Go 1.18+、Node.js 14+
通信协议：HTTP/1.1、HTTPS、gRPC、WebSocket（较少见）
数据格式：严格遵循 JSON / XML / Protobuf 其中一种
签名算法：RSA2(SHA256withRSA)、HMAC-SHA256、国密SM2/SM3
线程模型：同步阻塞、异步非阻塞、响应式（Reactive）

常见陷阱： 某些SDK在 Java 11 上强制依赖 Jakarta EE，与旧版 javax 不兼容。务必先执行编译测试，不要只看文档兼容列表。

1.3 环境要求

在接入前必须完成以下环境准备与验证：

环境项	要求	验证命令/检查点
操作系统	Linux (CentOS 7+/Ubuntu 20.04+) / macOS (Monterey+) / Windows Server 2019+	`uname -a` / `cat /etc/os-release`
运行环境	JDK 8u202+ / PHP 8.0+ / Python 3.8+ / Go 1.20+	`java -version` / `php -v` / `python --version`
依赖管理	Maven / Gradle / Composer / go mod / npm	`mvn -v` / `composer --version`
网络	出网权限（HTTPS 443），可访问支付网关域名	`curl -I https://api.pay.example.com`
时间同步	NTP 同步，与支付网关时间偏差 < 300秒	`timedatectl show -p NTPSynchronized`

# 服务端时间同步验证示例
#
# 1. 检查NTP同步状态
timedatectl show -p NTPSynchronized
# 预期输出: NTPSynchronized=yes

# 2. 对比本地时间与标准时间（取差值）
curl -s http://worldtimeapi.org/api/timezone/Etc/UTC | python -c "import sys,json; d=json.load(sys.stdin); print('差:', d['datetime'])"

1.4 接入前评估清单

以下评估应在编码前完成，并记录在项目技术评估文档中：

确定所需支付渠道及其对应的商户号/AppID。
确认商户平台的签名密钥对已配置并启用 RSA2 或 SM2。
准备异步回调域名（必须为 HTTPS，且公网可访问）。
确认开发环境的编译工具链与依赖版本（Maven/Gradle/Composer + JDK/PHP版本）。
确定 SDK 的包名/组织名，并添加到依赖管理文件。
获取沙箱环境的测试密钥与 Mock 回调 URL。
确认支付结果通知的 幂等处理方案（基于通知ID去重）。

1.5 支付SDK集成架构图

下图展示了从商户后端到支付网关的核心交互流程与技术选型边界，在实际集成前应确保每个环节的能力和版本都匹配。

1.6 依赖管理与SDK引入

在完成评估后，即可在项目中添加SDK依赖。以下以Maven（Java）和Composer（PHP）为例：

<!-- Java Maven 依赖示例 （假设SDK groupId: com.pay.sdk） -->
<dependency>
  <groupId>com.pay.sdk</groupId>
  <artifactId>pay-sdk-core</artifactId>
  <version>3.2.5</version>
</dependency>

<!-- 可选：对账/通知模块 -->
<dependency>
  <groupId>com.pay.sdk</groupId>
  <artifactId>pay-sdk-reconciliation</artifactId>
  <version>3.2.5</version>
</dependency>

// PHP Composer 依赖示例
// composer.json 片段
{
  "require": {
    "pay/sdk-core": "^3.2",
    "pay/sdk-notification": "^3.2"
  }
}
// 然后执行: composer install

实践建议： 在沙箱环境先执行一次完整的集成测试，模拟支付创建 → 回调接收 → 结果查询三个原子流程，以验证SDK的入参、签名、回调验签是否全部正确。

1.7 回调验签初始化

SDK初始化时需显式配置回调验签公钥。以下为商户端回调处理器的启动配置示例（Java）：

// 1. 初始化SDK客户端
PayClientConfig config = new PayClientConfig();
config.setAppId("wx2024123456789");
config.setPrivateKey("-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----");
config.setPayPublicKey("-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----");  // 支付网关公钥
config.setNotifyUrl("https://your-domain.com/api/pay/callback");
config.setSignType(SignType.RSA2);

// 2. 注册回调处理器
PaySdk sdk = new PaySdk(config);
sdk.registerNotifyHandler((request) -> {
  // 验签由SDK内部自动完成
  // 验签通过后返回解析后的订单对象
  PayNotifyResult result = sdk.parseNotify(request);
  // 业务处理...
  return result.getCode().equals("SUCCESS");
});

sdk.start();

至此，已完成支付SDK能力概览与技术评估的全部内容。接下来请进入第2章——沙箱环境配置与商户密钥创建。