SDK 配置说明

本文档详细说明一单位一平台 SDK 的所有配置选项。

配置文件

SDK 使用 Spring Boot 配置机制，在 application.yml 或 application.properties 中配置。

基础配置

必填配置

yaml

hztech:
  platform:
    sdk:
      # 应用 ID（必填）
      app-id: SUB_APP_001

      # 网关地址（必填）
      gateway-url: https://platform.example.com

      # 应用私钥（必填）
      private-key: ${HZTECH_PRIVATE_KEY}

      # 平台公钥（必填）
      platform-public-key: ${HZTECH_PLATFORM_PUBLIC_KEY}

配置项	类型	必填	说明
`app-id`	String	是	子应用 ID，由平台分配
`gateway-url`	String	是	平台网关地址
`private-key`	String	是	应用私钥（PEM 格式）
`platform-public-key`	String	是	平台公钥（PEM 格式）

超时配置

yaml

hztech:
  platform:
    sdk:
      # 连接超时（毫秒）
      connect-timeout: 10000    # 10秒

      # 读取超时（毫秒）
      read-timeout: 30000       # 30秒

      # 写入超时（毫秒）
      write-timeout: 30000      # 30秒

配置项	类型	默认值	说明
`connect-timeout`	Integer	10000	建立 TCP 连接的超时时间
`read-timeout`	Integer	30000	读取响应数据的超时时间
`write-timeout`	Integer	30000	发送请求数据的超时时间

日志配置

yaml

hztech:
  platform:
    sdk:
      # 是否启用日志
      enable-log: true

      # 日志级别
      log-level: INFO

配置项	类型	默认值	可选值	说明
`enable-log`	Boolean	true	true/false	是否启用请求/响应日志
`log-level`	String	INFO	DEBUG/INFO/WARN/ERROR	日志级别

日志配置示例

yaml

# 在 application.yml 中设置 SDK 日志级别
logging:
  level:
    cn.hztech.sdk: DEBUG

# 生产环境建议使用 INFO 级别
logging:
  level:
    cn.hztech.sdk: INFO

重试配置

yaml

hztech:
  platform:
    sdk:
      # 是否启用重试
      enable-retry: true

      # 最大重试次数
      max-retries: 3

      # 重试间隔（毫秒）
      retry-interval: 1000

配置项	类型	默认值	说明
`enable-retry`	Boolean	true	是否启用自动重试
`max-retries`	Integer	3	失败后的最大重试次数
`retry-interval`	Integer	1000	重试间隔时间（毫秒）

重试策略

SDK 会在以下情况自动重试：

网络连接失败
读取超时
5xx 服务器错误

重试次数达到上限后，SDK 会抛出 ApiException。

时间戳容差配置

yaml

hztech:
  platform:
    sdk:
      # 时间戳容差（毫秒）
      timestamp-tolerance: 60000  # ±60秒

配置项	类型	默认值	说明
`timestamp-tolerance`	Integer	60000	时间戳验证的容差范围

时间同步要求

客户端与服务器的时间差必须在容差范围内
建议使用 NTP 服务同步时间
容差设置过大会降低安全性

完整配置示例

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}

      # ===== 超时配置 =====
      connect-timeout: 10000
      read-timeout: 30000
      write-timeout: 30000

      # ===== 日志配置 =====
      enable-log: true
      log-level: INFO

      # ===== 重试配置 =====
      enable-retry: true
      max-retries: 3
      retry-interval: 1000

      # ===== 时间戳容差 =====
      timestamp-tolerance: 60000

环境变量配置

为了安全起见，建议使用环境变量存储密钥：

Linux/Mac

bash

# 在 ~/.bashrc 或 ~/.zshrc 中添加
export HZTECH_PRIVATE_KEY="MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC..."
export HZTECH_PLATFORM_PUBLIC_KEY="MFkwEQYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE5s8aJ5LX8QY4ZJ5K8M5ZJL8qN3s..."

Windows

cmd

# 在系统环境变量中设置
HZTECH_PRIVATE_KEY=MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...
HZTECH_PLATFORM_PUBLIC_KEY=MFkwEQYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE5s8aJ5LX8QY4ZJ5K8M5ZJL8qN3s...

Docker

yaml

version: '3.8'
services:
  app:
    image: your-app:latest
    environment:
      - HZTECH_PRIVATE_KEY=MIIEvQIBADANBgkqhkiG9w0B...
      - HZTECH_PLATFORM_PUBLIC_KEY=MFkwEQYHKoZIzj0CAQYIK...

Kubernetes

yaml

apiVersion: v1
kind: Secret
metadata:
  name: hztech-sdk-secrets
type: Opaque
data:
  private-key: MIIEvQIBADANBgkqhkiG9w0B...
  platform-public-key: MFkwEQYHKoZIzj0CAQYIK...
---
apiVersion: v1
kind: Deployment
metadata:
  name: your-app
spec:
  template:
    spec:
      containers:
        - name: app
          env:
            - name: HZTECH_PRIVATE_KEY
              valueFrom:
                secretKeyRef:
                  name: hztech-sdk-secrets
                  key: private-key
            - name: HZTECH_PLATFORM_PUBLIC_KEY
              valueFrom:
                secretKeyRef:
                  name: hztech-sdk-secrets
                  key: platform-public-key

配置属性类

SDK 使用 SdkProperties 类来管理配置：

java

@ConfigurationProperties(prefix = "hztech.platform.sdk")
public class SdkProperties {

    /**
     * 应用 ID
     */
    private String appId;

    /**
     * 网关地址
     */
    private String gatewayUrl;

    /**
     * 应用私钥
     */
    private String privateKey;

    /**
     * 平台公钥
     */
    private String platformPublicKey;

    /**
     * 连接超时
     */
    private Integer connectTimeout = 10000;

    /**
     * 读取超时
     */
    private Integer readTimeout = 30000;

    /**
     * 写入超时
     */
    private Integer writeTimeout = 30000;

    /**
     * 是否启用日志
     */
    private Boolean enableLog = true;

    /**
     * 日志级别
     */
    private String logLevel = "INFO";

    /**
     * 是否启用重试
     */
    private Boolean enableRetry = true;

    /**
     * 最大重试次数
     */
    private Integer maxRetries = 3;

    /**
     * 重试间隔
     */
    private Integer retryInterval = 1000;

    /**
     * 时间戳容差
     */
    private Integer timestampTolerance = 60000;

    // Getters and Setters
}

安全注意事项

密钥管理

不要将密钥硬编码在代码中
不要将密钥提交到 Git 仓库
不要在日志中打印密钥
使用环境变量或密钥管理服务（KMS）
设置适当的文件权限（600）

生产环境建议

yaml

# 生产环境配置示例
hztech:
  platform:
    sdk:
      # 使用环境变量
      app-id: ${HZTECH_APP_ID}
      gateway-url: ${HZTECH_GATEWAY_URL}
      private-key: ${HZTECH_PRIVATE_KEY}
      platform-public-key: ${HZTECH_PLATFORM_PUBLIC_KEY}

      # 日志级别使用 INFO 或 WARN
      enable-log: true
      log-level: INFO

      # 根据实际情况调整超时时间
      connect-timeout: 10000
      read-timeout: 30000
      write-timeout: 30000

配置验证

SDK 启动时会自动验证配置，如果配置不正确会抛出异常：

java

@SpringBootApplication
public class Application {

    public static void main(String[] args) {
        try {
            SpringApplication.run(Application.class, args);
            log.info("SDK 初始化成功");
        } catch (Exception e) {
            log.error("SDK 初始化失败: {}", e.getMessage());
            System.exit(1);
        }
    }
}

常见配置问题

问题1：密钥格式错误

错误信息：Invalid key format

解决方案：确保密钥是 PEM 格式，包含完整的头尾标记：

-----BEGIN PRIVATE KEY-----
MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQC...
-----END PRIVATE KEY-----

问题2：时间戳验证失败

错误信息：Timestamp validation failed

解决方案：

检查系统时间是否同步
增加 timestamp-tolerance 配置值
使用 NTP 服务同步时间

问题3：连接超时

错误信息：Connect timeout

解决方案：

检查网络连接
增加 connect-timeout 配置值
检查防火墙设置

下一步

API 参考 - 查看所有可用的 API 接口
错误处理 - 学习如何处理异常情况

SDK 配置说明 ​

配置文件 ​

基础配置 ​

必填配置 ​

超时配置 ​

日志配置 ​

日志配置示例 ​

重试配置 ​

重试策略 ​

时间戳容差配置 ​

时间同步要求 ​

完整配置示例 ​

环境变量配置 ​

Linux/Mac ​

Windows ​

Docker ​

Kubernetes ​

配置属性类 ​

安全注意事项 ​

密钥管理 ​

生产环境建议 ​

配置验证 ​

常见配置问题 ​

问题1：密钥格式错误 ​

问题2：时间戳验证失败 ​

问题3：连接超时 ​

下一步 ​

SDK 配置说明

配置文件

基础配置

必填配置

超时配置

日志配置

日志配置示例

重试配置

重试策略

时间戳容差配置

时间同步要求

完整配置示例

环境变量配置

Linux/Mac

Windows

Docker

Kubernetes

配置属性类

安全注意事项

密钥管理

生产环境建议

配置验证

常见配置问题

问题1：密钥格式错误

问题2：时间戳验证失败

问题3：连接超时

下一步