【編者按】本文作者為 Gal Lavinsky灰蛙，文中將列出10個(gè)零基礎(chǔ)小技巧腹缩，幫你創(chuàng)建完美的Java SDK。文章系國(guó)內(nèi) ITOM 管理平臺(tái) OneAPM 編譯呈現(xiàn)凛篙。以下為正文峦甩。

本文起源于筆者朋友的一次問詢赘来。他認(rèn)為现喳，關(guān)于如何寫好一個(gè)簡(jiǎn)單易用的SDK，沒有足夠的參考文件犬辰。

在過去的十年里嗦篱，SDK的使用在開發(fā)生命周期中已經(jīng)成為了重要的一部分。事實(shí)上幌缝，它的使用和在產(chǎn)品中的集成已經(jīng)如此常見灸促，可以說，相比于深度學(xué)習(xí)算法來自行實(shí)施涵卵，開發(fā)者們更需要學(xué)習(xí)大量框架以融會(huì)貫通浴栽。

本文主要面向想要學(xué)習(xí)書寫最佳SDK，并為之提供參考文檔的讀者缘厢。SDK的出發(fā)點(diǎn)是它的參考文檔應(yīng)當(dāng)是重點(diǎn)明確且清晰的吃度。如果你覺得文檔有多個(gè)重點(diǎn)甩挫，請(qǐng)考慮拆分為多個(gè)文檔贴硫。

以下是筆者希望能幫助你更好地構(gòu)建SDK并書寫其參考文檔的清單：

1. 了解墻外的世界

試著去關(guān)注你的競(jìng)爭(zhēng)對(duì)手或者與你相似領(lǐng)域的公司都做了什么。這可能會(huì)給你一些參考的角度伊者。采納你喜歡的地方英遭，改善你不喜歡的地方。

2. 簡(jiǎn)潔

代碼簡(jiǎn)潔——簡(jiǎn)潔的代碼意味著你的客戶用起來得心應(yīng)手亦渗。這可能包括盡可能減少與代碼交互的方式挖诸，比如只公開一個(gè)接口類；或是簡(jiǎn)短的方法簽名法精，比如少量的輸入?yún)?shù)多律，等等。

除了初始化階段（只發(fā)生一次且可能要求進(jìn)行配置）搂蜓，請(qǐng)讓SDK方法使用起來盡可能簡(jiǎn)單狼荞。

同樣地，請(qǐng)盡量減少方法簽名中的參數(shù)帮碰。

你可以通過提供默認(rèn)配置以及允許高級(jí)用戶進(jìn)行覆蓋的默認(rèn)實(shí)現(xiàn)類來達(dá)到這一目的相味。

隱藏用戶不需要使用的類和方法，比如殉挽，只將用戶必須使用的類/方法設(shè)定為公有的丰涉，否則就將它們的使用范圍設(shè)定為局部或者私有。一個(gè) IDEs 提供了代碼檢查與清除功能斯碌，可以幫你自動(dòng)實(shí)現(xiàn)這一點(diǎn)一死。

參考文檔簡(jiǎn)潔——讓你的文檔盡可能簡(jiǎn)單易懂。這意味著有時(shí)候你得多寫注釋傻唾，有時(shí)候又得盡量少寫投慈。內(nèi)聯(lián)樣本代碼通常很有幫助，因?yàn)榇蠖鄶?shù)人都是通過例子來學(xué)習(xí)的。

3. 提供簡(jiǎn)單的開始步驟

這是指一個(gè)人可以在五分鐘內(nèi)上手使用你的代碼逛裤。這一點(diǎn)非常重要瘩绒，因?yàn)榭蛻敉ＭM可能不費(fèi)力地進(jìn)行集成。除此之外带族，有時(shí)候客戶想要評(píng)估你的產(chǎn)品锁荔，但如果無法進(jìn)行簡(jiǎn)單的測(cè)試，他們就很可能選擇跳過你的產(chǎn)品蝙砌。

4. 短小精悍

保持簡(jiǎn)短主要是文檔的責(zé)任阳堕，但是同樣與用戶和SDK代碼的交互方式有關(guān)；為了保持文檔的簡(jiǎn)短择克，可以提供代碼樣例恬总、一目了然的方法名或使用默認(rèn)數(shù)據(jù)來實(shí)現(xiàn)。

5. 集成

請(qǐng)謹(jǐn)記客戶開發(fā)環(huán)境的多樣性肚邢。

比如說壹堰，如果你在寫一個(gè)安卓庫(kù)，它的集成方式在客戶使用Android Studio加gradle 框架和使用Eclipse集成開發(fā)環(huán)境時(shí)就非常不同骡湖。前者需要aar工件并發(fā)布到遠(yuǎn)程存儲(chǔ)庫(kù)中贱纠，而后者需要你提供jar文件，以及關(guān)于如何為SDK更改AndroidManifext.xml文件和獨(dú)立eclipse項(xiàng)目的指導(dǎo)响蕴。

這可能會(huì)影響你的構(gòu)建機(jī)制及其工件谆焊。然而，不要試圖取悅所有客戶浦夷，請(qǐng)先滿足你的第一位客戶辖试，或者預(yù)期中的大多數(shù)客戶的需求。

6. 項(xiàng)目示例

在GitHub上創(chuàng)建一個(gè)最基本的項(xiàng)目劈狐，模擬使用SDK包的用戶罐孝。

這可以向客戶展示你的產(chǎn)品如何滿足他們的需求，以及如何集成你的產(chǎn)品懈息。如果你想展示高級(jí)用法肾档，那就在另一個(gè)項(xiàng)目里進(jìn)行展示。通常辫继，客戶會(huì)將項(xiàng)目示例作為主要的參考文檔怒见，因此，請(qǐng)?zhí)峁┬袃?nèi)評(píng)論姑宽，并盡量用一目了然的方式書寫代碼遣耍。

7. 概述

在參考文檔的開頭，或是GitHub項(xiàng)目的README.md文件中炮车，請(qǐng)用直白的語言對(duì)你的解決方案進(jìn)行概述舵变。在此部分酣溃，筆者通常會(huì)提供一個(gè)使用樣例來解釋SDK的典型用法。如果有可能纪隙，請(qǐng)?zhí)峁┮粋€(gè)簡(jiǎn)單的表格或是圖表赊豌，這樣一來，不喜歡閱讀操作指南的用戶也可以快速了解該SDK的優(yōu)勢(shì)绵咱。

8. 初始化

使用在SDK域內(nèi)可接受的慣例碘饼。

這些慣例可能是可重載的構(gòu)造函數(shù)，某種構(gòu)建模式等悲伶。初始化應(yīng)當(dāng)巧妙地使用默認(rèn)值來簡(jiǎn)化流程艾恼。

9. 默認(rèn)值

默認(rèn)值對(duì)于保持代碼的簡(jiǎn)潔性和減少配置過程（見簡(jiǎn)潔性部分）是非常重要的。你所提供的默認(rèn)值（不管是在配置還是實(shí)施過程）應(yīng)該代表在你眼中大多數(shù)SDK用戶會(huì)進(jìn)行的操作麸锉。

你可以提供幾個(gè)方法重載钠绍，使最簡(jiǎn)單的簽名都可以用默認(rèn)值調(diào)用更高級(jí)的方法。

10. 發(fā)布

• 離線使用不可編輯模式——PDF花沉。優(yōu)勢(shì)是文檔創(chuàng)建簡(jiǎn)單柳爽，可以本地存儲(chǔ)在Dropbox中。并且對(duì)于每次發(fā)布主穗，版本可以自動(dòng)更新泻拦。
• 在線——你的企業(yè)網(wǎng)站。這是更推薦的方式忽媒。然而，在更新時(shí)可能會(huì)導(dǎo)致一些額外的IT開銷腋粥。

希望這些指南對(duì)你有所幫助晦雨。也歡迎進(jìn)行反饋。

OneAPM 能為您提供端到端的 Java 應(yīng)用性能解決方案隘冲，我們支持所有常見的 Java 框架及應(yīng)用服務(wù)器闹瞧，助您快速發(fā)現(xiàn)系統(tǒng)瓶頸，定位異常根本原因展辞。分鐘級(jí)部署奥邮，即刻體驗(yàn)，Java 監(jiān)控從來沒有如此簡(jiǎn)單罗珍。想閱讀更多技術(shù)文章洽腺，請(qǐng)?jiān)L問 OneAPM 官方技術(shù)博客。

本文轉(zhuǎn)自 OneAPM 官方博客

原文地址：http://blog.mobitech.io/2016/02/sdk-writing-guidelines.html覆旱。