2014年6月14日 星期六

一些關於 API 設計的碎碎念

平常可能寫 API 寫久了沒什麼感覺,但最近對於 API 設計感想特別多...碎碎念罷了。

1. 各種參數的 naming 如果沒有 consistent,在不同的 context 下會很容易造成混淆,譬如說同一個參數名稱在 A context 是某種 Type,B context 卻是另外一種 Type。

這樣的命名混淆,在一整個 process flow 裡面,一旦遇到不同的呼叫使用相同名稱卻在不同 context 有不同意義的參數,就會成為杯具。

再怎麼樣想不到適合的名字也不該用混淆的名字

2. 命名歸類的一致性: 譬如說某某 method 是 A 相關,可以 A 作為 prefix,那就不要突然 A 突然 B 突然又 C,否則誰知道是在幹嘛(丟鍵盤)

3. 函式命名沒有這麼難,就算不知道怎麼命名也至少用動詞加受詞 (V+OBJ) 吧,然後 OBJ 的名稱一定要一致,不要一下 memberInfo 一下 memberData 的。

4. 此外 method name 本身的命名應該要讓人能讀出 read-only / write 等資訊,而不是一個看起來明明是 read-only 的 API 本身卻包含了 write 的行為。

5. 參數類型、可選不可選、臨界值、長度、不同值所代表的隱含行為在文件上寫清楚也是相當重要的,否則呼叫方若誤解了參數所帶來的隱含操作,則會造成系統不穩定。

6. 另外參數名稱也請不要用 1234567 當 suffix 呀,若是為了安全性,你好歹也用英文縮寫。

7. 最後,至少寫個 persistent layer 的 test 吧,curl 腳本也行,不要一下噴 HTML 一下 XML 的,明明都送 Accept: text/xml 啦!