這是有關(guān)RESTful web API的設(shè)計技巧苏章。無論你是在寫一個開源庫或者內(nèi)部sdk请垛，甚至只是一個單獨的內(nèi)核模塊暑椰，下面的這些技巧應(yīng)該是有幫助的餐抢。要明確這也許是最重要一點现使。如果你有一個方法getUser，如果不明確它可能引起一些副作用旷痕，最終會導(dǎo)致很多問題碳锈。比如getUser明確的只是返回一個用戶，不會對用戶的id進行增加欺抗。盡可能多的提供更多的行為售碳。不要指望用戶會潛水你的源碼，以發(fā)現(xiàn)隱藏的行為绞呈。讓a p i表面積盡可能小沒有人喜歡臃腫的程序贸人，如果你能夠暴露更少的api就能完成工作，這對于每個人都是一個很好的體驗佃声。是否人們真的要求你寫這個新的api艺智？一直到它是一個真正需要有人去解決的問題的時候，你才可以去做它圾亏。減少樣板盡可能的在內(nèi)部處理各種細節(jié)十拣，以減少客戶端的負擔≈揪椋客戶端調(diào)用的時候做的越少夭问，漏洞才可能越少。喜歡干凈的代碼?那就保持你的api很干凈曹铃，那么缰趋，你的api的客戶調(diào)用就會很簡潔。降低依賴盡可能的保證你的代碼人自我封閉铛只，你有更多的依賴埠胖，就意味著潛在的問題會影響到下游代碼。如果你希望從另外一個模塊里淳玩，獲取一塊功能直撤，那么盡可能的只提取你需要的。在代碼重用和緊耦合和之間有一個平衡蜕着，如果功能比較小谋竖，那么就值得你自己重新實現(xiàn)它红柱。返回有意義的錯誤狀態(tài)返回null是毫無意義的，他什么也意味不了蓖乘。錯誤信息要能夠有可以進行改善的提示锤悄。Error.USER_NOT_CREATED 或Error.USER_DELETED都是有意義的。異常應(yīng)該有真正的含義如果你使用的語言沒有異常嘉抒，祝賀你零聚，函數(shù)式語言在提供有意義的錯誤狀態(tài)方面會做的更好。一場已經(jīng)在java領(lǐng)域被濫用些侍，getUser時如果沒有發(fā)現(xiàn)用戶隶症，不要拋UserNotFoundException,而是返回一個正常的錯誤狀態(tài)。比一個蹦潰的程序更壞的事情是岗宣，不要因為一個不確定的狀態(tài)導(dǎo)致崩潰蚂会。對所有的事情要建立文檔文檔是無聊的，但必不可少耗式，良好的文檔會保存你的理智思考胁住，會避免api消費的很多問題。一個好的文檔包括：1.有關(guān)模塊是如何工作的高層次概述2.公共方法和接口的javadoc3.如何使用api的案例不是所有的抽象都需要文檔的,一些小類就不需要案例代碼刊咳。文檔必須是演進彪见，如果有很多問題問同樣的事情，你就可能需要把它加到文檔里芦缰。太多的文檔也是浪費時間企巢，因為你必須保持不斷的更新，但是如果仍沒有人使用让蕾，它就沒有什么價值浪规，所以要保證足夠的重點和適當?shù)奈臋n。編寫測試這是是正確性的證明探孝，文檔和示例代碼都可以包括進去笋婿。它為中國提供了巨大的價值，能夠讓你在事情改變時候顿颅，很自信的快速移動缸濒。那些想對你的api實現(xiàn)深入研究的人總是，通過閱讀測試實現(xiàn)的粱腻，能夠更多的了解你的代碼行為和意圖庇配。這些都是文檔無法實現(xiàn)的。變得可測試測試你的代碼是一回事兒绍些，讓人們對你的api更容易地編寫測試代碼又是另外一回事兒捞慌。你需要有針對調(diào)試和產(chǎn)品環(huán)境的不同配置。允許用戶選擇不是每一個客戶端都以同樣的方式調(diào)用你的api柬批，有些人可能喜歡同步調(diào)用啸澡，而另外一些人更喜歡一部回調(diào)袖订。讓用戶選擇他們自己喜歡的方式，你的api就更容易集成到他們現(xiàn)有的編程環(huán)境中嗅虏，更可能地被使用洛姑。不要給用戶太多的選擇不要給用戶太多的選擇，否則他們就有選擇障礙皮服，總是提供合理的默認行為楞艾，也就是你的api默認的使用方式。api應(yīng)該鼓勵規(guī)范行為冰更，不要讓消費者修改內(nèi)部狀態(tài)产徊，如果你無意中暴露一些怪異的行為，它會產(chǎn)生一些不可預(yù)見的后果蜀细。給出態(tài)度的選擇就會失去重點，在正確和靈活之間要進行平衡和選擇戈盈〉煜危總之，設(shè)計一個api是一種藝術(shù)塘娶，需要更多的實踐归斤。
如何設(shè)計一個良好的API?
最后編輯于 ：
?著作權(quán)歸作者所有,轉(zhuǎn)載或內(nèi)容合作請聯(lián)系作者
- 文/潘曉璐 我一進店門，熙熙樓的掌柜王于貴愁眉苦臉地迎上來疏哗，“玉大人呛讲，你說我怎么就攤上這事》捣睿” “怎么了贝搁？”我有些...
- 文/不壞的土叔 我叫張陵，是天一觀的道長芽偏。 經(jīng)常有香客問我雷逆，道長，這世上最難降的妖魔是什么哮针？ 我笑而不...
- 正文 為了忘掉前任关面，我火速辦了婚禮坦袍，結(jié)果婚禮上，老公的妹妹穿的比我還像新娘等太。我一直安慰自己抗愁，他們只是感情好，可當我...
- 文/花漫 我一把揭開白布撵割。 她就那樣靜靜地躺著哗讥，像睡著了一般。 火紅的嫁衣襯著肌膚如雪瞻想。 梳的紋絲不亂的頭發(fā)上压真，一...
- 文/蒼蘭香墨 我猛地睜開眼呵俏，長吁一口氣：“原來是場噩夢啊……” “哼堆缘！你這毒婦竟也來了？” 一聲冷哼從身側(cè)響起普碎，我...
- 正文 年R本政府宣布，位于F島的核電站猿涨，受9級特大地震影響握童，放射性物質(zhì)發(fā)生泄漏。R本人自食惡果不足惜叛赚，卻給世界環(huán)境...
- 文/蒙蒙 一澡绩、第九天 我趴在偏房一處隱蔽的房頂上張望稽揭。 院中可真熱鬧，春花似錦肥卡、人聲如沸溪掀。這莊子的主人今日做“春日...
- 文/蒼蘭香墨 我抬頭看了看天上的太陽揪胃。三九已至，卻和暖如春氛琢，著一層夾襖步出監(jiān)牢的瞬間喊递，已是汗流浹背。 一陣腳步聲響...
推薦閱讀更多精彩內(nèi)容
- Spring Cloud為開發(fā)人員提供了快速構(gòu)建分布式系統(tǒng)中一些常見模式的工具（例如配置管理，服務(wù)發(fā)現(xiàn)即供，斷路器定拟，智...
- Android 自定義View的各種姿勢1 Activity的顯示之ViewRootImpl詳解 Activity...
- 發(fā)現(xiàn) 關(guān)注 消息 iOS 第三方庫、插件逗嫡、知名博客總結(jié) 作者大灰狼的小綿羊哥哥關(guān)注 2017.06.26 09:4...
- 曾經(jīng)一篇美國報道指出青自，20世紀90年代中年人失業(yè)的可能性大約是80年代初的兩倍，而且狀況越來越糟驱证，而這些事情在今天...
- 熟悉的感覺 最近兩年IP劇大熱抹锄，一大波的青春偶像瑪麗蘇劇撲面而來逆瑞，畫風(fēng)驚奇。作為一個新時代的女性伙单，追劇乃日常生活之...
