對接xx業務時，xx業務具備的功能和api全靠跑業務負責人那反覆逐個詢問、確認。用哪個api；怎麼用；有沒有限制；等等
各個業務間，甚至同一業務內，api風格不統一。
xx業務api效能方面未知。
隨著業務的演進，開放的api持續在增加，但類同的很多
api編碼規範迫在眉睫
自解釋
易學習
易使用
難誤用
不是隨便乙個功能就要有個介面，也不是隨便乙個需求就要加個介面。
每新建乙個介面，要有充分的理由和考慮，即這個介面的存在是十分有意義和價值的。無意義的介面不僅增加了維護的難度，更重要是對於程式的可控性的大大降低，介面也會十分臃腫。
設計介面時，分析的角度要統一。否則會造成介面結構的混亂。例如：不要一會以角色的角度設計，一會兒就要以功能的角度設計。
推薦：以"屬性物件 + 行為"的視角定義api
每個api介面應該只專注一件事，並做好。產品概念簡單、關係清楚。功能模稜兩可，諸多特殊邏輯的api肯定不是個優雅的api，且會造成功能類似重複的api。
注：如果api它很難命名，那麼這或許是個不好的徵兆，好的名稱可以驅動開發、並且只需拆分與合併模組即可。
功能大而全的api在靈活性、簡單性方面肯定捉襟見肘。定義api的粒度之前，建議先將業務分領域、劃邊界，以此來提取業務物件，然後再根據業務物件用例來設計單一功能的api。
比如：查詢會員，可能除了查詢會員表外還要獲取該會員的其他必要資訊，但不要在查詢會員的同時還有修改許可權等類似的其他業務功能，應該分成兩個介面執行。
介面設計簡單、清晰。api執行的功能可以很豐富、很強大，但api宣告和用法一定要盡量的簡單，不能將功能的豐富通過複雜的用法來實現，這會導致api功能不單一，演進不可控。
最終的評審要看api的簡單易用程度。
編寫的**一定要易於讀、易於理解，這樣別人才會欣賞，也能夠給你提出合理化的建議。相反，若是繁雜難解的程式，其他人總是會避而遠之的。
api的入參、出參所述的物件、屬性，一定是按業務特性進行抽象後的實體。誤將底層資料模型概念如實的反應到api上。抽象api、抽象物件實體更巨集觀，具有更好的適用性、相容性、擴充套件性。
對擴充套件開放，對修改關閉。保證api的向後相容。
擴充套件引數應當是便利的，保證後續類似的需求，可以在已有的api上通過相容擴充套件的方式實現。
**應該盡可能減少讓讀者驚喜。業務api只需根據需求來設計即可，不需要刻意去設計一下複雜無用、華而不實的api，以免弄巧成拙。
api應該減少對其他業務**的依賴關係。低耦合往往是完美結構系統和優秀設計的標誌。
耦合的種類：
正交性是指改變某個特性而不會影響到其他的特性。
api之間的功能應該成正交性，無功能重合。api之間應該是互相補充的關係。
對於api呼叫者而言，api應該是可被測試且易於被測試的。測試api不需要依賴額外的環境、容器、配置、公共服務等。
對可測試友好的api也是可被有效整合測試的前提。
api要具備統一的命名、統一的入/出參規範、統一的異常規範、統一的錯誤碼規範、統一的版本規範等。
統一規範的api優點：
服務API設計 之 API版本規範
正式發布的api包必須是release版本 eg.cn.gov.zcy.paas.template template api 2.1.1.release 使用 semantic versioning 風格 version號由 major.minor.patch 三段組合構成，version號增加含義...
API通用設計原則
什麼是好的 api？完備 be complete 對確定重點支援的使用者場景具有完備的功能支援。就是說，使用者通過對一組 api的呼叫能夠完成預期的功能。不冗餘 be minimal 在完備的前提下，api只提供最小的功能集合。不缺少 不冗餘。簡單清晰 be clear 介面設計簡單清晰。每個介面都...
API 介面設計 原則
api 設計乙個非同步介面實踐 知乎 介面設計的16個原則 accident web api介面設計經驗總結 hugejihu9的專欄 csdn部落格 聊聊restful 介面設計篇 一 就浩這口 csdn部落格 api 介面設計問題 獲取所有資料 和 獲取我的資料 介面是分開的嗎 v2ex wha...