【轉載】大廠的 SDK 寫法，偷學到了！

title: 【轉載】大廠的 SDK 寫法，偷學到了！
date: 2021-09-09 10:13:00
comment: false
toc: true
category:

Java
tags:
轉載
Java
SDK
寫法
大廠
通用
工作
需要

本文轉載自：大廠的 SDK 寫法，偷學到了！ - 掘金

自己動手寫 SDK 的經驗技巧分享

大家好，我是魚皮。

最近因為工作需要，自己動手寫了一些項目的通用 SDK。在編寫的過程中，我閱讀和參考了不少公司中其他大佬寫的 SDK，也總結了一些開發 SDK 的經驗和技巧，給大家分享下～

在此之前，必須先給大家解釋一下啥是 SDK。

啥是 SDK ？#

SDK（Software Development Kit）即 軟體開發工具包 ，就是幫助我們開發出軟體的工具集合，除了程式碼之外，一般還要搭配文檔、示例等。

一般 SDK 都是需要引入到項目中使用的。比如學 Java 的朋友最早接觸的 JDK，就是用來開發 Java 軟體的工具包，使用時需要編寫類似 import java.util.* 的語法來引入。此外，大部分的 SDK，都是需要通過人工或項目管理工具，將其文件下載到指定路徑才能引入。

引入 SDK

使用 SDK 有什麼好處呢？#

舉個例子，假設公司有很多系統都需要實現文件上傳功能。之前看過我文章的朋友應該知道，一個優秀的文件上傳功能並不好做，要考慮很多點，比如分塊、斷點續傳、秒傳、文件存儲、文件管理等。

文件上傳設計：mp.weixin.qq.com/s/3QXe4MSOb…

顯然，我們不需要給每個系統都去開發文件上傳，而是只需要有一個團隊舍身而出，編寫一套 通用的 文件上傳 SDK，然後讓需要實現同樣功能的系統引用就行了，這樣就 大大減少了工作量、提高了開發效率 。

通用 SDK

有點前人造車，後人享樂的意思～

編寫 SDK 又稱 造輪子 ，好的輪子不僅能夠幫助團隊省時省力，還能夠減少一些項目在相同功能上的差異。就不要說同一個功能，小王寫的要運行 1 秒，小李寫的要運行 1 小時！

而假設每個系統都去開發同樣的功能，那就是 重複造輪子 ，在大多數情況下，不是明智之舉。

理解了啥是 SDK 後，來看看如何寫出優秀的 SDK 吧～

手寫 SDK 經驗總結#

好的 SDK 應該具有簡單易用、通俗易懂、便於擴展、高效穩定等特點。

易用性#

如今，現成的輪子實在太多了！如何讓你的輪子脫穎而出呢？那就要先提升 SDK 的易用性。

我自己在技術選型時，就會傾向於優先選擇簡單易用的 SDK，最好是幾行程式碼就能輕鬆使用，而不是必須要我讀完老長一份文檔，再寫個幾十行程式碼才能生效。

就和產品說明書一樣，太複雜直接把人勸退。

我們可以通過以下幾點提高易用性：

統一調用#

將複雜的功能進行封裝，對外提供統一的調用入口，盡量屏蔽一些實現細節，減少用戶調用的流程和對參數的理解成本。

舉個例子，下面是兩種日期處理函數。用戶不需要關心它們是如何實現的，只需要知道怎麼用、傳遞哪些參數、得到哪些返回值就行了。

// 第 1 種：需要 new 對象
DateUtils dateUtils = new DateUtils();
dateUtils.setDate('2021-08-31');
Date date = dateUtils.parse();

// 第 2 種：直接調用
Date date = DateUtils.parse('2021-08-13');

那大家覺得哪種更易用呢？

集中配置#

將複雜的參數配置化，不需要讓用戶到處寫參數，而是通過一個配置文件統一管理。

Java 主流開發框架 SpringBoot 就是典型的例子，假如用戶想改變內嵌伺服器啟動的端口、亦或是改變資料庫的連接地址，不需要寫程式碼，而是改一下配置文件就行了：

# 伺服器配置
server:
  port: 8081
# 資料庫配置
db:
	ip: 10.0.0.1

此外，這樣也便於維護項目和實現多環境。

良好命名#

給 SDK 的函數取名稱時，盡量讓它符合用戶的習慣。

比如具有解析功能的函數，可以叫 "parseXXX"；判斷是否為空的函數，可以叫 "xx.isEmpty" 等。最好能做到讓用戶不看文檔，只通過函數名稱和參數，就知道你這個函數是做什麼的。

好壞命名

因此，想要寫出好的 SDK，首先要多用、多參考別人的 SDK，養成習慣後你就會發現，大家起名兒都差不多。

但也要注意一點，如果可以，盡量不要讓你 SDK 中的類名（函數名）和別人的完全一致，否則可能給用戶帶來困擾：這麼多同名的函數，我該用哪個呢？哪個是你開發的 SDK 呢？

可理解性#

有時，用戶可能不滿足於簡單地使用你的 SDK，而是希望閱讀你的 SDK 源碼來進一步了解，用的才更放心。

因此，除了易用外，還要讓你的 SDK 便於理解，不能金玉其外敗絮其中。

這個就和編碼習慣有很大的關係了，無論是寫 SDK 也好，還是做項目也罷，都要做到以下幾點：

結構清晰#

把程式碼按照功能或類別進行整理，放到指定的目錄下。常見的做法有分包、分層等，讓人一眼就知道每個目錄下的文件的作用。

比如下面這個經典的 Java 項目結構，service 目錄是編寫業務邏輯的、constant 是存放常量的、utils 是存放工具類的等等，都很清晰：

Java MVC 項目結構

統一風格#

統一風格的目標很簡單：讓項目看起來是同一個人寫出來的。

比如程式碼縮進都用 4 個空格、命名都用駝峰式等。尤其是功能相似的程式碼，一定要保持命名和用法的統一！比如解析文本的函數，不要一會叫 "parseXXX"、一會兒又叫 "jiexiXXX"，給用戶都整樂了～

但實際上，團隊開發中，很難做到這點。因此才需要有一套通用的程式碼規範，大家都去遵守規範，才能讓項目更好理解、更便於維護。

編寫註釋#

最好給 SDK 中的每個類和函數的開頭都加上註釋，這樣用戶在使用 SDK 時，甚至都不需要看文檔，直接看程式碼註釋就能知道它是幹嘛的、怎麼用。

隨便打開 Java SDK 或者網上知名 SDK 中的一個函數，一般都能看到這些註釋，包括對函數功能的描述、參數含義、返回值含義等：

添加註釋

說明文檔#

除了註釋外，還要編寫一個說明文檔（用戶手冊），包括如何引入 SDK 、有哪些功能、應該怎麼使用等等，甚至還可以補充一些關鍵的實現細節、以及常見的問題列表。

這點也會極大地影響用戶的選擇。就我個人而言，沒有文檔的 SDK 我一般是不會選用的，萬一出了事我找誰呢？

可擴展性#

編寫 SDK 的一大難點是：不僅要考慮到大部分通用的使用場景，還要滿足小部分用戶定制化的需求。

因此，SDK 的可擴展性是很重要的，但怎麼提升呢？

輕量依賴#

一方面，我們可以盡量減少 SDK 本身對其他類庫的依賴。

舉個例子，假如你要做一個很輕小的工具類，可能只有幾十 KB，那就沒有必要再引入一個幾百 KB 的依賴庫了，得不償失！別人也不樂意用啊！

輕量依賴不僅可以減少 SDK 的體積，更關鍵的是可以減少依賴衝突的可能性。我自己也曾經遇到過很多次這樣的尷尬局面：引入一個工具類後，整個項目就跑不起來了！

自定義實現#

為了提高 SDK 的通用性和靈活性，在設計 SDK 時，除了提供默認實現外，建議提供一個通用接口或抽象類，讓用戶來繼承，編寫自己的實現方式。

舉個例子，假設我們要編寫一個日期解析類，默認的解析規則是按照短橫分割字串：

// 按照 '-' 切分
date = DateUtils.parse('2021-01-18')

如果只能做到這點，那這個 SDK 就很死板。因為用戶可能想按照冒號或其他規則來解析。

怎麼實現呢？

我們可以允許用戶自己傳入分割字符：

// 按照 '-' 切分
parseRule = ':'
date = DateUtils.parse('2021-01-18', parseRule)

還可以讓用戶自己來控制解析的方式：

// 自定義解析器
interface MyParser extends Parser {
  // 需要用戶自己實現
  void doParse();
}
// 指定解析器
date = DateUtils.parse('2021-01-18', MyParser.class);

這兩種方式在 SDK 的設計中屢見不鮮，此外還可以讓用戶自行編寫或指定配置文件，也能提高靈活性。

高效穩定#

其實，開發 SDK，尤其是在大廠開發 SDK，是個很 “坑” 的工作，我相信做過的朋友會感同身受。

因為隨著使用你 SDK 的用戶越來越多，可能會發現各種各樣莫名其妙的問題；而且 SDK 作為相對底層的依賴，對使用方的影響也是無法估量的。所以，不想經常加班改 Bug 的話，就要保證你 SDK 的穩定性。

我們需要注意以下幾點：

1. 測試#

為了保證每個功能都是正常的，我們可以編寫 單元測試 （UT）來最大程度上地覆蓋 SDK 的功能和程式碼。

尤其是每次改動程式碼後、發布新版本之前，都要再完整地執行一遍測試，不要盲目自信。

接口測試報告

此外，還可以通過 壓力測試 來估算 SDK 的執行效率，比如每秒最多同時執行 3 次、每次要執行 500 毫秒等。建議將這些信息補充到說明文檔中，給用戶一些預期。當然也可以嘗試通過壓測來優化 SDK 的性能。

2. 兼容性#

重要的函數和接口盡量減少改動，尤其是函數名、入參和返回值！

舉個例子，SDK 0.1 版本時，函數的定義是這樣的：

boolean isValid(String str)

結果突然在 0.2 版本時改成了：

String checkValid(StringBuilder str)

這樣就會導致用戶升級時一臉懵逼，怎麼報了一堆找不到函數呢？

因此，對於比較大的改動，可以新寫一個函數，並且給老函數打上類似 @Deprecated 的註釋，表示已過時，引導用戶去用新的。

此外，還可以在 版本號 上做做文章，小改動時只改變小版本號，比如 0.0.1 到 0.0.2；大改動時才改變大版本號，比如 1.0 到 2.0。這樣可以給用戶一個預期：這次改動很大，可能會存在不兼容。

3. 暴露異常#

要讓用戶感知到 SDK 程式碼中可能拋出的異常，交給他們去進行相應的處理，防止出現一些意料之外的錯誤。

此外，SDK 要合理地打印日誌，尤其是異常日誌，在出了問題時要讓調用者知道是出了什麼問題，便於排查。