乾貨 | Api 體系架構分享（上）

最近呢，在作 api 的設計

對於設計，一方面是對於後端 server 框架的設計，另外一方面呢，是對於整個 api 體系的設計

在這裏呢，咱們來理理思路，先來大體分一下塊

風格就不用說了，咱們就用 restful 風格，接下來：

• IDL，也就是咱們所說的接口描述語言

• server 框架，整個 api 服務的核心驅動

• 版本控制

• 還有一些輔助工具，好比說，自動化工具、認證受權、監控上報、日誌記錄、檢索等等

而後呢，咱們就來分別說說設計開發中的一些感觸

IDL

顧名思義，IDL 是咱們整個 api 體系的核心模型，基本上全部的東西都是要基於咱們的 IDL 的，在使用的選擇上有不少，好比 Yaml、Json、xml、PB 等等，這些均可以做爲接口描述語言，同時呢，各有優劣，在這裏呢，咱們考慮瞭如下這幾種：

Json：Json 是一種穩定並獲得普遍應用的序列化格式，瀏覽器包含對該格式的原生解析能力，瀏覽器內建調試器也能很好地顯示這種內容。惟一不足在於要具有 Json 解析器/序列器，好在基本全部語言都已提供。使用 Json 最主要的麻煩在於每條信息會重複包含屬性名，致使傳輸效率低下，同時呢，Json 對於一些 api 開發過程當中可能出現的特殊需求可能會處理很差，好比說，字段之間的依賴關係，就不容易描述出來

Yaml：使用 Yaml 來定義咱們的 api 模型的話，可謂是很是的簡潔明瞭，可是對於 api 模型中的一些複雜結構，以及一些字段的自檢測，並不可以很好的支持，同時，這個格式也不容易在開發中進行約定，可能會引發一些沒必要要的麻煩

PB：PB 全稱是 Protocol Buffers，是谷歌建立的一種基於二進制鏈接格式的接口描述語言。在解析和網絡傳輸方面 Protocol Buffers 更高效，並經歷了谷歌高負荷環境的考驗，不足在於一些語言的支持並非很好，主要仍是對於 C、python 和 java 的支持，而且呢，在 .proto 文件的共享和編譯方面會產生些許額外開發負擔

xml：這個你們就都很是熟悉了，相對於 Json 和 Yaml，xml 就顯得有些笨重了，可是 xml 可以很好的應用於各類特殊的場景，可以根據不斷的線上需求進一步的擴展，而且能夠直接經過 xsd 進行自校驗，從功能上來說，或許會更加完善一些

由於 IDL 是咱們 api 的核心，之後的各項業務基本都要圍繞 IDL 展開，因此須要可以功能完善，便於擴展，而且在開發中可以有一些自動化的工具來進行約束，so，最終呢，仍是決定採用 xml 的形式

server 框架

核心代碼很是的簡單，只須要寫一個 route 來實現路由調用就好了，可是，爲了輔助他可以正常的調用，咱們就不得不實現更多的一些輔助功能了

能夠來看一下個人基本的目錄結構

Framework
    │
    ├── Auth        認證、鑑權模塊
    │
    ├── Base        基礎服務
    │
    ├── Client      各類端服務
    │
    ├── Common      公共組件
    │
    ├── Core        核心調度邏輯
    │
    ├── Coroutine   協程調度實現
    │
    ├── Exception   異常處理
    │
    ├── Http        協議實現
    │
    ├── Log         日誌上報，監控模塊
    │
    ├── Pool        鏈接池（資源池）
    │
    └── Resource    資源模型

同時呢，開發過程當中要下降各模塊間依賴關係，就好比說，與其 new 一個對象，不如採用 set 的方式來解耦，預期繼承，不如採用組合的方式，保證各個模塊的獨立性，同時呢各模塊間又要有一個通信通道

爲了實現一些特殊的需求，咱們採用協程調度來實現非阻塞 IO，固然，這裏咱們就須要實現一個單獨的服務端口監聽，就比如 swoole 或是 workerman 那樣，編寫獨立的服務進程

ok，上面也提到了，核心代碼只須要實現一個 route 路由就好了，可是在路由先後，要記得留出認證、鑑權接口，同時呢，對於運行時的異常也要及時捕獲上報，同時記入日誌，方便調試

對了，除了這些 server 服務依賴，數據也要注意哦，最好是可以在原始數據之上再單獨抽離出來一層數據接口層，不要直接操做原始數據

這些核心服務完成後，剩下的就是客戶端和服務端代碼，這個就能夠根據實際的服務去自由發揮了，對於 api，咱們也能夠把客戶端代碼稱之爲 SDK，同時呢，爲了方便之後的開發維護，能夠統一編寫自動化工具生成，對於不一樣語言對應的作支持

---

OK 了，上篇就先寫到這裏吧，主要說了對於 server 框架以及 IDL 的設計選擇思路

下篇呢，會主要對於 api 的版本控制，發佈，以及一些自動化工具進行一些分享

From: 一名熱愛動漫的攻城獅