# hop-java-sdk **Repository Path**: hywrepo/hop-java-sdk ## Basic Information - **Project Name**: hop-java-sdk - **Description**: java对接汇元开放平台sdk - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 1 - **Created**: 2025-11-21 - **Last Updated**: 2026-09-24 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 汇元开放平台 Java SDK 使用指引 **更新日期：2023-03-23** --- ## 📖 简介 汇元开放平台 Java SDK 是为开发者提供的便捷接入工具，支持 RSA2 和 SM2 两种签名方式，帮助您快速对接汇元支付相关接口。 **环境要求：** JDK 1.8 及以上版本 --- ## 📦 SDK 获取 ### 多语言 SDK 支持 汇元开放平台提供多种语言的 SDK，请根据您的技术栈选择： | 名称 | 语言 | 环境要求 | 获取地址 | |------|------|---------|----------| | hop-java-sdk | Java | JDK 1.8 及以上 | [Gitee 仓库](https://gitee.com/hywrepo/hop-java-sdk) | | hop-csharp-sdk | C# | .NET Framework 3.5 及以上 | [Gitee 仓库](https://gitee.com/hywrepo/hop-csharp-sdk) | | hop-php-sdk | PHP | PHP 5 及以上 | [Gitee 仓库](https://gitee.com/hywrepo/hop-php-sdk) | ### 获取方式 **方式一：Git 克隆** ```bash git clone https://gitee.com/hywrepo/hop-java-sdk.git ``` **方式二：直接下载** 访问 [Gitee 仓库](https://gitee.com/hywrepo/hop-java-sdk) 点击下载 ZIP 压缩包 --- ## 🚀 快速开始 ### 第一步：导入 SDK 到项目 **Maven 项目：** 将 SDK 源码复制到您的项目中，或将 SDK 打包后添加到本地 Maven 仓库。 **普通 Java 项目：** 直接导入 SDK 的 JAR 包及其依赖到项目的 classpath 中（支持 Maven 或直接导入 JAR 包）。 ### 第二步：配置环境参数 打开 `src/main/java/com/hyw/hop/api/demo/HopEnvConfig.java` 文件，根据您的实际情况修改配置： #### 1. 切换环境 ```java // 切换到沙箱环境（用于测试） private static final Env ACTIVE_ENV = Env.SANDBOX; // 切换到生产环境（正式上线） private static final Env ACTIVE_ENV = Env.PROD; ``` #### 2. 配置商户信息 **沙箱环境配置（测试用）：** - SDK 中已内置沙箱环境的测试账号，可直接使用 **生产环境配置（正式使用）：** 找到 `getRsa2ConfigByEnv()` 方法中的生产环境配置部分： ```java case PROD: config.setAppId("您的应用ID"); // 替换为您的 AppId config.setServerUrl("https://openapi.heepay.com"); config.setPrivateKey("您的商户RSA2私钥"); // 替换为您的私钥 config.setHopPublicKey("汇元提供的RSA2公钥"); // 替换为汇元公钥 break; ``` 同样，如果使用 SM2 签名，还需要配置 `getSm2ConfigByEnv()` 方法中的生产环境部分。 ### 第三步：验证 SDK 配置 运行 `src/main/java/com/hyw/hop/api/demo/SdkDemo.java` 中的测试方法： ```java public static void main(String[] args) { // 打印当前环境 System.out.println("当前环境：" + HopEnvConfig.getActiveEnv().getDesc()); // 测试接口（验证配置是否正确） sayHelloRsa2(); // 测试 RSA2 签名 sayHelloSm2(); // 测试 SM2 签名 } ``` **运行结果：** ![沙箱测试示例](https://res.heepay.com/public/doc/img/20250804/d61311ca9871485f068cf84a4ee02022.png) 如果接口调用成功，说明 SDK 配置正确，可以开始对接业务接口。 --- ## 💡 对接业务接口 ### 方式一：使用 SDK 已封装的接口 #### 1. 查找对应的 Request 和 Response 类 从 API 文档中找到您要对接的接口 method 方法名，例如：`customer.info.enter.query`（商户入网查询） ![API文档示例](https://res.heepay.com/public/doc/img/20250808/1d35886dc501f07871e17c81e9680793.png) #### 2. 在 SDK 中全局搜索对应的类 在项目中搜索 `CustomerEnterQueryRequest`（请求类）和 `CustomerEnterQueryResponse`（响应类） ![搜索示例](https://res.heepay.com/public/doc/img/20250808/5f2e35cd085538b471073e2448301aba.png) #### 3. 调用接口 参考 `SdkDemo.java` 中的示例代码： ```java public static void customerEnterQueryRSa2() { // 1. 创建请求对象 CustomerEnterQueryRequest req = new CustomerEnterQueryRequest(); req.setRequestNo("innerApi20064"); // 设置请求参数 req.setQueryType("BUSINESS_REQUEST"); // 2. 调用接口（使用 RSA2 签名客户端） HopResponse rsp = HopEnvConfig.getClientRsa2().execute(req); // 3. 处理响应结果 System.out.println("调用完成，响应数据：" + JsonUtil.toPrettyJson(rsp)); } ``` ![调用示例](https://res.heepay.com/public/doc/img/20250808/f1d7e9873b0433f5aa6d93dca4760915.png) **核心要点：** - 使用 `HopEnvConfig.getClientRsa2()` 获取 RSA2 签名客户端 - 使用 `HopEnvConfig.getClientSm2()` 获取 SM2 签名客户端 - 调用 `execute(req)` 方法执行接口请求 --- ### 方式二：自定义 Request 和 Response 类 如果 SDK 中没有您需要的接口封装，可以参考已有接口自己定义： #### 1. 创建 Request 类 ```java public class YourBusinessRequest extends HopRequestModel { // 定义请求参数 private String param1; private String param2; @Override public String getMethod() { return "your.api.method"; // 对应 API 文档中的 method } @Override public Class getResponseClass() { return YourBusinessResponse.class; } // Getter 和 Setter 方法 // ... } ``` #### 2. 创建 Response 类 ```java public class YourBusinessResponse extends HopResponseModel { // 定义响应字段（根据 API 文档） private String result1; private String result2; // Getter 和 Setter 方法 // ... } ``` #### 3. 调用接口 ```java YourBusinessRequest req = new YourBusinessRequest(); req.setParam1("value1"); req.setParam2("value2"); HopResponse rsp = HopEnvConfig.getClientRsa2().execute(req); System.out.println(JsonUtil.toPrettyJson(rsp)); ``` --- ## 📋 常见接口示例 ### 1. 测试接口（验证连通性） ```java SayHelloRequest req = new SayHelloRequest(); req.setHello("测试"); HopResponse rsp = HopEnvConfig.getClientRsa2().execute(req); ``` ### 2. 商户入网查询 ```java CustomerEnterQueryRequest req = new CustomerEnterQueryRequest(); req.setRequestNo("商户请求号"); req.setQueryType("BUSINESS_REQUEST"); HopResponse rsp = HopEnvConfig.getClientRsa2().execute(req); ``` ### 3. 文件上传 ```java CustomerFileUploadRequest req = new CustomerFileUploadRequest(); req.setFileMediaType("01"); // 文件类型 req.setFileContent(new File("文件路径")); req.setFileSign(getFileMD5("文件路径")); // 文件 MD5 签名 HopResponse rsp = HopEnvConfig.getClientRsa2().execute(req); ``` ### 4. 余额查询 ```java MerchantBalanceQueryRequest req = new MerchantBalanceQueryRequest(); req.setQueryType("BALANCE"); HopResponse rsp = HopEnvConfig.getClientRsa2().execute(req); ``` --- ## 🔧 核心类说明 | 类名 | 说明 | |------|------| | `HopEnvConfig` | 环境配置管理类，统一管理沙箱/生产环境配置 | | `SdkDemo` | 接口调用示例类，包含常用接口的调用示例 | | `HopClient` | SDK 核心客户端类，负责发起 API 调用 | | `HopConfig` | 客户端配置类，包含 AppId、密钥、URL 等信息 | | `HopRequestModel` | 请求基类，所有业务请求类需继承此类 | | `HopResponseModel` | 响应基类，所有业务响应类需继承此类 | --- ## 📂 项目目录结构 ``` src/main/java/com/hyw/hop/api/ ├── demo/ # 示例代码 │ ├── HopEnvConfig.java # 环境配置管理（必看） │ └── SdkDemo.java # 接口调用示例（必看） ├── model/ # 数据模型 │ ├── accountTrade/ # 账户交易相关模型（余额、充值、提现等） │ ├── customer/ # 客户信息相关模型（入网、查询等） │ ├── heepayCom/ # 通用业务模型 │ ├── heepayFund/ # 资金业务模型 │ └── heepayPay/ # 支付业务模型 ├── util/ # 工具类（加密、HTTP、JSON等） ├── HopClient.java # 核心客户端类 ├── HopConfig.java # 客户端配置类 └── HopConstant.java # 常量定义 ``` --- ## ⚙️ 技术栈 - **开发语言：** Java 8+ - **构建工具：** Maven - **核心依赖：** - Jackson / FastJson（JSON 处理） - Apache HttpClient（HTTP 通信） - Bouncy Castle（加密算法） - Hutool（工具类库） - Commons Lang3（通用工具） - CFCA 安全组件（数字证书） --- ## ❓ 常见问题 ### 1. 其他语言的 SDK 如何使用？ 本文档以 Java SDK 为例，其他语言 SDK 的使用方法请参考对应仓库的说明文档： - [C# SDK 使用说明](https://gitee.com/hywrepo/hop-csharp-sdk) - [PHP SDK 使用说明](https://gitee.com/hywrepo/hop-php-sdk) ### 2. 如何切换沙箱和生产环境？ 修改 `HopEnvConfig.java` 中的 `ACTIVE_ENV` 常量： ```java private static final Env ACTIVE_ENV = Env.SANDBOX; // 沙箱环境 private static final Env ACTIVE_ENV = Env.PROD; // 生产环境 ``` ### 3. RSA2 和 SM2 如何选择？ - **RSA2：** 国际通用加密算法，兼容性好 - **SM2：** 国密算法，符合国家密码管理局要求 根据您的业务需求选择对应的客户端即可。 ### 4. 如何查看完整的 API 文档？ 请联系汇元技术支持获取完整的 API 接口文档。 ### 5. 遇到签名错误怎么办？ 检查以下配置项： - AppId 是否正确 - 私钥和公钥是否匹配 - 环境 URL 是否正确（沙箱/生产） - 签名类型是否与密钥匹配（RSA2/SM2） --- ### 6. Maven 依赖问题如何解决？ SDK 中包含两个 CFCA 安全组件需要手动放置： - `lib/sadk-3.6.3.2.jar` - `lib/logback-cfca-jdk-1.1.8.jar` 请确保这些 JAR 文件存在于项目的 `lib/` 目录下，否则可能导致编译失败。 --- ## 📞 技术支持 如有问题，请联系汇元技术支持团队。 **相关链接：** - [Java SDK 仓库](https://gitee.com/hywrepo/hop-java-sdk) - [C# SDK 仓库](https://gitee.com/hywrepo/hop-csharp-sdk) - [PHP SDK 仓库](https://gitee.com/hywrepo/hop-php-sdk) --- ## 📄 许可证 本 SDK 由汇元支付提供，仅供合作商户使用。