SDK说明

SaaS OpenAPI 客户端 SDK，封装了接口调用的加解密、签名与 HTTP 通讯细节，业务方只需关注接口地址和业务参数。

SDK调用

下载SDK

TODO 后续补充

环境要求

JDK 8+

Maven

引入依赖

<dependency>
    <groupId>com.jcsk</groupId>
    <artifactId>saas-openapi-sdk</artifactId>
    <version>1.0.0-SNAPSHOT</version>
</dependency>

客户项目需自行引入以下依赖：

<!-- Hutool 版本属性 -->
<properties>
    <hutool.version>5.8.35</hutool.version>
    <bouncycastle.version>1.78.1</bouncycastle.version>
</properties>

<!-- Hutool 工具库（HTTP / 加密 / JSON） -->
<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-all</artifactId>
    <version>${hutool.version}</version>
</dependency>
<!-- BouncyCastle（JDK 8 环境提供 SM4 算法支持） -->
<dependency>
    <groupId>org.bouncycastle</groupId>
    <artifactId>bcprov-jdk15to18</artifactId>
    <version>${bouncycastle.version}</version>
</dependency>

快速开始

1. 创建客户端

客户端为无状态对象，建议全局复用单例。

2. 配置项说明

配置项	必填	默认值	说明
baseUrl	是	-	服务端基础地址，由平台分配
appKey	是	-	平台分配的应用标识
appSecret	是	-	平台分配的应用密钥，长度须为 16 字节（SM4 密钥要求）
version	否	`"1"`	接口版本号
timeout	否	`10000`	HTTP 请求超时时间（毫秒）

3. 调用接口

postJson 参数说明：

api：接口地址，由用户传入。以 http 开头时视为完整 URL 直接请求；否则自动拼接到 baseUrl 之后（是否以 / 开头均可）

params：业务参数，支持 Map、JSONObject、JavaBean 或 JSON 字符串

timeout（可选）：本次请求超时时间（毫秒），不传时取配置值（默认 10000）

单次调用指定超时时间：

响应处理

响应报文格式（data 为 SM4 加密串，SDK 自动解密后返回明文）：

{
 "code": 200,
 "data": "SM4 加密后的 Base64 字符串",
 "msg": "处理成功",
 "success": true
}

OpenApiResponse 提供以下方法：

方法	返回类型	说明
`getCode()`	`int`	响应码
`getMsg()`	`String`	响应消息
`isSuccess()`	`boolean`	是否成功（取响应中的 `success` 字段）
`getData()`	`Object`	业务数据（解密后的明文 JSON 字符串）
`getDataJSON()`	`JSONObject`	业务数据转 JSONObject，便于直接取字段

异常处理

请求加密、HTTP 通讯、响应解析失败时统一抛出 OpenApiException（RuntimeException）：

注意：接口返回业务失败（success=false）不抛异常，需通过 isSuccess() 判断。

日志

SDK 使用 slf4j 打印 debug 级别日志（请求 URL、请求报文、响应报文）。排查问题时将 com.jcsk.openapi 包的日志级别调为 DEBUG 即可：

<logger name="com.jcsk.openapi" level="DEBUG"/>

通讯协议说明

SDK 在通讯层自动完成以下处理，业务方无需关心：

加密：请求体 JSON 使用 SM4（CBC 模式 + ZeroPadding）加密，每次请求生成随机 16 字节 IV（Base64 编码传输）

签名：sign = MD5(appKey + appSecret + encryptStr + timestamp + iv)

请求公共参数：appKey、version、encryptStr（加密后的业务参数）、iv、timestamp、sign

响应：data 为 SM4 加密串（与请求同一密钥/IV），SDK 解密后返回明文

SDK集成

SDK说明#

SDK调用#

下载SDK#

环境要求#

引入依赖#

快速开始#

1. 创建客户端#

2. 配置项说明#

3. 调用接口#

响应处理#

异常处理#

日志#

通讯协议说明#