大家好，我是魚皮。

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

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

啥是 SDK ？

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

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

引入 SDK

使用 SDK 有什么好處呢？

舉個例子，假設(shè)公司有很多系統(tǒng)都需要實現(xiàn)文件上傳功能。之前看過我文章的朋友應(yīng)該知道，一個優(yōu)秀的文件上傳功能并不好做，要考慮很多點，比如分塊、斷點續(xù)傳、秒傳、文件存儲、文件管理等。

文件上傳設(shè)計：https://mp.weixin.qq.com/s/3QXe4MSObJTP43M2gXWSlA

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

通用 SDK

有點前人造車，后人享樂的意思~

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

而假設(shè)每個系統(tǒng)都去開發(fā)同樣的功能，那就是 重復(fù)造輪子 ，在大多數(shù)情況下，不是明智之舉。

理解了啥是 SDK 后，來看看如何寫出優(yōu)秀的 SDK 吧~

手寫 SDK 經(jīng)驗總結(jié)

好的 SDK 應(yīng)該具有簡單易用、通俗易懂、便于擴展、高效穩(wěn)定等特點。

易用性

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

我自己在技術(shù)選型時，就會傾向于優(yōu)先選擇簡單易用的 SDK，最好是幾行代碼就能輕松使用，而不是必須要我讀完老長一份文檔，再寫個幾十行代碼才能生效。

就和產(chǎn)品說明書一樣，太復(fù)雜直接把人勸退。

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

統(tǒng)一調(diào)用

將復(fù)雜的功能進行封裝，對外提供統(tǒng)一的調(diào)用入口，盡量屏蔽一些實現(xiàn)細節(jié)，減少用戶調(diào)用的流程和對參數(shù)的理解成本。

舉個例子，下面是兩種日期處理函數(shù)。用戶不需要關(guān)心他們是如何實現(xiàn)的，只需要知道怎么用、傳遞哪些參數(shù)、得到哪些返回值就行了。

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

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

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

集中配置

將復(fù)雜的參數(shù)配置化，不需要讓用戶到處寫參數(shù)，而是通過一個配置文件統(tǒng)一管理。

Java 主流開發(fā)框架 SpringBoot 就是典型的例子，假如用戶想改變內(nèi)嵌服務(wù)器啟動的端口、亦或是改變數(shù)據(jù)庫的連接地址，不需要寫代碼，而是改一下配置文件就行了：

# 服務(wù)器配置
server:
  port: 8081
# 數(shù)據(jù)庫配置
db:
 ip: 10.0.0.1

此外，這樣也便于維護項目和實現(xiàn)多環(huán)境。

良好命名

給 SDK 的函數(shù)取名稱時，盡量讓它符合用戶的習(xí)慣。

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

好壞命名

因此，想要寫出好的 SDK，首先要多用、多參考別人的 SDK，養(yǎng)成習(xí)慣后你就會發(fā)現(xiàn)，大家起名兒都差不多。

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

可理解性

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

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

這個就和編碼習(xí)慣有很大的關(guān)系了，無論是寫 SDK 也好，還是做項目也罷，都要做到以下幾點：

結(jié)構(gòu)清晰

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

比如下面這個經(jīng)典的 Java 項目結(jié)構(gòu)，service 目錄是編寫業(yè)務(wù)邏輯的、constant 是存放常量的、utils 是存放工具類的等等，都很清晰：

Java MVC 項目結(jié)構(gòu)

統(tǒng)一風(fēng)格

統(tǒng)一風(fēng)格的目標很簡單：讓項目看起來是同一個人寫出來的。

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

但實際上，團隊開發(fā)中，很難做到這點。因此才需要有一套通用的代碼規(guī)范，大家都去遵守規(guī)范，才能讓項目更好理解、更便于維護。

編寫注釋

最好給 SDK 中的每個類和函數(shù)的 開頭 都加上注釋，這樣用戶在使用 SDK 時，甚至都不需要看文檔，直接看代碼注釋就能知道它是干嘛的、怎么用。

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

添加注釋

說明文檔

除了注釋外，還要編寫一個說明文檔（用戶手冊），包括如何引入 SDK 、有哪些功能、應(yīng)該怎么使用等等，甚至還可以補充一些關(guān)鍵的實現(xiàn)細節(jié)、以及常見的問題列表。

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

可擴展性

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

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

輕量依賴

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

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

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

自定義實現(xiàn)

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

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

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

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

怎么實現(xiàn)呢？

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

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

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

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

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

高效穩(wěn)定

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

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

我們需要注意以下幾點：

1. 測試

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

尤其是每次改動代碼后、發(fā)布新版本之前，都要再完整地執(zhí)行一遍測試，不要盲目自信。

接口測試報告

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

2. 兼容性

重要的函數(shù)和接口盡量減少改動，尤其是函數(shù)名、入?yún)⒑头祷刂担?/p>

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

boolean isValid(String str)

結(jié)果突然在 0.2 版本時改成了：

String checkValid(StringBuilder str)

這樣就會導(dǎo)致用戶升級時一臉懵逼，怎么報了一堆找不到函數(shù)呢？

因此，對于比較大的改動，可以新寫一個函數(shù)，并且給老函數(shù)打上類似 @Deprecated 的注釋，表示已過時，引導(dǎo)用戶去用新的。

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

3. 暴露異常

要讓用戶感知到 SDK 代碼中可能拋出的異常，交給他們?nèi)ミM行相應(yīng)的處理，防止出現(xiàn)一些意料之外的錯誤。

此外，SDK 要合理地打印日志，尤其是異常日志，在出了問題時要讓調(diào)用者知道是出了什么問題，便于排查。

以上就是本期分享，建議學(xué)編程的同學(xué)多自己動手寫 SDK，并且按照本文的總結(jié)去優(yōu)化它，對提升編程能力真的很有幫助！

最近整理了我原創(chuàng)的 140 篇編程經(jīng)驗和技術(shù)文章，歡迎大家閱讀，一起成長！??

指路：https://t.1yb.co/ARnD