如何优雅的设计一个SDK

相信很多开发同学一定都听说过SDK，SDK全称Software Development Kit，即软件开发工具包。它是由硬件平台、操作系统或编程语言的制造商提供的一套工具，协助软件开发人员面向特定的平台、系统或编程语言创建应用。SDK经常被用于为特定的软件包、软件框架、硬件平台、操作系统等创建应用软件的开发工具的集合。

先来个抛砖引玉，写过Java的同学一定听说过JDK ，和SDK只有一字之差，那么它们两者之间有什么区别和联系呢？

首先，SDK（Software Development Kit） 和 JDK（Java Development Kit） 之间的区别：

• 定义不同 ：SDK是软件开发工具包，它是一个广泛的概念，包括各种API、库、文档、工具等，用于辅助开发者开发特定类型的应用程序。而JDK是Java开发工具包，是SDK的一种，专门针对Java语言的开发。

• 涵盖的内容不同：JDK包含Java的运行环境（Java Runtime Environment，JRE），Java编译器（javac）和Java基础的类库。而SDK可能包含特定编程语言或框架的库、接口、文档、示例代码等。

其次，它们两个也有相同的地方：

• 都是一种开发工具：无论是SDK还是JDK，都是开发工具包，为开发者提供了一系列的工具，帮助开发者更有效率地进行开发。

• 都可以提供库和API：两者都会提供库文件和API接口。这些库文件和API接口封装了一些底层操作，提供了更高级别的操作接口，让开发者能更简单地实现功能。

简而言之，SDK是统称，而JDK只是Java的集成开发工具，是SDK的子集。

接下来，我们就着手了解一下SDK的真正作用，是如何使用的，又如何优雅的设计一个SDK。

1 SDK的主要作用

SDK（Software Development Kit）的作用主要体现在以下几个方面：

1. 提供API接口：SDK通常包含一套API接口，这些接口是预先定义好的，开发者可以通过调用这些接口，实现与底层系统的交互，从而简化开发过程。
2. 提供库文件：SDK中通常包含一些库文件，这些库文件包含了大量的函数和类，开发者可以直接使用这些函数和类，而无需从头开始编写。
3. 提供文档和示例代码：SDK还会提供详细的开发文档和示例代码，帮助开发者理解和使用API接口和库文件。

总的来说，SDK的作用就是帮助开发者更快、更方便地开发应用程序。通过提供开发工具、API接口、库文件以及文档和示例代码，SDK降低了开发的难度，提高了开发的效率。

2 SDK的使用场景

SDK的使用场景非常广泛，主要包括以下几个方面：

1. 移动应用开发：无论是Android还是iOS平台，开发者可以使用相应的SDK来构建各类移动应用。例如，Android开发者可以使用Android SDK来访问设备的各种硬件功能，如摄像头、传感器等；iOS开发者则可以使用iOS SDK来利用苹果设备的特色功能，如Touch ID、Apple Pay等。
2. 游戏开发：游戏开发者可以使用游戏引擎提供的SDK来构建游戏应用。例如，开发者可以利用Unity SDK来实现游戏中的各种功能，如图形渲染、物理模拟、音频处理等。
3. 小程序开发：小程序SDK是一种开发工具包，用于开发和构建小程序应用程序。开发者可以使用这些API和组件来构建小程序应用程序，例如在小程序中添加功能、调用硬件设备、实现交互等。使用小程序SDK可以加速小程序开发和部署的过程，并提高小程序的稳定性和性能。
4. 网站开发：在网站开发中，SDK可以作为网站与第三方服务集成的桥梁。例如，支付SDK可以让网站轻松集成支付功能，而无需自行开发复杂的支付系统。类似地，社交SDK可以让网站集成社交网络的功能，如用户登录、分享等。
5. 云端服务：云端服务的SDK为开发者提供了与云服务交互的方式。例如，开发者可以使用AWS SDK（亚马逊网络服务开发工具包）来调用亚马逊的各种云服务，如计算、存储、数据库、分析等。同样，Google Cloud SDK和Azure SDK也为开发者提供了与Google和Microsoft的云服务进行交互的能力。
6. 嵌入式系统开发：在嵌入式系统开发过程中，SDK常常用于提供硬件抽象层、驱动程序以及开发工具等。通过嵌入式SDK，开发者可以更方便地编写、调试和部署应用程序，降低开发难度和复杂性。例如，智能家电的开发者可以使用SDK来简化与设备传感器的交互、实现远程控制等功能。
7. 物联网（IoT）开发：物联网的发展使得设备之间的互联互通成为必要，而SDK在物联网开发中扮演着重要角色。IoT SDK通常包括设备连接、数据传输、安全管理等功能，帮助开发者快速构建IoT应用程序。通过使用IoT SDK，开发者可以将设备连接到云平台，实现远程监控、数据分析和智能控制等功能。

总的来说，SDK的使用场景相当广泛，几乎涵盖了软件开发的各个方面。不过具体使用时还是要根据实际需求进行选择。这些只是SDK的一些典型使用场景，实际上，只要是需要对某种特定功能进行封装以便于开发者使用的场景，都可能会使用到SDK。

3 优雅的设计一个SDK

Go语言SDK的设计流程一般可以分为以下几个步骤：

1. 需求分析：在开始设计SDK之前，首先需要明确SDK的需求和目标。
2. 接口设计：在明确需求后，开始设计SDK的接口。接口设计应该简洁明了，提供清晰的输入和输出，并遵循一致的命名规范和设计原则。
3. 代码实现：根据接口设计，开始编写SDK的代码。在编写代码时，要遵循Go语言的最佳实践，确保代码的可读性、可维护性和性能。同时，要进行适当的错误处理和日志记录，以便于调试和故障排除。
4. 单元测试与集成测试：编写单元测试和集成测试来验证SDK的正确性和稳定性。
5. 文档编写：为SDK编写清晰、详尽的文档。文档应该包括接口的描述、参数说明、返回值说明、错误处理以及示例代码等。
6. 版本发布与迭代：完成代码实现、测试和文档编写后，可以进行SDK的版本发布。遵循语义版本控制规范，确保版本的兼容性和稳定性。

下面我们就以一个HTTP服务为例设计一个简单的SDK。

3.1 先编写一个Go HTTP服务

const (
	HeaderName = "barry yan"
)

var (
	data map[string]string

	ErrOk        = Err{Code: 200, Msg: "ok"}
	ErrNotAuth     = Err{Code: 401, Msg: "not auth"}
	ErrRequestBad   = Err{Code: 400, Msg: "request bad"}
)

func init() {
	data = make(map[string]string)
}

type T struct {
	Key string `json:"key,omitempty"`
	Val string `json:"val,omitempty"`
}

type Err struct {
	Code int    `json:"code,omitempty"`
	Msg  string `json:"msg,omitempty"`
}

func headerInterceptor(c *gin.Context) {
	header := c.Request.Header.Get("name")

	if header != HeaderName {
		c.JSON(http.StatusUnauthorized, ErrNotAuth)
		c.Abort()
		return
	}
	c.Next()
}

func create(c *gin.Context) {
	var t T
	if err := c.BindJSON(&t); err != nil {
		c.JSON(http.StatusBadRequest, ErrRequestBad)
		return
	}
	data[t.Key] = t.Val
	c.JSON(http.StatusOK, ErrOk)
	return
}

func get(c *gin.Context) {
	key := c.Param("key")
	val := data[key]
	c.JSON(http.StatusOK, val)
	return
}

func main() {
	r := gin.Default()
	r.Use(headerInterceptor)

	r.POST("/create", create)
	r.GET("/get/:key", get)

	_ = r.Run(":9999")
}

3.2 了解服务API的调用方式

在没有SDK的情况下我们尝试写代码调用接口：

func TestCreateAPI(t *testing.T) {
	// 创建一个HTTP客户端
	client := &http.Client{}

	// 创建POST请求的body
	reqData := []byte(`{"key":"A","val":"1"}`)

	// 创建一个POST请求
	req, err := http.NewRequest("POST", "http://localhost:9999/create", bytes.NewBuffer(reqData))
	if err != nil {
		fmt.Println("创建请求时发生错误:", err)
		return
	}

	// 设置请求头
	req.Header.Set("Content-Type", "application/json")
	req.Header.Set("name", "barry yan")

	// 发送请求并获取响应
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("发送请求时发生错误:", err)
		return
	}
	defer func() {
		_ = resp.Body.Close()
	}()

	// 读取响应内容
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("读取响应时发生错误:", err)
		return
	}

	// 打印响应内容
	fmt.Println(string(body))
}

func TestGetAPI(t *testing.T) {
	// 创建一个HTTP客户端
	client := &http.Client{}

	// 创建一个GET请求
	req, err := http.NewRequest("GET", "http://localhost:9999/get/A", nil)
	if err != nil {
		fmt.Println("创建请求时发生错误:", err)
		return
	}
	req.Header.Set("name", "barry yan")

	// 发送请求并获取响应
	resp, err := client.Do(req)
	if err != nil {
		fmt.Println("发送请求时发生错误:", err)
		return
	}
	defer func() {
		_ = resp.Body.Close()
	}()

	// 读取响应的内容
	body, err := io.ReadAll(resp.Body)
	if err != nil {
		fmt.Println("读取响应时发生错误:", err)
		return
	}

	// 打印响应内容
	fmt.Println(string(body))
}

该方式的缺点显而易见，比如：

（1）请求参数和返回值定义没有固定的规范

（2）重复代码太多

（3）调用链复杂时难以解耦合

基于此，我们设计一个SDK，专门用于调用该系统API的接口

3.3 设计API的SDK

我们先将Go调用HTTP接口的方式做一个封装：

type Option func(*HttpClient)

type HttpClient struct {
   Url    string
   Body   []byte
   Header map[string]string
   Client *http.Client
}

func NewHttpClient(url string, opts ...Option) *HttpClient {
   cli := &HttpClient{Url: url, Client: &http.Client{}}

   for _, opt := range opts {
      opt(cli)
   }

   return cli
}

func WithBody(body []byte) Option {
   return func(client *HttpClient) {
      client.Body = body
   }
}

func WithHeader(header map[string]string) Option {
   return func(client *HttpClient) {
      client.Header = header
   }
}

func (c *HttpClient) Post() ([]byte, error) {
   req, err := http.NewRequest("POST", c.Url, bytes.NewBuffer(c.Body))
   if err != nil {
      return nil, err
   }

   req.Header.Set("Content-Type", "application/json")
   for k, v := range c.Header {
      req.Header.Set(k, v)
   }

   resp, err := c.Client.Do(req)
   if err != nil {
      return nil, err
   }

   defer func() {
      _ = resp.Body.Close()
   }()

   body, err := io.ReadAll(resp.Body)
   if err != nil {
      return nil, err
   }
   return body, nil
}

func (c *HttpClient) Get() ([]byte, error) {
   req, err := http.NewRequest("GET", c.Url, bytes.NewBuffer(c.Body))
   if err != nil {
      return nil, err
   }
   for k, v := range c.Header {
      req.Header.Set(k, v)
   }

   resp, err := c.Client.Do(req)
   if err != nil {
      return nil, err
   }
   defer func() {
      _ = resp.Body.Close()
   }()

   body, err := io.ReadAll(resp.Body)
   if err != nil {
      return nil, err
   }
   return body, nil
}

接下来我们sdk的核心代码就是对我们的业务接口调用方式进行封装：

（1）定义统一的请求体结构和错误码：

请求体：

type CreateRequest struct {
   Key string `json:"key,omitempty"`
   Val string `json:"val,omitempty"`
}

错误码：

type Err struct {
   Code int    `json:"code,omitempty"`
   Msg  string `json:"msg,omitempty"`
}

var (
   ErrOk         = Err{Code: 200, Msg: "ok"}
   ErrNotAuth    = Err{Code: 401, Msg: "not auth"}
   ErrRequestBad = Err{Code: 400, Msg: "request bad"}
   ErrInnerErr   = Err{Code: 500, Msg: "inner err"}
)

（2）sdk核心方法

const (
   defaultUsername = "barry"
   defaultPasswd   = "yan"
)

type SDK struct {
   Host   string
   User   string
   Passwd string
   header map[string]string
}

func NewSDK(host, userName, passWd string) (*SDK, error) {
   sdk := &SDK{
      Host:   host,
      User:   userName,
      Passwd: passWd,
   }
   if sdk.checkAuth() {
      sdk.header = map[string]string{"name": "barry yan"}
      return sdk, nil
   }
   return nil, errors.New("auth err")
}

func (s *SDK) checkAuth() bool {
   return s.User == defaultUsername && s.Passwd == defaultPasswd
}

func (s *SDK) Create(request CreateRequest) Err {
   path := "/create"

   bytes, err := json.Marshal(request)
   if err != nil {
      return ErrInnerErr
   }
   resp, err := NewHttpClient(fmt.Sprintf("%s%s", s.Host, path),
      WithBody(bytes),
      WithHeader(map[string]string{"name": "barry yan"})).Post()
   if err != nil {
      return ErrInnerErr
   }

   httpResp := &Err{}
   if err := json.Unmarshal(resp, httpResp); err != nil {
      return ErrInnerErr
   }
   if httpResp.Code != http.StatusOK {
      return *httpResp
   }
   return ErrOk
}

func (s *SDK) Get(key string) (string, Err) {
   path := "/get"

   resp, err := NewHttpClient(fmt.Sprintf("%s%s/%s", s.Host, path, key),
      WithHeader(map[string]string{"name": "barry yan"})).Get()
   if err != nil {
      return "", ErrInnerErr
   }
   return string(resp), ErrOk
}

3.4 SDK使用样例

import (
   "fmt"
   sdk "go-http-sdk"
   "net/http"
   "testing"
)

func TestSDKCreate(t *testing.T) {
   newSDK, err := sdk.NewSDK("http://localhost:9999", "barry", "yan")
   if err != nil && newSDK != nil {
      return
   }
   err1 := newSDK.Create(sdk.CreateRequest{Key: "D", Val: "1"})
   if err1.Code != http.StatusOK {
      fmt.Println(err1)
   }
}

func TestSDKGet(t *testing.T) {
   newSDK, err := sdk.NewSDK("http://localhost:9999", "barry", "yan")
   if err != nil && newSDK != nil {
      return
   }
   resp, err2 := newSDK.Get("D")
   if err2.Code != http.StatusOK {
      fmt.Println(err2)
   }
   fmt.Println(resp)
}

看，是不是感觉代码少了太多

4 小总结

到这里大家可能会产生疑问，为什么NewSDK的时候除了host还要带上username和passwd这两个参数。

其实主要是因为系统一般会有Auth认证的流程，主要是用于认证调用者是否为该系统的合法用户，API中的header（name=barry yan）也正是为了验证用户，当然实际一定是要比这个复杂的多，SDK也会有对Auth认证方式的封装。

除此之外，由于时间关系，本文中的这个SDK案例设计的确实过于简单，希望大家在真实的生产项目中不要照搬模仿，在这里提供几个比较好的SDK设计：

• aws-sdk-go
• tencentcloud-sdk-go
• alibaba-cloud-sdk-go

本文的全部代码也已经打包上传到Github，欢迎大家提出issue。