自己動手寫 SDK 的經驗技巧分享
大家好，我是魚皮。
最近因為工作需要，自己動手寫了一些項目的通用 SDK。在編寫的過程中，我閱讀和參考了不少公司中其他大佬寫的 SDK，也總結了一些開發 SDK 的經驗和技巧，給大家分享下~
在此之前，必須先給大家解釋一下啥是 SDK。
啥是 SDK ？
SDK（Software Development Kit）即 軟件開發工具包 ，就是幫助我們開發出軟件的工具集合，除了代碼之外，一般還要搭配文檔、示例等。
一般 SDK 都是需要 引入 到項目中使用的。比如學 Java 的朋友最早接觸的 JDK，就是用來開發 Java 軟件的工具包，使用時需要編寫 類似 import java.util.* 的語法來引入。此外，大部分的 SDK，都是需要通過人工或項目管理工具，將其文件下載到指定路徑才能引入。
使用 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 是存放工具類的等等，都很清晰：
統一風格
統一風格的目標很簡單：讓項目看起來是同一個人寫出來的。
比如代碼縮進都用 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 要合理地打印日志，尤其是異常日志，在出了問題時要讓調用者知道是出了什么問題，便於排查。
以上就是本期分享，建議學編程的同學多自己動手寫 SDK，並且按照本文的總結去優化它，對提升編程能力真的很有幫助！
最近整理了我原創的 140 篇編程經驗和技術文章，歡迎大家閱讀，一起成長！⛽️
我是魚皮，最后求個 點贊 ，這將是我持續創作的最大動力，謝謝 🙏