設計優秀的 API 有什麼特徵？

01-05

一看就會，用了就爽，想啥是啥，要啥有啥。

=========================================

舉個栗子，LINQ to XML的API：

一看就會：

var element = document.Element( "Root" ); var attribute = element.Attribute( "name" );

用了就爽：

document.Add( new XElement( new XAttribute( "name", "winter" ) ) );

想啥是啥：

element.Attribute( "name" ).Remove();

要啥有啥：

foreach ( var element in document.Descendants() )

反例就是HTML DOM API，原生的JS寫的有多痛苦前端都知道。

=========================================

jQuery的API的確也是非常優秀的一個API，尤其在JS這種語言上實現的如此美妙實屬不易。但老實說jQuery仍然有一些學習成本（選擇器？），有些東西受限於JS這個語言也很難設計的完美（基於事件的非同步處理）。

會讓錯誤使用它的代碼變醜

不邀自來。

我2年半曾有一個演講探討這個話題，視頻在此：

JavaScript API設計的思考兩三例 01

JavaScript API設計的思考兩三例 02

JavaScript API設計的思考兩三例 03

Slides在此：JavaScript之API設計的思考兩三例

這個演講當時還不算非常成熟，後面的例子有許多改善餘地，不過基本框架還是ok的，那就是優秀API的關鍵點：針對性無緒。評價API好壞的標準包括：可理解性、一致性、可見性、簡單性、保護投資（兼容性）。

設計公共API的六個注意事項-CSDN.NET

我以為這個說的已經很好了

順便吐槽一個反例，是今天遇到的。

正常人設計一個回調函數，心路歷程是這樣的：

」某個條件觸發之後告訴我一下呦~「

——」好的親~「

然後，今天我遇到的某公司的開放平台API是這樣的：

」某個條件觸發之後告訴我一下呦~「

——」好的親~「

」咦？怎麼觸發了你沒有反應？「

——」親，當條件觸發的時候，你要通知我去通知你才行哦~！「

我(╯‵□′)╯︵┻━┻

要不是打不過人家……我就動手了……

--------------------

有很多人說這是輪詢，我想說的是……如果是輪詢的話，為何要一開始設置Listener？我自己輪詢請求狀態不就結了？這分明就是不遵守正常人類思路的設計方案嘛。

1、介面得有一個望文生義的名字，明確的功能、參數、返回值描述；

2、介面功能單一化，我們不需要全能介面，同時組合優於繼承；

3、介面需要泛型化、模板化；

4、介面參數驗證必不可少，同時異常等返回信息得全面，讓調用者明確異常原由；

5、介面行為一致性，不可變性；

6、介面參數、返回值需要具備類型安全特徵；

7、介面參數個數限制，如果參數過多可以用輔助類；

弱類型語言天生不適合用來提供介面，強類型支持泛型、異常機制的語言比較適合用來提供介面。

jquery確實不錯。不算黑，就素這種設計最牛逼了。單介面+小型dsl，滿足你在該領域的一切需求：）

精於心，簡於形

Almost nothing compares to the APIs of Rails on Rails (Ruby).

1. Beyond your imagination (Though it"s not Rails code, it shows the sexyness of Ruby)

10.times { puts "Hi" }

2. Sexy syntax sugar

2.days.ago

3. More natural way

class Subject &< ActiveRecord::Base has_many :pages validates_presence_of :name validates_length_of :name, :maximum =&> 255


  scope :visible, lambda {where(:visible =&> true)}

  scope :invisible, lambda {where(:visible =&> false)}

  scope :sorted, lambda {order("subjects.position ASC")}

  scope :newest_first, lambda{order("subjects.created_at DESC")}

  scope :search, lambda{|query|

    where(["name LIKE ?", "%#{query}%"])

  }

end

3. Plural and singular, don"t worry about that

irb(main):020:0&> Subject.first.pages.first.sections


  Subject Load (0.4ms)  SELECT `subjects`.* FROM `subjects` ORDER BY `subjects`.`id` ASC LIMIT 1
  Page Load (0.5ms)  SELECT `pages`.* FROM `pages` WHERE `pages`.`subject_id` = 1 ORDER BY `pages`.`id` ASC LIMIT 1
  Section Load (0.2ms)  SELECT `sections`.* FROM `sections` WHERE `sections`.`page_id` = 1

=&> #&]&>

4.URL pattern? Can"t be simpler

resources :posts do resources :comments end

And it marches on and on...

可簡，可繁，可小，可大

You haven"t built a good API until developers can surprise you.

—— Alan Eustace

符合人類直覺
符合語言慣例
符合其他慣例

重要性遞減排序

import json

json.loads()

代碼簡潔，兼容性高，調用穩定

注釋詳細介面名要直觀參數合理簡單