如何設計一個良好的API?

要明確
這也許是最重要一點。如果你有一個方法getUser，如果不明確它可能引起一些副作用，最終會導致很多問題。比如getUser明確的只是返回一個使用者，不會對使用者的id進行增加。

儘可能多的提供更多的行為。不要指望使用者會潛水你的原始碼，以發現隱藏的行為。

讓a p i表面積儘可能小
沒有人喜歡臃腫的程式，如果你能夠暴露更少的api就能完成工作，這對於每個人都是一個很好的體驗。

是否人們真的要求你寫這個新的api？一直到它是一個真正需要有人去解決的問題的時候，你才可以去做它。

減少樣板
儘可能的在內部處理各種細節，以減少客戶端的負擔。客戶端呼叫的時候做的越少，漏洞才可能越少。

喜歡乾淨的程式碼?那就保持你的api很乾淨，那麼，你的api的客戶呼叫就會很簡潔。

降低依賴
儘可能的保證你的程式碼人自我封閉，你有更多的依賴，就意味著潛在的問題會影響到下游程式碼。

如果你希望從另外一個模組裡，獲取一塊功能，那麼儘可能的只提取你需要的。在程式碼重用和緊耦合和之間有一個平衡，如果功能比較小，那麼就值得你自己重新實現它。

返回有意義的錯誤狀態
返回null是毫無意義的，他什麼也意味不了。錯誤資訊要能夠有可以進行改善的提示。Error.USER_NOT_CREATED 或Error.USER_DELETED都是有意義的。

異常應該有真正的含義
如果你使用的語言沒有異常，祝賀你，函式式語言在提供有意義的錯誤狀態方面會做的更好。

一場已經在java領域被濫用，getUser時如果沒有發現使用者，不要拋UserNotFoundException,而是返回一個正常的錯誤狀態。
比一個蹦潰的程式更壞的事情是，不要因為一個不確定的狀態導致崩潰。

對所有的事情要建立文件
文件是無聊的，但必不可少，良好的文件會儲存你的理智思考，會避免api消費的很多問題。

一個好的文件包括：
1.有關模組是如何工作的高層次概述
2.公共方法和介面的javadoc
3.如何使用api的案例

不是所有的抽象都需要文件的,一些小類就不需要案例程式碼。
文件必須是演進，如果有很多問題問同樣的事情，你就可能需要把它加到文件裡。

太多的文件也是浪費時間，因為你必須保持不斷的更新，但是如果仍沒有人使用，它就沒有什麼價值，所以要保證足夠的重點和適當的文件。

編寫測試
這是是正確性的證明，文件和示例程式碼都可以包括進去。它為中國提供了巨大的價值，能夠讓你在事情改變時候，很自信的快速移動。

那些想對你的api實現深入研究的人總是，透過閱讀測試實現的，能夠更多的瞭解你的程式碼行為和意圖。這些都是文件無法實現的。

變得可測試
測試你的程式碼是一回事兒，讓人們對你的api更容易地編寫測試程式碼又是另外一回事兒。

你需要有針對除錯和產品環境的不同配置。

允許使用者選擇
不是每一個客戶端都以同樣的方式呼叫你的api，有些人可能喜歡同步呼叫，而另外一些人更喜歡一部回撥。

讓使用者選擇他們自己喜歡的方式，你的api就更容易整合到他們現有的程式設計環境中，更可能地被使用。

不要給使用者太多的選擇
不要給使用者太多的選擇，否則他們就有選擇障礙，總是提供合理的預設行為，也就是你的api預設的使用方式。

api應該鼓勵規範行為，不要讓消費者修改內部狀態，如果你無意中暴露一些怪異的行為，它會產生一些不可預見的後果。

給出態度的選擇就會失去重點，在正確和靈活之間要進行平衡和選擇。

總之，設計一個api是一種藝術，需要更多的實踐。

How to design APIs that don’t suck

[該貼被banq於2016-10-24 16:29修改過]