有一個很老的梗: 我最討厭別人寫的程式碼沒有文件，我也最討厭自己需要寫文件。

有這種想法的程式設計師應該算是一個老鳥了，對於大多數程式設計師來說，對於他們來說: 文件是什麼。

對於大規模，超大規模的專案，並且歷時很長，需要大量人員協同開發的專案，沒有文件簡直不可想象。但是由於時間緊，任務重，大多數的專案中的開發者都沒時間寫文件，而且，文件也不計入考核指標，導致開發者也沒有動機寫文件。這就造成了很多專案都缺少規範化文件，專案的交接和介面的對齊都是靠口口相傳，介面定義準確度低，並且專案的整體開發效率低下。

作為一個文件愛好者的筆者來說，平常很重要的一件事兒就是將自己的工作歸納總結並整理成文件。即便如此，筆者也面臨著很多問題：

· 需求很快就變了，光是改程式碼就已經耗盡了我的精力了，哪有時間同步文件。

· 要麼先改程式碼，要麼先改文件，總之文件和程式碼之間存在一個不一致錯位期。

除此之外，由於我們主要從事AI相關能力的研發，所以在開發過程中還存在以下特殊的問題：

· 開發者不得不寫大量重複的網路程式設計相關的業務程式碼，這些程式碼的質量通常不高，並且在後期的反覆修改中變得越來越臃腫，從而難以維護。

· 因為重複的業務程式碼開發工作佔比過大，嚴重壓縮智慧化研發人員在AI方面的精力投入，這就導致了企業投入大量人力卻無法得到好的效果。

經過不斷的摸索和實踐，AIMS專案組採取了一套文件驅動的開發模式，可以有效地解決上述在專案中廣泛存在的問題。

1. AI介面開發的特點

不同於傳統API的CRUD介面的開發，AI的開發模式通常包含了以下步驟：

· 資料清洗；

· 模型訓練；

· 引數調優；

· API上線。

前三項都是我們組的強項，也是我們的工作重點。但是在實際工作中，卻是API上線消耗了我們的大部分精力。AIMS專案組大都從事的是AI方向相關的工作，對於API的相關庫flask、tornado也不是很熟悉，這就導致開發人員需要花大量時間去了解網路程式設計相關內容，開發出來的程式質量可能也不是很高。而且，在介面開發後，還需要準備一份Swagger UI給前端的開發人員，這又是一項繁重的工作。為了解決如上所述的痛點問題，AI介面開發就需要滿足以下兩個特點和需求：

· API的核心函式是現成的；

· 需要將API開發工作量降到最低。

2. 文件驅動的開發模式

我們發現API的介面文件中已經包含了實現API介面的所有資訊。也就是說，API介面文件的資訊熵和API介面程式碼的資訊熵是一樣的。因此，我們只需要完成程式碼或者文件中的一項即可，另外一項可以交給框架自動生成，這就避免了把同樣一件事情重複做兩遍的問題。考慮到文件不論從可讀性、易寫性還是可維護性都勝過程式碼，我們決定寫文件，然後根據文件生成對應的程式碼。

我們參考了OpenAPI Specification3.0.1標準，以及JSON Schema定義了一套API描述語言，開發者基於這個API描述語言撰寫API文件。當完成文件時，API的開發工作也隨之完成，大大節省了API介面的開發工作量。經過初步估計，使用文件驅動模式開發一個API介面，通常可以減少40%–70%的工作量。

3. AIMS框架介紹

為了實現文件驅動的開發模式，AIMS基於tornado實現了一套Web後端框架，如下圖所示。

3.1. Application Router元件

每一個API都會有一個路徑，即一個正規表示式[1]。一個微服務中的多個API的所有路徑會組成一個API路徑列表。

當Application Router接收到請求時，會根據請求中的URI在路由表中查詢。如果匹配到某一個Request Handler，路由模組會將請求轉發給響應的Request Handler。如果所有的路徑都不匹配，則返回404結果[2]。

3.2. Request Handler元件

Request Handler處理來自Application Router的響應，是AIMS架構的核心，而Document則是Request Handler的核心。在AIMS架構中，Document是指函式的文件，即__doc__。Request Handler是在服務的啟動階段動態生成的。

事實上，在AIMS架構圖中，只有Document是開發者必須寫的[3]。其它的元件都是由AIMS提供的，或者是由Document自動生成的，所以AIMS開發模式也被稱為文件驅動型開發模式。開發者只需要維護Document即可，從而實現減少開發者工作量的目的。

3.3. Watchman元件

Watchman元件可以透過設定來訂閱某些介面的異常，當被訂閱介面出現任何異常時，Exception Handler便會觸發Watchman元件。

因為Recorder元件記錄了Arguments，Watchman甚至可以自動產生一個可以復現該問題的測試用例，方便開發人員定位問題。

3.4. Recorder元件

Recorder是一個採集器，可以採集每一次請求的所有細節資訊，包括請求ID、請求引數、遠端IP、被呼叫的介面、響應時間、工作目錄和程式號等各種資訊。這些資料具有以下兩個作用:

· 系統的維護者可以利用Recorder中的資料快速定位，復現現網問題，可以看做是一個更強大的日誌系統。

· 透過請求ID，訓練資料收集系統可以將請求引數、響應資料與使用者反饋資料關聯起來，這就相當於是一條有標記的資料。

3.5. Logger元件

Logger是AIMS封裝的日誌模組，用法和python自帶的logging.Logger使用方式一致，最大限度地降低開發者的學習成本。

4. 補充說明

我們注意到，在AIMS架構圖中，Argument Parser、Schema Checker、Swagger UI和OpenAPI Specification是同源的，即都是來自Document。這就不會出現文件(Swagger UI、OpenAPI Specification)與函式實現(Argument Parser、Schema Checker)不一致的情況。開發者也不需要同時維護Argument Parser、Schema Checker、Swagger UI和OpenAPI Specification相關程式碼。

以上就是文件驅動開發在AIMS框架中的優勢，既降低了開發者的工作量，又解決了一致性的問題。事實證明，自動產生的元件質量也是優於開發者自行開發的程式碼，並且不易出錯，從而提升整體服務的質量以及穩定性。

[1] 在AIMS開發中，這個欄位是寫在__doc__中的api_path欄位中。
[2] 事實上，路由模組會將請求轉發給NotFoundRequestHandler，然後由NotFoundRequestHandler進行響應。
[3] 在AI相關微服務開發過程中，Function，也就是核心功能函式，是已經準備好的。

文件驅動開發模式在 AIMS 中的應用與實踐