# Alipay-Spring-Boot-Starter
**Repository Path**: tool_list/alipay-spring-boot-starter
## Basic Information
- **Project Name**: Alipay-Spring-Boot-Starter
- **Description**: Alipay-Spring-Boot-Starter 是一个轻量级的支付宝支付集成组件，基于 Spring Boot 自动配置特性，无需复杂配置即可快速实现支付宝电脑网站支付、手机网站支付、退款等核心功能，简化支付宝 SDK 的集成流程。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-19
- **Last Updated**: 2026-01-19
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# Alipay Spring Boot Starter 使用文档
## 简介
Alipay Spring Boot Starter 是一个轻量级的支付宝支付集成组件，基于 Spring Boot 自动配置特性，无需复杂配置即可快速实现支付宝**电脑网站支付、手机网站支付、退款**等核心功能，简化支付宝 SDK 的集成流程。
## 版本要求
* JDK 8+
* Spring Boot 2.3.x \~ 2.7.x（兼容 Spring Boot 3.x，需调整依赖适配）
* 支付宝商户账号（已开通支付 / 退款权限）
## 快速开始
### 1. 引入依赖
在 Maven 项目的 `pom.xml` 中添加依赖
```
edu.nf.alipay.spring.boot
alipay-spring-boot-starter
1.0
```
### 2. 配置支付宝参数
在 `application.yml` 或 `application.properties` 中配置支付宝核心参数（从支付宝商户后台获取）：
#### YML 格式（推荐）
```yaml
alipay:
# 应用ID（必填）
app-id: your-alipay-app-id
# 商户私钥（必填，PKCS8格式，去除换行）
private-key: your-merchant-private-key
# 支付宝公钥（必填，从支付宝开放平台获取）
public-key: alipay-public-key
# 支付回调通知地址（必填，公网可访问）
notify-url: https://your-domain.com/alipay/notify
# 支付跳转同步回调地址（可选，前端跳转页面）
return-url: https://your-domain.com/alipay/return
# 字符编码（默认UTF-8，无需修改）
charset: UTF-8
# 签名算法（默认RSA2，支付宝推荐）
sign-type: RSA2
# 支付宝网关（沙箱环境：https://openapi.alipaydev.com/gateway.do；正式环境：https://openapi.alipay.com/gateway.do）
gateway-url: https://openapi.alipaydev.com/gateway.do
```
#### Properties 格式
```properties
alipay.app-id=your-alipay-app-id
alipay.private-key=your-merchant-private-key
alipay.public-key=alipay-public-key
alipay.notify-url=https://your-domain.com/alipay/notify
alipay.return-url=https://your-domain.com/alipay/return
alipay.charset=UTF-8
alipay.sign-type=RSA2
alipay.gateway-url=https://openapi.alipaydev.com/gateway.do
```
### 3. 核心 API 注入
在 Spring Boot 组件（Controller/Service）中注入 `AlipayTemplate`，即可调用支付、退款等功能：
```java
import com.yourcompany.alipay.template.AlipayTemplate;
import com.yourcompany.alipay.request.PayRequest;
import com.yourcompany.alipay.response.PayResponse;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource;
@RestController
public class AlipayController {
// 注入支付宝模板（自动配置，无需手动创建）
@Autowired
private AlipayTemplate alipayTemplate;
// 示例：发起电脑网站支付
@GetMapping("/alipay/pay")
public String doPay() {
// 1. 构建支付请求参数
PayRequest payRequest = new PayRequest();
payRequest.setOutTradeNo("MERCHANT\_20240520001"); // 商户订单号（唯一）
payRequest.setTotalAmount("0.01"); // 支付金额（单位：元）
payRequest.setSubject("测试商品"); // 订单标题
payRequest.setBody("测试商品描述"); // 订单描述（可选）
payRequest.setProductCode("FAST\_INSTANT\_TRADE\_PAY"); // 产品码（电脑网站支付固定值）
// 2. 发起支付，获取支付宝跳转链接（或表单HTML）
PayResponse response = alipayTemplate.pay(payRequest);
if (response.isSuccess()) {
// 电脑网站支付返回表单HTML，直接返回给前端渲染
return response.getFormHtml();
} else {
return "支付发起失败：" + response.getErrorMessage();
}
}
}
```
## 核心功能使用
### 一、支付功能
支持**电脑网站支付、手机网站支付**，核心差异在于 `productCode` 参数：
| 支付类型 | productCode 固定值 | 场景说明 |
| ------ | ------------------------- | --------- |
| 电脑网站支付 | FAST\_INSTANT\_TRADE\_PAY | 电脑端网页支付 |
| 手机网站支付 | QUICK\_WAP\_WAY | 移动端 H5 支付 |
#### 1. 电脑网站支付（示例）
```Java
// 构建支付请求
PayRequest payRequest = new PayRequest();
payRequest.setOutTradeNo("MERCHANT\_20240520001"); // 商户唯一订单号
payRequest.setTotalAmount("99.00"); // 支付金额（精确到分）
payRequest.setSubject("Java编程思想（书籍）"); // 订单标题
payRequest.setProductCode("FAST\_INSTANT\_TRADE\_PAY"); // 电脑网站支付产品码
payRequest.setReturnUrl("https://your-domain.com/pay/success"); // 同步回调地址（支付成功后跳转）
// 发起支付，返回表单HTML（前端直接渲染即可跳转支付宝）
PayResponse response = alipayTemplate.pay(payRequest);
if (response.isSuccess()) {
return response.getFormHtml(); // 前端渲染该HTML自动跳转支付宝
}
```
#### 2. 手机网站支付（示例）
```Java
PayRequest payRequest = new PayRequest();
payRequest.setOutTradeNo("MERCHANT\_20240520002");
payRequest.setTotalAmount("199.00");
payRequest.setSubject("手机端会员充值");
payRequest.setProductCode("QUICK\_WAP\_WAY"); // 手机网站支付产品码
payRequest.setBody("年度会员充值");
PayResponse response = alipayTemplate.pay(payRequest);
return response.getFormHtml(); // 移动端H5页面渲染后跳转支付宝
```
### 二、退款功能
支持全额退款或部分退款，需传入原订单号和退款单号（唯一）。
#### 1. 发起退款（示例）
```Java
import com.yourcompany.alipay.request.RefundRequest;
import com.yourcompany.alipay.response.RefundResponse;
// 构建退款请求
RefundRequest refundRequest = new RefundRequest();
refundRequest.setOutTradeNo("MERCHANT\_20240520001"); // 原商户订单号
refundRequest.setOutRequestNo("REFUND\_20240520001"); // 商户退款单号（唯一，区分同一订单的多次退款）
refundRequest.setRefundAmount("0.01"); // 退款金额（不能超过原订单金额）
refundRequest.setRefundReason("用户取消订单"); // 退款原因（可选）
// 发起退款
RefundResponse response = alipayTemplate.refund(refundRequest);
if (response.isSuccess()) {
System.out.println("退款成功！退款金额：" + response.getRefundAmount());
System.out.println("退款时间：" + response.getGmtRefundPay());
} else {
System.out.println("退款失败：" + response.getErrorMessage());
}
```
#### 2. 退款注意事项
* 退款单号 `outRequestNo` 必须唯一，同一订单多次退款需使用不同的退款单号；
* 退款金额不能超过原订单的实际支付金额；
* 退款申请提交后，支付宝会异步处理，建议通过 “退款查询” 接口确认最终退款状态。
### 三、支付回调处理
支付宝支付成功后，会向配置的 `notify-url` 发起异步通知（POST 请求），需验证通知的真实性并更新订单状态。
#### 回调处理示例（Controller）
```java
import com.yourcompany.alipay.util.AlipayNotifyUtil;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;
import javax.annotation.Resource;
import javax.servlet.http.HttpServletRequest;
import java.util.Map;
@RestController
@RequestMapping("/alipay")
public class AlipayNotifyController {
@Resource
private AlipayTemplate alipayTemplate;
// 支付宝异步通知接收地址（需与 application.yml 中配置的 notify-url 一致）
@PostMapping("/notify")
public String handleNotify(HttpServletRequest request) {
try {
// 1. 获取支付宝通知参数（Map格式）
Map\ notifyParams = AlipayNotifyUtil.getNotifyParams(request);
// 2. 验证通知的真实性（核心：防止伪造通知）
boolean verifyResult = alipayTemplate.verifyNotify(notifyParams);
if (!verifyResult) {
return "fail"; // 验证失败，返回fail告知支付宝
}
// 3. 验证通知状态（支付成功的状态为 TRADE\_SUCCESS）
String tradeStatus = notifyParams.get("trade\_status");
if (!"TRADE\_SUCCESS".equals(tradeStatus)) {
return "success"; // 非支付成功状态，返回success避免支付宝重复通知
}
// 4. 处理业务逻辑（更新订单状态、记录支付日志等）
String outTradeNo = notifyParams.get("out\_trade\_no"); // 商户订单号
String tradeNo = notifyParams.get("trade\_no"); // 支付宝交易号
String totalAmount = notifyParams.get("total\_amount"); // 支付金额
// TODO: 此处编写你的业务逻辑（如：更新订单为“已支付”状态）
System.out.println("订单支付成功：商户订单号=" + outTradeNo + "，支付宝交易号=" + tradeNo);
// 5. 处理成功，返回success告知支付宝（无需重复通知）
return "success";
} catch (Exception e) {
// 异常处理（记录日志）
e.printStackTrace();
return "fail";
}
}
}
```
#### 回调验证说明
* 必须通过 `alipayTemplate.verifyNotify(notifyParams)` 验证通知签名，防止恶意伪造；
* 通知参数中的 `trade_status` 为 `TRADE_SUCCESS` 时，才表示支付成功；
* 处理完成后必须返回 `success`（纯字符串，无多余字符），否则支付宝会每隔一段时间重复发送通知。
## 配置参数详解
| 配置项 | 类型 | 是否必填 | 说明 |
| ------------------ | ------ | ---- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| alipay.app-id | String | 是 | 支付宝开放平台创建应用后获取的 AppID |
| alipay.private-key | String | 是 | 商户私钥（PKCS8 格式，需去除换行符，可通过支付宝密钥生成工具生成） |
| alipay.public-key | String | 是 | 支付宝公钥（从支付宝开放平台 “应用详情 - 开发设置” 中获取） |
| alipay.notify-url | String | 是 | 支付异步通知地址（公网可访问，用于接收支付宝支付结果通知） |
| alipay.return-url | String | 否 | 支付同步回调地址（支付成功后跳转的前端页面，仅用于页面跳转，不做业务处理） |
| alipay.charset | String | 否 | 字符编码，默认 UTF-8 |
| alipay.sign-type | String | 否 | 签名算法，默认 RSA2（支付宝推荐，支持 RSA 和 RSA2，优先使用 RSA2） |
| alipay.gateway-url | String | 是 | 支付宝网关地址：沙箱环境（[https://openapi.alipaydev.com/gateway.do](https://openapi.alipaydev.com/gateway.do)）、正式环境（[https://openapi.alipay.com/gateway.do](https://openapi.alipay.com/gateway.do)） |
## 常见问题（FAQ）
### 1. 支付发起失败，提示 “签名验证失败”？
* 检查 `private-key` 和 `public-key` 是否正确（私钥是商户的，公钥是支付宝的，不要混淆）；
* 私钥需为 PKCS8 格式（去除 `-----BEGIN PRIVATE KEY-----` 和 `-----END PRIVATE KEY-----` 及换行）；
* 签名算法 `sign-type` 需与支付宝开放平台配置一致（默认 RSA2）。
### 2. 回调通知接收不到？
* 检查 `notify-url` 是否为公网可访问（可通过 ngrok 等工具内网穿透测试）；
* 检查服务器是否有防火墙拦截支付宝的请求（支付宝 IP 段需放行）；
* 检查回调接口是否返回 `success` 字符串（无多余空格或 HTML 标签）。
### 3. 退款失败，提示 “订单不存在”？
* 检查 `outTradeNo` 是否为已支付成功的订单号；
* 确认订单是否已过退款有效期（支付宝普通订单退款有效期为支付成功后 3 个月）；
* 检查退款金额是否超过原订单支付金额。
## 联系与反馈
* 项目地址：https://gitee.com/tu-fangsheng/alipay-spring-boot-starter.git
* 问题反馈： 提交或发送邮件至 1474088532@qq.com || rsl808084@gmail.com