# supos-java-openapi-httpclient

**Repository Path**: huang-jian-bo/supos-java-openapi-httpclient

## Basic Information

- **Project Name**: supos-java-openapi-httpclient
- **Description**: 适配supOS的JAVA版本的OpenAPI调用脚手架
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 0
- **Created**: 2025-01-13
- **Last Updated**: 2026-03-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# supOS-OpenAPI-SDK(Java)

[![Apache2.0](license.svg)](http://www.apache.org/licenses/LICENSE-2.0)

- [supOS-OpenAPI-SDK(Java)](#supos-openapi-sdkjava)
    - [1. 介绍](#1-介绍)
      - [1.1. 使用的技术栈](#11-使用的技术栈)
      - [1.2. supOS兼容列表](#12-supos兼容列表)
    - [2. 部署教程](#2-部署教程)
      - [2.1. 基于Maven的源码编译方式](#21-基于maven的源码编译方式)
    - [3. 使用说明](#3-使用说明)
      - [3.1. 配置maven引用](#31-配置maven引用)
      - [3.2. 创建客户端（普通模式）](#32-创建客户端普通模式)
      - [3.3. 创建客户端（Spring-boot模式）](#33-创建客户端spring-boot模式)
      - [3.4. 创建客户端（高代码APP）](#34-创建客户端高代码app)
      - [3.5. 创建客户端（基于Spring boot开发的高代码APP）](#35-创建客户端基于spring-boot开发的高代码app)
      - [3.6. 动态传递配置参数](#36-动态传递配置参数)
    - [4.接口使用说明](#4接口使用说明)
      - [4.1. 接口说明](#41-接口说明)
      - [4.2. 接口示例](#42-接口示例)

### 1. 介绍

欢迎使用supOS JAVA版本的OpenAPI调用SDK。本SDK适配目前市面上常见的supOS商业版本，支持高代码APP开发者、外部系统集成商等；
支持完整的supOS OpenAPI调用能力，包括参数校验、异常捕获、语言传递、租户配置及上传文件、下载文件等功能，且封装了对AK/SK的签名算法及对Token认证的支持，方便开发者进行使用。

#### 1.1. 使用的技术栈

| 序号 | 名称          | 版本      | 说明              |
|----|-------------|---------|-----------------|
| 1  | fastjson2   | 2.0.54  | 参数JSON序列化       |
| 2  | httpclient5 | 5.4.1   | HTTP客户端组件，支持连接池配置 |
| 3  | java        | (>=)1.8 | JAVA运行版本        |

#### 1.2. supOS兼容列表

| 名称    | 版本          |
|-------|-------------|
| supOS | V3.50.XX.XX |
| supOS | V4.XX.XX.XX |
| supOS | V5.XX.XX.XX |
| supOS | V6.XX.XX.XX |

### 2. 部署教程

#### 2.1. 基于Maven的源码编译方式

* 前提条件：部署Maven(>=3.0)

> 执行以下指令查看Maven版本
```shell
mvn -version
```

* 下载代码
```shell
git clone https://gitee.com/huang-jian-bo/supos-java-openapi-httpclient.git
```
或者
```shell
git clone git@gitee.com:huang-jian-bo/supos-java-openapi-httpclient.git
```
* 编译并部署开发组件
```shell
mvn clean package install -DskipTests=true
```

### 3. 使用说明

#### 3.1. 配置maven引用
```xml
<dependencies>
    <dependency>
        <groupId>org.slf4j</groupId>
        <artifactId>slf4j-api</artifactId>
        <version>1.7.36</version>
    </dependency>
    <dependency>
        <groupId>com.alibaba.fastjson2</groupId>
        <artifactId>fastjson2</artifactId>
        <version>2.0.54</version>
    </dependency>
    <dependency>
        <groupId>org.apache.httpcomponents.client5</groupId>
        <artifactId>httpclient5</artifactId>
        <version>5.4.1</version>
    </dependency>
    <dependency>
        <groupId>io.gitee.huang-jian-bo</groupId>
        <artifactId>openapi-httpclient-core</artifactId>
        <version>1.0.5</version>
    </dependency>
    <dependency>
        <groupId>io.gitee.huang-jian-bo</groupId>
        <artifactId>openapi-httpclient-httpclient5</artifactId>
        <version>1.0.5</version>
    </dependency>
</dependencies>
```

#### 3.2. 创建客户端（普通模式）
适用于外部服务调用supOS OpenAPI的场景。使用之前通过supOS的管理端申请到AK/SK账套
（系统配置->AK/SK管理） 后进行配置使用。

```java
// 设置调用参数
SuposApiClientConfig config = SuposApiClientConfig.of()
                .ticket("TYOEhrter970gUYETth==") // 令牌，可选。配置后将优先使用令牌认证
                .accessKey("f1b8d10248b92c7566a4a0b55e103ca3") // AK，必填
                .secretKey("d20d283d662294b9c360c28be4e8402a") // SK，必填
                .endpoint("http://192.168.236.87:8080") // supOS请求地址，必填
                .defaultLanguage(HttpLanguage.zh_CN) // 默认调用语言，非必填。默认中文
                .appId("example") // 应用ID，必填。同申请AK/SK时填的APP ID
                .tenantId(ApiClientConstant.DEFAULT_TENANT); // 租户ID，非必填。默认为dt
// 获取接口
SuposApiClient client = SuposApiClientFactory.getClient(config);
```

#### 3.3. 创建客户端（Spring-boot模式）

区别于普通模式，适用于基于Spring boot进行开发的应用集成SDK调用supOS OpenAPI。
使用之前需先在supOS的管理端申请到AK/SK账套。

通过Maven引用boot-starter包：
```xml
<dependency>
  <groupId>io.gitee.huang-jian-bo</groupId>
  <artifactId>openapi-httpclient-boot-starter</artifactId>
  <version>1.0.5</version>
</dependency>
```

application.yml配置示例如下：
```yaml
supos:
  sdk:
    ticket: hAGmKomQ0BeI2oPiVYDcK
    access-key: f1b8d10248b92c7566a4a0b55e103ca3
    secret-key: d20d283d662294b9c360c28be4e8402a
    endpoint: http://192.168.1.1:8080
    app-id: example
    tenant-id: dt
    default-language: zh_CN
    service-name: "example"
    httpclient5:
      max-idle-time: 60000
      connection-timeout: 5000
      response-timeout: 60000
      socket-timeout: 15000
      rcv-buf-size: 8192
      snd-buf-size: 8192
```

SDK参数说明(supos.sdk)：

| 参数名称                       | 参数说明                                                  |
|----------------------------|-------------------------------------------------------|
| ticket           | 配置令牌认证模式，当填写后调用时<font color="red">令牌认证优先于AK/SK</font> |
| access-key       | AK，在supOS中申请获得                                        |
| secret-key       | SK，在supOS中申请获得                                        |
| endpoint         | supOS访问地址，格式为：http[s]://ip:port                       |
| app-id           | 应用ID，申请AK/SK时填的APP ID                                 |
| tenant-id        | 租户ID，应用调用supOS的哪个租户，默认为dt                             |
| default-language | 默认语言，应用调用supOS的语言环境，默认为中文                             |
| service-name     | 应用服务名称，可与app-id一致                                     |

HttpClient5参数说明（supos.sdk.httpclient5）：

| 参数名称                       | 参数说明                                 |
|-------------------|--------------------------------------|
|max-idle-time| 连接最大空闲时间，单位毫秒。默认60000                |
|connection-timeout| 获取连接超时时间，单位毫秒。默认5000                 |
|response-timeout| 请求响应超时时间，单位毫秒。默认60000                |
|socket-timeout| TCP连接超时时间，单位毫秒。默认15000               |
|rcv-buf-size| TCP接收缓冲区大小，默认8192。详见：TCP的SO_RCVBUF参数 |
|snd-buf-size| TCP发送缓冲区大小，默认8192。详见：TCP的SO_SNDBUF参数 |


#### 3.4. 创建客户端（高代码APP）

当应用是遵守supOS的高代码APP规范开发的应用并通过supOS的应用管理安装的应用APP，
则可以简化相关参数配置。SDK会自动读取应用容器中的相关参数的“环境变量”进行赋值。

读取的环境变量如下：

| 环境变量名称                | 变量说明                                            |
|-----------------------|-------------------------------------------------|
| SUPOS_ADDRESS         | supOS的访问地址，默认为http://supos-gateway.default:8080 |
| SUPOS_APP_ID          | 应用的APP ID                                       |
| SUPOS_APP_TENANT_ID   | 应用当前所属的租户ID                                     |
| SUPOS_APP_ACCOUNT_ID  | AK                                              |
| SUPOS_APP_SECRET_KEY  | SK                                              |
|SUPOS_APP_SERVICE_NAME| 应用在K8S中的SVC名称                                   |

应用代码创建客户端代码如下：
```java
SuposApiClient client = SuposApiClientFactory.getClient(SuposApiClientConfig.of());
```

#### 3.5. 创建客户端（基于Spring boot开发的高代码APP）

如应用也是基于Spring boot开发，可参考Spring-boot模式，直接在Yaml中配置上述的环境变量来设置参数，示例如下：
```yaml
supos:
  sdk:
    access-key: ${SUPOS_APP_ACCOUNT_ID}
    secret-key: ${SUPOS_APP_SECRET_KEY}
    endpoint: ${SUPOS_ADDRESS:http://supos-gateway.default:8080}
    app-id: ${SUPOS_APP_ID}
    tenant-id: ${SUPOS_APP_TENANT_ID:dt}
    default-language: ${OSLANG:zh_CN}
    service-name: ${SUPOS_APP_SERVICE_NAME}
```
代码中使用客户端代码如下：
```java
/**
 * 注入
 */
@Autowired
private SuposApiClient suposApiClient;
```

#### 3.6. 动态传递配置参数

支持在客户端的代码中动态的指定配置参数进行调用，示例如下：
```java
suposApiClient
        .ticket("hAGmKomQ0BeI2oPiVYDcK")
        .accessKey("f1b8d10248b92c7566a4a0b55e103ca3")
        .secretKey("d20d283d662294b9c360c28be4e8402a")
        .tenantId(ApiClientConstant.DEFAULT_TENANT)
        .language(HttpLanguage.zh_CN)
        .callWithoutResponse(path, args, headers);
```
上述参数，在调用时指定后将<font color="red">优先于初始化的配置</font>。

### 4.接口使用说明
本SDK对接口调用的参数进行高度的封装，以方便开发者进行代码编写。

#### 4.1. 接口说明
| 接口名称                       | 功能说明                               |
|----------------------------|------------------------------------|
| callWithResponse           | 请求带返回参，此接口扩展了支持分页查询及传递数组、Map表等参数能力 |
| callWithResponseNoArgs     | 请求带返回参，且无请求参传递                     |
| callWithoutResponse        | 请求不带返回参                            |
| callWithoutResponseNoArgs  | 请求不带返回参，且无请求参传递                    |
| upload                     | 上传文件                               |
| download                   | 下载文件                               |
| getSupOSVersions           | 获取supOS的版本信息                       |

#### 4.2. 接口示例
以“查询指定编码的公司的人员列表”的OpenAPI为例：

* 定义请求参
```java
import com.sun.deploy.util.StringUtils;

/**
 * 请求参
 */
public class FindPersonsByCompanyArgs implements RequestArguments {
  /**
   * 定义URL的Path参数值
   * 必录项
   */
  @PathParam
  private String companyCode;
  /**
   * 定义页号参数
   */
  @QueryParam
  private Integer current = 1;
  /**
   * 定义页码参数
   */
  @QueryParam
  private Integer pageSize = 20;
  /**
   * 定义模糊匹配关键字
   */
  @QueryParam
  private String keyword;
  /**
   * 定义一个自定义的请求头，发起请求时将会填充至HTTP请求头当中
   */
  @HeaderParam
  private String example;

  /**
   * 参数校验
   * 当请求参中有必录项、限制长度、限制值范围等约束时，可以实现此接口进行参数校验。
   * 此接口在请求发起前执行，如校验失败则请求中止
   *
   * @return
   */
  @Override
  public boolean validate() {
    if (StringUtils.isEmpty(this.companyCode)) {
        throw new NullPointerException("the field of CompanyCode is null");
    }
    return true;
  }
}
```
上述示例中分别通过PathParam、QueryParam和HeaderParam的注解来表示请求的参数，上述注解在客户端发起请求时将被解释并进行HTTP协议赋值。注解说明如下：

| 注解名称        | 说明                                    |
|-------------|---------------------------------------|
| PathParam   | 用于配置URL的Path参数                        |
| QueryParam  | 用于配置URL的Query参数                       |
| HeaderParam | 用于配置请求的HTTP自定义请求头，可为空                 |
| FormParam   | 用于上传文件时携带请求参数，详见multipart/form-data协议 |
| IgnoreParam | 主要用于进行JSON序列化时，忽略相关字段                 |

并且，除了上述注解外，支持实现validate()接口来对参数进行有效性、完整性校验。

* 定义返回参
```java
/**
 * 返回参
 */
public class Person {
    private String code;
    private String name;
    private Integer valid;
}
```
* 发起调用
```java
// 定义请求地址
HttpPath findCompanyUrl = HttpPath.of("/open-api/organization/v2/companies/{companyCode}/persons");
// 定义请求头
//HttpHeader headers = HttpHeader.of(); // 空参
HttpHeader headers = HttpHeader.of().add("test", "test"); // 定义了一个test请求头
// 定义请求参
FindPersonsByCompanyArgs args = new FindPersonsByCompanyArgs();
args.setCompanyCode("1000"); // 设置公司编码为1000
args.setCurrent(2); // 设置页码为2
args.setKeyword("test"); // 设置查询关键字为test
// 发起请求
// 返回分页数据
PageResult<Person> result = client.callWithResponseForPageResult(findCompanyUrl, args, headers, Person.class);
```