一单位一平台

主题

HzTech2026-03-02
696
3m

SDK 快速开始 ​

本指南将帮助您快速集成一单位一平台 Java SDK 到您的项目中。

概述 ​

一单位一平台 Java SDK 是用于子应用对接的官方 SDK，提供了完整的人员、部门、角色、菜单、权限、接口管理和消息发送功能。

核心特性 ​

  • 国密 SM2+SM4 数字信封加密
  • 自动处理报文加密、解密、签名、验签
  • 21 个 API 接口覆盖完整业务场景
  • 自动重试机制
  • 完整的请求/响应日志
  • 本地缓存支持
  • Spring Boot 自动配置

环境要求 ​

  • Java 17+
  • Spring Boot 3.2+
  • Maven 3.6+

安装 ​

1. 添加 Maven 依赖 ​

在您的项目 pom.xml 中添加依赖：

xml
<dependency>
    <groupId>cn.hztech</groupId>
    <artifactId>hztech-platform-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

2. 配置文件 ​

在 application.yml 中添加基础配置：

yaml
hztech:
  platform:
    sdk:
      # 基础配置
      app-id: SUB_APP_001
      gateway-url: https://platform.example.com

      # 密钥配置（使用环境变量）
      private-key: ${HZTECH_PRIVATE_KEY}
      platform-public-key: ${HZTECH_PLATFORM_PUBLIC_KEY}

3. 环境变量配置 ​

在启动脚本或系统环境中设置环境变量：

bash
export HZTECH_PRIVATE_KEY="MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC..."
export HZTECH_PLATFORM_PUBLIC_KEY="MFkwEQYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE5s8aJ5LX8QY4ZJ5K8M5ZJL8qN3s..."

快速示例 ​

查询用户详情 ​

java
@Service
public class UserService {

    @Autowired
    private UserApiClient userApiClient;

    /**
     * 查询用户详情
     */
    public User getUserDetail(String userId) {
        return userApiClient.getDetail(userId);
    }
}

REST 控制器示例 ​

java
@RestController
@RequestMapping("/api/demo")
public class DemoController {

    @Autowired
    private UserApiClient userApiClient;

    @GetMapping("/user/{userId}")
    public Result<User> getUser(@PathVariable String userId) {
        User user = userApiClient.getDetail(userId);
        return Result.success(user);
    }
}

查询用户列表 ​

java
@Service
public class UserService {

    @Autowired
    private UserApiClient userApiClient;

    /**
     * 查询用户列表
     */
    public PageResult<User> getUserList(int pageNum, int pageSize) {
        UserListRequest request = new UserListRequest();
        request.setPageNum(pageNum);
        request.setPageSize(pageSize);
        request.setStatus(1); // 只查询启用的用户
        return userApiClient.getList(request);
    }
}

搜索用户 ​

java
@Service
public class UserService {

    @Autowired
    private UserApiClient userApiClient;

    /**
     * 搜索用户
     */
    public PageResult<User> searchUsers(String keyword) {
        UserSearchRequest request = new UserSearchRequest();
        request.setKeyword(keyword);
        request.setPageNum(1);
        request.setPageSize(20);
        return userApiClient.search(request);
    }
}

验证安装 ​

运行以下代码验证 SDK 是否正确安装：

java
@SpringBootTest
class SdkIntegrationTest {

    @Autowired
    private UserApiClient userApiClient;

    @Test
    void testSdkConnection() {
        // 测试连接是否正常
        User user = userApiClient.getDetail("test-user-id");
        assertNotNull(user);
    }
}

下一步 ​

常见问题 ​

如何获取密钥？ ​

向一单位一平台管理员申请应用 ID 和密钥对。

时间戳验证失败怎么办？ ​

检查系统时间是否同步，确保误差在±60秒内。

如何启用调试日志？ ​

在配置文件中设置：

yaml
logging:
  level:
    cn.hztech.sdk: DEBUG

参考文档 ​

最近更新