Alipay SDK for Java完全指南：一个仓库同时覆盖v2与v3协议，两者到底差在哪？

Alipay SDK for Java完全指南：一个仓库同时覆盖v2与v3协议，两者到底差在哪？

【免费下载链接】alipay-sdk-java-all支付宝开放平台 Alipay SDK for Java项目地址: https://gitcode.com/gh_mirrors/al/alipay-sdk-java-all

Alipay SDK for Java 是支付宝开放平台官方提供的 Java 服务端 SDK，让你无需处理复杂的证书校验、加签、验签和 HTTP 请求细节，即可快速接入支付宝的支付、转账、账单、小程序等开放能力。这个仓库最特别的地方在于：它把v2 协议和v3 协议两套 SDK 放在同一个仓库中维护，新手常常困惑——我该用哪一套？v2 和 v3 到底差在哪？本文用最通俗的方式带你一次讲清楚。

🧭 30秒看懂：Alipay SDK for Java 帮你做了什么

调用支付宝接口，裸写代码你需要自己处理这些"脏活累活"：

• 🔐加签：用你的应用私钥对请求签名，证明"真的是你发的"
• ✅验签：用支付宝的证书/公钥验证响应，防止被篡改
• 📦报文组装：按协议要求拼装 XML 或 JSON 请求
• 🌐HTTP 通信：发送请求、处理超时与异常

Alipay SDK for Java 把这一切都封装好了，你只需要：创建客户端 → 设置参数 → 调用接口。

📁 仓库结构一览：v2 和 v3 各住在哪里

两个核心客户端类的源码位置：

• v2 客户端：v2/src/main/java/com/alipay/api/DefaultAlipayClient.java
• v3 客户端：v3/src/main/java/com/alipay/v3/ApiClient.java

🕰️ v2 SDK：久经考验的经典协议

v2 是目前绝大多数存量项目在使用的方式，发起的是基于v2 协议的 OpenAPI 调用。

特点速览：

• 请求入口统一为网关地址https://openapi.alipay.com/gateway.do，通过method参数区分接口
• 数据格式支持 XML 和表单格式（也支持 JSON）
• 签名针对业务参数拼接串进行，规则相对复杂
• 版本号为4.x，例如4.40.934.ALL（见v2/pom.xml）
• 支持 JDK 1.6 及以上，对老系统非常友好

Maven 引入依赖：

<dependency> <groupId>com.alipay.sdk</groupId> <artifactId>alipay-sdk-java</artifactId> <version>4.40.934.ALL</version> </dependency>

调用只有 3 步（完整示例见v2/README.md）：

1. 创建并初始化DefaultAlipayClient（填入 AppID、私钥、证书路径等）
2. 创建对应接口的 Request 对象，填充业务参数 Model
3. 执行请求，判断response.isSuccess()并处理结果

💡 排障小技巧：当isSuccess()返回 false 时，从日志中拿到trace_id，提供给支付宝技术支持可以最快定位问题。

🚀 v3 SDK：RESTful + JSON 的现代协议

v3 发起的是基于v3 协议的 OpenAPI 调用，是支付宝接口的"未来式"。相比 v2 协议，主要区别有四点：

• 🧩RESTful 风格：每个接口有独立的 URL 路径（如/v3/alipay/trade/pay），并用 OpenAPI 规范（OAS）标准描述
• 📄只用 JSON：不再使用 XML 和表单格式
• ✍️加验签更简单：直接对 HTTP 报文整体加验签，逻辑大幅简化
• 🗂️文件上传、加解密等规范也更简化

v3 SDK 还有一个"出身"亮点：它是基于仓库内的 OpenAPI 描述文件v3/api/openapi.yaml，用 OpenAPI Generator 工具自动生成的。这意味着接口定义即代码，规范性和一致性更好。每个 API 都有独立的 Markdown 文档，存放在v3/docs/目录下（共 300+ 篇）。

Maven 引入依赖：

<dependency> <groupId>com.alipay.sdk</groupId> <artifactId>alipay-sdk-java-v3</artifactId> <version>3.1.78.ALL</version> </dependency>

调用方式更贴近 HTTP 语义：全局配置一次AlipayConfig（AppID、私钥、公钥或证书），然后实例化具体的 API 类直接调用，例如交易支付就是AlipayTradeApi的pay方法，错误处理则通过ApiException统一抛出（完整示例见v3/README.md）。

⚠️ 环境要求：Java 1.8+、Maven 3.8.3+ 或 Gradle 7.2+。

⚖️ 核心对比：v2 与 v3 到底差在哪？

🤔 新手选型指南：到底该用哪个？

选 v2，如果你：

• 维护的是老项目，或团队已有大量 v2 调用代码
• 运行环境是 JDK 1.6~1.7 的老系统
• 目标接口文档标注的是 v2 协议（大多数存量接口仍是 v2）

选 v3，如果你：

• 从零开始开发新项目 ✅
• 喜欢 RESTful + JSON 的现代化 API 设计
• 希望加验签逻辑更简单、排查更直接
• 项目使用 Java 8 及以上环境

一句话总结：新项目优先 v3，老项目稳定用 v2。两套 SDK 可以共存，按接口所属协议分别调用即可。

📚 上手前必做的 3 件准备

无论 v2 还是 v3，使用 SDK 前都需要在支付宝开发者中心完成准备工作：

1. 创建应用并添加所需功能包（支付、转账等）
2. 设置接口加签方式：推荐使用"公钥证书模式"（更安全），保存好 AppID、应用私钥、应用公钥证书、支付宝公钥证书、支付宝根证书等文件
3. 升级安全版本：v2 建议 4.34.0 及以上（修复 Fastjson 漏洞风险）；v3 建议 2.9.0.ALL 及以上（兼容平台接口新版）

🔍 常用文件速查表

希望这篇对比指南帮你快速理清 Alipay SDK for Java 中 v2 与 v3 的差异，选对协议、少走弯路，顺利接入支付宝开放平台！

【免费下载链接】alipay-sdk-java-all支付宝开放平台 Alipay SDK for Java项目地址: https://gitcode.com/gh_mirrors/al/alipay-sdk-java-all