openapi

致力于提供一个能够快速搭建开放api的sdk

背景

对外服务的接口为了安全起见，往往需要进行相应的安全处理：数据加密传输和身份认证。数据加密传输有对称加密和非对称加密两种，为了更加安全起见采用非对称加密比较好些，身份认证则采用数字签名可以实现。开发此sdk就是为了能够快速地实现项目中api的安全开放。

基于框架

spring-boot

主要依赖包

cn.hutool.hutool-all

功能

1.负责对外开放接口（基于HTTP对外提供服务）
2.实现接口的参数与返回值的加解密（使用非对称加密：RSA/SM2，或对称加密：AES/SM4）
3.实现接口的验签（服务端会校验客户端的签名，确保调用者身份以及数据不被篡改）

特色

1.提供客户端sdk和服务端sdk,方便在已有项目中快速集成开放api功能
2.实现了三种API的安全交互方式：仅加签+非对称加密+对称加密，可以进行配置切换
3.实现了RSA和SM2等多种加密算法用于接口参数与返回值的加解密
4.专门为文件传输定制一套数据传输机制，使得文件传输更加方便、快速
5.实现了服务端接口文档功能，方便查询所有的API接口
6.方法调用实现了HTTP超时时间、HTTP代理等设置，且支持方法级别的配置

程序流程图

使用方法

服务端

1.引入openapi-server-sdk

<dependency>
    <groupId>io.github.hdwang123</groupId>
    <artifactId>openapi-server-sdk</artifactId>
    <version>1.5.12</version>
</dependency>

2.实现OpenApiConfig接口进行配置

注：默认没有任何配置实现类，启动项目会报错，必须手动配置一个OpenApiConfig实现类

@Component
public class OpenApiConfigImpl implements OpenApiConfig {

    @Value("${keys.local.rsa.privateKey}")
    private String privateKey;

    @Value("${keys.remote.rsa.publicKey}")
    private String callerPublicKey;

    @Override
    public AsymmetricCryEnum getAsymmetricCry() {
        //设置非对称加密算法
        return AsymmetricCryEnum.RSA;
    }

    @Override
    public String getCallerPublicKey(String callerId) {
        //TODO 根据调用者ID查找调用者的公钥（可以将所有调用者的公钥存到数据库中）
        return callerPublicKey;
    }

    @Override
    public String getSelfPrivateKey() {
        //设置服务端私钥
        return privateKey;
    }

    @Override
    public boolean retEncrypt() {
        //设置返回值是否需要加密
        return true;
    }

    @Override
    public CryModeEnum getCryMode() {
        //设置加密模式
        return CryModeEnum.SYMMETRIC_CRY;
    }

    @Override
    public SymmetricCryEnum getSymmetricCry() {
        //设置对称加密算法
        return SymmetricCryEnum.AES;
    }

    @Override
    public boolean enableDoc() {
        //是否启用接口文档功能
        return true;
    }
}

3.自定义开放API

注：被@OpenApi标识的类必须处于spring包的扫描路径下，方可注入容器中

@Slf4j
@OpenApi("userApi")
public class UserApi {

    @OpenApiMethod("getUserById")
    public User getUserById(Long id) {
        log.info("getUserById：id=" + id);
        User user = new User();
        user.setId(1L);
        user.setName("张三");
        return user;
    }
}

4.查看开放API接口文档

网址：http://localhost:8080/openapi/doc.html
实际项目中替换 http://localhost:8080 为实际路径

客户端

1.引入openapi-client-sdk

<dependency>
    <groupId>io.github.hdwang123</groupId>
    <artifactId>openapi-client-sdk</artifactId>
    <version>1.5.12</version>
</dependency>

2.调用openapi

方式一

直接调用OpenApiClient

@Slf4j
@Component
public class UserApiClient {

    @Value("${keys.local.rsa.privateKey}")
    private String privateKey;

    @Value("${keys.remote.rsa.publicKey}")
    private String remotePublicKey;

    String baseUrl = "http://localhost:8080";

    /**
     * 定义OpenApiClient
     */
    OpenApiClient apiClient = null;

    @PostConstruct
    public void init() {
        apiClient = new OpenApiClientBuilder(baseUrl, privateKey, remotePublicKey, "001", "userApi")
                .asymmetricCry(AsymmetricCryEnum.RSA)
                .retDecrypt(true)
                .cryModeEnum(CryModeEnum.SYMMETRIC_CRY)
                .symmetricCry(SymmetricCryEnum.AES)
                .build();
    }


    public void getUserById() {
        OutParams outParams = apiClient.callOpenApi("getUserById", 10001);
        log.info("返回值：" + outParams);
    }
}

方式二

使用注解@OpenApiRef定义服务引用，在需要的地方注入即可
1.定义配置

openapi:
  client:
    config:
      openApiRefPath: openapi.example.client.openapiclient
      baseUrl: http://localhost:8080
      selfPrivateKey: ${keys.local.rsa.privateKey}
      remotePublicKey: ${keys.remote.rsa.publicKey}
      asymmetricCryEnum: RSA
      retDecrypt: true
      cryModeEnum: SYMMETRIC_CRY
      symmetricCryEnum: AES
      callerId: "001"
      httpConnectionTimeout: 3
      httpReadTimeout: 6
#      httpProxyHost: 127.0.0.1
#      httpProxyPort: 8888

2.定义服务引用

@OpenApiRef(value = "userApi")
public interface UserApiClient {

    @OpenApiMethod("getUserById")
    User getUserById(Long id);
}

3.注入服务引用调用远程openapi服务

@Component
public class UserApiTest2 {

    @Autowired
    UserApiClient userApiClient;

    public void getUserById() {
        User user = userApiClient.getUserById(10001L);
        log.info("返回值：" + user);
    }
}

wilsonp / openapi