AIGC/demo/IJPAY_USAGE_GUIDE.md

IJPay 使用指南

一、IJPay 简介

IJPay 是一个简洁易用的 Java 聚合支付 SDK，支持微信支付、支付宝支付、银联支付等多种支付方式。

项目已集成 IJPay-AliPay 模块，用于支付宝支付功能。

二、项目中的 IJPay 使用方式

1. 依赖配置

在 pom.xml 中已添加 IJPay 依赖：

<dependency>
    <groupId>com.github.javen205</groupId>
    <artifactId>IJPay-AliPay</artifactId>
    <version>2.9.12.1</version>
</dependency>

2. 代码使用方式

项目中主要通过 AlipayController.java 使用 IJPay 的 AliPayApi 类进行支付操作。

2.1 扫码支付（QR码支付）

@PostMapping("/qr-pay")
public ResponseEntity<Map<String, Object>> qrPay(...) {
    AlipayTradePrecreateModel model = new AlipayTradePrecreateModel();
    model.setOutTradeNo(outTradeNo);
    model.setTotalAmount(totalAmount);
    model.setSubject(subject);
    model.setBody(body);
    
    // 使用 IJPay 的 AliPayApi 调用预创建接口
    String qrCode = AliPayApi.tradePrecreatePayToResponse(model, notifyUrl).getBody();
    // 返回二维码字符串
}

2.2 PC网页支付

@PostMapping("/pc-pay")
public void pcPay(...) {
    AlipayTradePagePayModel model = new AlipayTradePagePayModel();
    model.setOutTradeNo(outTradeNo);
    model.setProductCode("FAST_INSTANT_TRADE_PAY");
    model.setTotalAmount(totalAmount);
    model.setSubject(subject);
    
    // 使用 IJPay 的 AliPayApi 进行页面跳转
    AliPayApi.tradePage(response, model, notifyUrl, returnUrl);
}

2.3 手机网页支付

@PostMapping("/wap-pay")
public void wapPay(...) {
    AlipayTradeWapPayModel model = new AlipayTradeWapPayModel();
    model.setOutTradeNo(outTradeNo);
    model.setProductCode("QUICK_WAP_PAY");
    model.setTotalAmount(totalAmount);
    
    // 使用 IJPay 的 AliPayApi 进行手机支付
    AliPayApi.wapPay(response, model, returnUrl, notifyUrl);
}

2.4 APP支付

@PostMapping("/app-pay")
public ResponseEntity<Map<String, Object>> appPay(...) {
    AlipayTradeAppPayModel model = new AlipayTradeAppPayModel();
    model.setOutTradeNo(outTradeNo);
    model.setProductCode("QUICK_MSECURITY_PAY");
    model.setTotalAmount(totalAmount);
    
    // 使用 IJPay 的 AliPayApi 获取 APP 支付订单信息
    String orderInfo = AliPayApi.appPayToResponse(model, notifyUrl).getBody();
    // 返回订单信息给 APP
}

2.5 订单查询

@GetMapping("/query")
public ResponseEntity<Map<String, Object>> queryOrder(...) {
    AlipayTradeQueryModel model = new AlipayTradeQueryModel();
    model.setOutTradeNo(outTradeNo);
    
    // 使用 IJPay 的 AliPayApi 查询订单
    String result = AliPayApi.tradeQueryToResponse(model).getBody();
    // 返回查询结果
}

2.6 退款

@PostMapping("/refund")
public ResponseEntity<Map<String, Object>> refund(...) {
    AlipayTradeRefundModel model = new AlipayTradeRefundModel();
    model.setOutTradeNo(outTradeNo);
    model.setRefundAmount(refundAmount);
    model.setRefundReason(refundReason);
    
    // 使用 IJPay 的 AliPayApi 发起退款
    String result = AliPayApi.tradeRefundToResponse(model).getBody();
    // 返回退款结果
}

2.7 异步通知处理

@PostMapping("/notify")
public String notifyUrl(HttpServletRequest request) {
    // 使用 IJPay 的 AliPayApi 将请求参数转换为 Map
    Map<String, String> params = AliPayApi.toMap(request);
    
    // 验证签名
    boolean verifyResult = AlipaySignature.rsaCertCheckV1(
        params, aliPayConfig.getAliPayCertPath(), "UTF-8", "RSA2");
    
    if (verifyResult) {
        // 处理支付成功逻辑
        return "success";
    } else {
        return "failure";
    }
}

三、IJPay 配置说明

3.1 配置方式

IJPay 的 AliPayApi 类内部会自动读取系统属性或配置文件中的支付宝配置。

需要配置的参数包括：

• appId: 支付宝应用ID
• privateKey: 应用私钥
• publicKey: 支付宝公钥
• gatewayUrl: 支付宝网关地址
• charset: 字符编码（通常为 UTF-8）
• signType: 签名类型（通常为 RSA2）

3.2 配置文件

配置在 application-dev.properties 或 application-prod.properties 中：

# 支付宝配置
alipay.app-id=你的APPID
alipay.private-key=你的应用私钥
alipay.public-key=支付宝公钥
alipay.gateway-url=https://openapi.alipaydev.com/gateway.do
alipay.charset=UTF-8
alipay.sign-type=RSA2
alipay.notify-url=回调通知地址
alipay.return-url=同步返回地址

3.3 IJPay 初始化（可选）

如果需要显式初始化 IJPay，可以在应用启动时配置：

@Configuration
public class IJPayConfig {
    
    @Autowired
    private AliPayConfig aliPayConfig;
    
    @PostConstruct
    public void init() {
        // IJPay 的 AliPayApi 会自动读取配置
        // 如果需要显式配置，可以使用 AliPayApiConfigKit
        // 注意：具体初始化方式取决于 IJPay 版本
    }
}

四、IJPay vs 原生 Alipay SDK

项目中同时使用了两种方式：

1. IJPay (AliPayApi) - 在 AlipayController.java 中使用

   • 优点：封装更简洁，使用更方便
   • 缺点：需要额外依赖 IJPay 库

2. 原生 Alipay SDK (DefaultAlipayClient) - 在 AlipayService.java 中使用

   • 优点：官方 SDK，功能完整
   • 缺点：需要手动创建客户端和处理响应

五、常见问题

Q1: IJPay 如何初始化？

A: IJPay 的 AliPayApi 类内部会自动读取配置，通常不需要显式初始化。如果遇到配置问题，可以检查：

1. 配置文件中的参数是否正确
2. 系统属性是否设置
3. 环境变量是否配置

Q2: 如何切换到 IJPay？

A: 如果当前使用原生 Alipay SDK，可以：

1. 修改 AlipayService.java，使用 AliPayApi 替代 DefaultAlipayClient
2. 或者直接使用 AlipayController 中的接口

Q3: IJPay 和原生 SDK 的区别？

A: IJPay 是对原生 SDK 的封装，提供了更简洁的 API。底层实现仍然使用支付宝官方 SDK。

六、参考文档

• IJPay 官方文档：https://github.com/Javen205/IJPay
• IJPay 示例项目：https://github.com/Javen205/IJPay-Demo
• 支付宝开放平台：https://open.alipay.com