原 文：How to design APIs that don’t suck
譯 文：SDK.cn
作 者：魯行云（編譯）
你設(shè)計的API，很可能會被其他開發(fā)者所使用。因此不要讓你的API用起來讓人感到痛苦。如果你不想讓其他開發(fā)者在背后罵你的話，那就把你的API設(shè)計好。
在這些年中，我積累了一些API設(shè)計的技巧。我把它們進(jìn)行了總結(jié)。
詳盡
這一條是最重要的技巧。假如你的API中一個名叫g(shù)etUser的方法，它會引起一些副作用，如果你沒有詳細(xì)說明的話，它會引發(fā)很多問題。
在沒有詳盡說明的情況下，不要調(diào)整那些共享可變狀態(tài)。如果我調(diào)用getUser，我只是期望它會返回一個用戶，并不想引發(fā)其它作用。你也可以考慮使用不可變的數(shù)據(jù)結(jié)構(gòu)。
在給方法/類/模塊起名的時候，盡可能的在名字中詳盡的表明其行為。不要以為用戶會去在源代碼中搜索它們的隱藏行為。
“API軍團(tuán)”的規(guī)模越小越好
沒有人喜歡臃腫的程序。在完成一個項目的時候，所使用的API數(shù)量越小，開發(fā)者和用戶的體驗越好。
加入你想寫一個新的API，先考慮一下，是否真的有人希望你寫它？如果這個API所解決的并不是人們特別想馬上解決的問題，那你就可以暫時拖延這個計劃。
一些環(huán)境（例如安卓）會限制應(yīng)用所使用的方法數(shù)量，這一點(diǎn)你應(yīng)該牢記。
減少boilerplate
盡可能多的處理好部署細(xì)節(jié)，能夠減少用戶的負(fù)擔(dān)。用戶所做的事情越少，你用來修復(fù)bug的時間也就越少。
這里還有一個美學(xué)的問題。寫太多的boilerplate會讓完美的API也變成糟糕的API。我們都喜歡簡潔的代碼，當(dāng)用戶在使用你的API時，你應(yīng)該幫他們保持代碼的簡潔性。
減少依賴
不要讓你的代碼有太多的依賴。因為依賴越多，出現(xiàn)問題的可能性就越高。
如果你真的想要使用其他模塊的某個功能，你可以嘗試將這個功能提取出來，只用這個你想要的功能，其他無關(guān)功能完全拋棄。
出錯提示要讓人看得懂
在給用戶彈出錯誤提示的時候，只顯示一個null是毫無意義的做法。
這種提示根本無法讓用戶知道哪里出了問題，也無法讓他們找到解決辦法。你完全可以給出讓人能看得懂的錯誤提示，例如：
Error.USER_NOT_CREATED或是Error.USER_DELETED
在可能的時候，你也可以在錯誤提示中給出相應(yīng)的解決辦法。
做好說明文檔
沒錯，寫文檔是件無聊的事情。但是和許多無聊的事情一樣，它是必不可少的東西。好的文檔能夠讓你省下很多時間。文檔寫的好，用戶就可以自己找到問題的答案，他們不再需要來詢問你。
好的文檔應(yīng)該包含以下內(nèi)容：
- 整個模塊的總覽和其工作方式
- Javadocs, Heredocs, Rdocs等公共方法和協(xié)議
- 充當(dāng)使用說明的樣本代碼
而且文檔也需要定期升級。如果好多用戶一直在就一個問題對你進(jìn)行提問，你可以考慮將這個問題添加在未來的文檔中。
寫好測試
測試是API開發(fā)中必不可少的一環(huán)。在你對API做出改變的時候，測試能告訴你新的東西是否能正常運(yùn)作。
對于那些想要更加深入了解你API的用戶來說，他們也可以通過測試報告來了解代碼的行文。文檔無法覆蓋API的所有東西，這是就需要使用測試報告來補(bǔ)充。
你可能會問：“既然都寫了測試報告了，為何還要寫說明文檔？”打個比方吧，如果說文檔是用戶手冊的話，那么測試報告就是x86操作碼指令參考。
讓API本身可測試
測試你自己寫的代碼是一回事，讓你的API可以被其他用戶測試，則是另一回事。對于那些特別重視測試的開發(fā)者來說，如果你的API很難進(jìn)行測試，他們就會非常惱火。
給用戶一定的選擇
每一個用戶使用API的方式都不一樣。一些人偏好同步調(diào)用，另一些人則喜歡異步調(diào)用。
你要讓用戶有一定的選擇權(quán)，讓他們自己選擇使用方法。API與用戶程序整合的方式越多，他們使用的意愿就越高。
但是不要給用戶太多的選擇
但是也不要一次性給用戶太多選擇，否則他們在使用的時候就會遇到選擇恐懼癥。分析一下人們使用你API時最主要的使用方法，然后將其設(shè)為默認(rèn)行為。
你需要有一定的態(tài)度，不要因為給了用戶太多選擇，而讓你的API失去重心。
總結(jié)
API的設(shè)計有點(diǎn)像是藝術(shù)。希望我給出的這些技巧能幫你設(shè)計出更好的API.
