supOS SDK for Java 开发指南

为了更好的帮助企业开发者进行系统集成，减轻开发者对接OpenAPI的难度，蓝卓提供了基于JAVA语言的集成工具包SDK（后续将陆续支持多种开发语言），实现对supOS多版本的兼容，降低使用方对supOS的过度依赖。

SDK说明

SDK名称：bluetron-java-sdk

jar包下载地址：bluetron-java-sdk-1.1.4.jar

主要用于高代码开发的自研APP用。

接入方式

非 Spring Boot 接入方式

引入依赖

<dependency>
    <groupId>com.bluetron.sdk</groupId>
    <artifactId>bluetron-java-sdk</artifactId>
    <version>#{最佳版本}</version>
</dependency>

版本兼容性详见版本更新列表。

配置参数 SdkDefaultConfig

主要包含以下信息：

• 系统相关配置

• supOS 相关配置

• okHttp 相关配置

• i18n 相关配置

// 设置配置信息
SdkBaseService.setSdkConfigStorage(SdkConfigStorage sdkConfigStorage)

提供服务

• SdkService
  • 应用统一的配置和出口；
  • 实现类：com.bluetron.app.middle.sdk.api.SdkServiceImpl；
  • 接口服务：SdkAppService，SdkSuposService；
• SdkSuposService
  • supOS 接口服务；
  • 实现类：com.bluetron.app.middle.sdk.api.supOS.SdkSuposService；
• SdkSuposService
  • 内置App接口服务；
  • 实现类：com.bluetron.app.middle.sdk.api.app.SdkAppService；
• getAccessToken()
  • 认证模式;
  • 实现类：com.bluetron.sdk.api.SdkBaseService；
  • 默认值：OAuth 2.0 的 client 模式;
• code 认证模式
  • 使用方法：getAccessToken();
  • 实现方式：调用com.bluetron.sdk.config.SdkConfigStorage.setAuthorizationCode() 及 com.bluetron.sdk.config.SdkConfigStorage.setAuthorizationCodeRedirectUri()；

Demo 示例

• 单独使用 SdkSuposService

SdkDefaultConfig config = new SdkDefaultConfig();
// 示例值，请根据实际参数进行配置
config.setAppId("App_f977249f96f34f01aae3259d98671a7f");
config.setAppSecret("965d2dc6ac2da958e91ba6c5d57bba72");
config.setAppVersion("2.6.0");
config.setRequestUrl("http://127.0.0.1");
config.setRequestPort("80");
config.setReadTimeout(10);
SdkSuposService sdkSuposService = new SdkSuposServiceImpl();
sdkSuposService.setSdkConfigStorage(config);
// 注意，一定要进行初始化
sdkSuposService.init();
// 获取对象模型接口，根据需要调用相关方法即可
ObjectService objectService = sdkSuposService.getObjectService();

• 单独使用 SdkAppService

SdkDefaultConfig config = new SdkDefaultConfig();
// 示例值，请根据实际参数进行配置
config.setAppId("App_f977249f96f34f01aae3259d98671a7f");
config.setAppSecret("965d2dc6ac2da958e91ba6c5d57bba72");
config.setIamAccountId("552987919581184");
config.setIamSecretKey("c07582d917b924f217b94c38b2d4484c");
config.setAppVersion("2.6.0");
config.setRequestUrl("http://127.0.0.1");
config.setRequestPort("80");
config.setReadTimeout(10);
SdkAppService sdkAppService = new SdkAppServiceImpl();
sdkAppService.setSdkConfigStorage(config);
// 注意，一定要进行初始化
sdkAppService.init();
// 通过sdkAppService获取相关app内置服务即可

• 同时使用 SdkSuposService和SdkAppService

SdkDefaultConfig config = new SdkDefaultConfig();
// 示例值，请根据实际参数进行配置
config.setAppId("App_f977249f96f34f01aae3259d98671a7f");
config.setAppSecret("965d2dc6ac2da958e91ba6c5d57bba72");
config.setIamAccountId("552987919581184");
config.setIamSecretKey("c07582d917b924f217b94c38b2d4484c");
config.setAppVersion("2.6.0");
config.setRequestUrl("http://127.0.0.1");
config.setRequestPort("8088");
config.setReadTimeout(10);

SdkService sdkService = new SdkServiceImpl();
sdkService.setSdkConfigStorage(config);

// 注意，一定要进行初始化
sdkService.init();

// 通过sdkAppService获取相关app内置服务
SdkAppService sdkAppService = sdkService.getSdkAppService();

// 通过sdkSuposService获取相关Supos服务
SdkSuposService sdkSuposService = sdkService.getSdkSuposService();

分布式开发

• 存在问题
  对于sdk的配置信息，系统默认提供了基于内存的存储方式。
  如果需要支持分布式，存在access_token生成时竞争的问题

• 解决办法
  使用方可以通过继承com.bluetron.sdk.config.SdkDefaultConfig进行扩展；
  也可以完全实现com.bluetron.sdk.config.SdkConfigStorage满足需求。

Spring Boot 接入方式

统一定义bean

@Data
@Configuration
@ConfigurationProperties(prefix = "bluetron.sdk")
public class BluetronSdkProperties {
    /**
     * 是否开启debug模式，该模式下会打印日志
     */
    private boolean debugEnable;

    /**
     * supOS 请求地址
     */
    private String requestUrl;

    /**
     * supOS apis 请求端口
     */
    private String requestPort;

    /**
     * appid
     */
    private String appId;

    /**
     * appSecret
     */
    private String appSecret;

    /**
     * accountId, 参见supOS数据库:supOS_iam,表:iam_account
     */
    private volatile String iamAccountId;

    /**
     * secretKey, 参见supOS数据库:supOS_iam,表:iam_account
     */
    private volatile String iamSecretKey;

    private String accessToken;

    private String refreshToken;

    private String appVersion;

    private Integer readTimeout;

    private String iamAccountId;

    private String iamSecretKey;
}

application.yml配置信息

bluetron:
  sdk:
    enabled: true #是否开启登陆校验
    debug-enable: false
    request-url: http://127.0.0.1
    request-port: 8080
    app-id: 
    app-secret: 
    aksk-enable: true
    iam-account-id：
    iam-secret-key：
    app-version: 2.60.00.00-200316-C
    read-timeout: 10
    accept-language: zh-cn

• 这里提供一种在Spring中的使用方式

@Slf4j
public class BluetronSdk {
    public static SdkService sdkService;
    public static SdkSuposService supOSService;
    public static SdkAppService appService;

    static  {
        log.info("初始化bluetron sdk...");
        //SpringContextHolder 需要使用方自行定义
        BluetronSdkProperties bluetronSdkProperties = SpringContextHolder.getBean(BluetronSdkProperties.class);
        SdkDefaultConfig config = new SdkDefaultConfig();
        BeanUtils.copyProperties(bluetronSdkProperties, config);
        log.info("bluetron sdk 配置信息{}...", config);
        sdkService = new SdkServiceImpl();
        //配置sdk
        sdkService.setSdkConfigStorage(config);
        //初始化sdk
        sdkService.init();
        //获取对应service实例
        supOSService = sdkService.getSdkSuposService();
        appService = sdkService.getSdkAppService();
        log.info("完成初始化bluetron sdk...");
    }
}

国际化

i18N支持

实现方式

supOS使用 header Accept-Language ： zh-cn / en-us 来做国际化；

默认配置

SdkDefaultConfig中增加 acceptLanguage 字段，默认为中文；

修改配置

如果需要修改为英文环境，则可以再配置文件或者是初始化手工修改，代码如下：

config.setAcceptLanguage(SdkConstants.SUPOS_EN_US);

详见测试用例：UserServiceImpl_118n_Test;

AK/SK使用

说明

AK/SK认证开启以后，OpenAPI 接口走 AK/SK 流程，其他接口仍然以 OAuth 2.0 方式处理。

常见问题排查

自检内容

确保方法的入参是否都正确，注意请求的 Http Method。

排查步骤

请求返回提示：{"code":"80021002","message":"illegal account"},可以到supOS环境中对其日志进行查看。

// 查看命名空间
k3s kubectl get ns

// 查看pod
k3s kubectl get pod -n {namespace}

// 查看pod日志
k3s kubectl logs {pod_id} -n {namespace}

在日志中可以看到 请求的入参、签名源、签名结果、响应信息。可以根据以上信息对问题进行排查。