使用 IDEA 开发一个简单易用的 SDK

news2024/12/25 14:53:35

一、什么是 SDK

二、为什么要开发 SDK

三、开发 SDK 的详细步骤

四、导入 SDK 进行测试

附：@ConfigurationProperties 注解的介绍及使用

一、什么是 SDK

1. 定义：软件开发工具包 Software Development Kit

2. 用于开发特定软件或应用程序的工具、库、文档和示例代码的集合

二、为什么要开发 SDK

1. 便于集成和使用：编写 SDK，为其他开发者提供一种简化的方式来使用我们提供的功能或服务；开发者只需要填写简单的配置信息，即可创建客户端，调用我们提供的 API 进行操作，而不用关心具体实现

2. 加速开发过程：通过提供 SDK，其他开发者可以直接使用我们预先封装好的功能和接口，而无需从头开始编写相关代码

例如：我们编写好了 API 签名认证的功能，其中客户端需要设置请求头，服务端需要取出请求头中的数据进行校验，通过签名生成算法来校验签名 sign 是否一致以判断用户的权限，操作繁杂。如果其他开发者引入我们编写的 SDK，就不需要重复编写上面的实现代码，直接填写配置创建客户端就可以直接调用现成的接口来进行 API 签名认证了！

3. 提供示例和文档：SDK 通常附带有详细的文档和示例代码，文档可以提供清晰的说明、API 参考和最佳实践等，示例代码则可以展示如何正确地使用 SDK 中提供的功能

4. 开放共享和合作：其他开发者可以在我们提供的 SDK 的基础上进行二次开发和定制化

5. 功能代码复用：如果其他项目需要使用（API 签名认证功能），直接导入之前写好的 SDK / starter，就可以直接使用咯

三、开发 SDK 的详细步骤

1. 新建 SpringBoot 项目，引入依赖

Lombok
Spring Configuration Processor：在 application.yml 中填写配置时自动补全、提示代码 / 配置项

2. 修改 pom.yml 文件中的版本号和依赖

修改版本号：自己开发的 starter 的版本号

删除 <build></build> 中的内容：build 中是 Maven 构建依赖的方式，不删除会构建为 jar 包，开发 SDK 是要构建依赖包而不是 jar 包，直接删除 build 中的内容

3. 删除项目主类，创建自己 SDK 的客户端配置主类，并添加注解

创建配置类，在引入依赖时自动生成客户端实例

@Configuration
@ConfigurationProperties("leapi.client")：读取配置项，自动映射
@ComponentScan
@Data

4.定义客户端 LeAPIClient 以及添加客户端所需的依赖 Hutool

package com.ghost.leapiclientsdk.client;

import cn.hutool.core.util.RandomUtil;
import cn.hutool.http.HttpRequest;
import cn.hutool.http.HttpResponse;
import cn.hutool.http.HttpUtil;
import cn.hutool.json.JSONUtil;
import com.ghost.leapiclientsdk.model.User;
import com.ghost.leapiclientsdk.utils.SignUtil;

import java.util.HashMap;
import java.util.Map;


/**
 * 调用第三方接口的客户端
 * @author 乐小鑫
 * @version 1.0
 * @Date 2024-02-01-20:28
 */
public class LeAPIClient {
    private String accessKey;
    private String secretKey;

    public LeAPIClient(String accessKey, String secretKey) {
        this.accessKey = accessKey;
        this.secretKey = secretKey;
    }

    public String getNameByGet(String name) {
        //可以单独传入http参数，这样参数会自动做URL编码，拼接在URL中
        HashMap<String, Object> paramMap = new HashMap<>();
        paramMap.put("name", name);
        String result = HttpUtil.get("http://localhost:8102/api/name/", paramMap);
        System.out.println(result);
        return result;
    }

    public String getNameByPost(String name) {
        HashMap<String, Object> paramMap = new HashMap<>();
        paramMap.put("name", name);
        String result = HttpUtil.post("http://localhost:8102/api/name/", paramMap);
        System.out.println(result);
        return result;
    }



    /**
     * 将参数添加到请求头 map
     * @return
     */
    private Map<String, String> headerMap(String body) {
        HashMap<String, String> hashMap = new HashMap<>();
        hashMap.put("accessKey", accessKey);
        // 一定不能发送给后端！
//        hashMap.put("secretKey", secretKey);
        hashMap.put("nonce", RandomUtil.randomNumbers(5));
        hashMap.put("body", body);
        hashMap.put("timestamp", String.valueOf(System.currentTimeMillis() / 1000));
        hashMap.put("sign", SignUtil.genSign(body, secretKey));
        return hashMap;
    }

    public String getNameByJSON(User user) {
        String userStr = JSONUtil.toJsonStr(user);
        HttpResponse httpResponse = HttpRequest.post("http://localhost:8102/api/name/user")
                .addHeaders(headerMap(userStr))// 客户端在请求头中携带签名
                .body(userStr)
                .execute();
        System.out.println(httpResponse.getStatus());
        String body = httpResponse.body();
        System.out.println(body);
        return body;
    }

}

5. 定义生成客户端的 Bean，读取配置文件 application.yml 中的配置项为 Java 对象 / 属性（accessKey 和 secretKey）赋值

@Bean：让 Spring 自动加载客户端，管理 Bean

6. 指定加载配置类

创建 META-INF/spring.factories

7. 完成后 install 安装项目到本地 Maven 仓库，SDK 编写完成✔

四、导入 SDK 进行测试

1. 在 pom.xml 中引入 SDK / starter

我们自己编写的 SDK

在其他项目中导入 SDK

2. 在项目的 application.yml 中编写配置（因为 SDK 引入了 Spring Configuration Processor，所以会有提示）

自动生成配置项提示的原理：Spring Configuration Processor 生成的

3. 注入客户端实例

    @Resource
    private LeAPIClient leAPIClient;// 注入客户端实例

4. 调用接口

package com.ghost.leapiinterface;

import com.ghost.leapiclientsdk.client.LeAPIClient;
import com.ghost.leapiclientsdk.model.User;
import org.junit.jupiter.api.Test;
import org.springframework.boot.test.context.SpringBootTest;

import javax.annotation.Resource;

@SpringBootTest
class LeapiInterfaceApplicationTests {

    @Resource
    private LeAPIClient leAPIClient;// 注入客户端实例

    @Test
    void testClientSDK() {
        // 调用接口
        String result = leAPIClient.getNameByGet("ghost");
        User user = new User();
        user.setUsername("xiaoxin");
        String nameByJSON = leAPIClient.getNameByJSON(user);
        System.out.println(result);
        System.out.println(nameByJSON);
    }
}

5. 测试效果：编写测试类，注入客户端，使用客户端调用接口，测试成功✔

附：@ConfigurationProperties 注解的介绍及使用

1. 作用：将配置文件中的属性值与Java类进行绑定。它的作用是将配置文件中的属性值映射到对应的Java对象中，方便在代码中直接使用这些属性值

2. 使用步骤

在需要绑定属性的 Java 类上添加 @ConfigurationProperties 注解。
可以通过 prefix 属性指定要绑定的属性的前缀，也可以通过 value 属性指定具体的属性名。
定义对应的属性字段，并提供 setter 和 getter 方法。
在 application.properties 或 application.yml 配置文件中设置相应的属性值。

3. 示例

@ConfigurationProperties(prefix = "myapp")
public class MyAppConfig {
    private String name;
    private int age;
    
    // getters and setters

}