摘要：程序員常會說：我最討厭別人寫的代碼沒有文檔，我也最討厭本身須要寫文檔。
有一個很老的梗: 我最討厭別人寫的代碼沒有文檔，我也最討厭本身須要寫文檔。前端
有這種想法的程序員應該算是一個老鳥了，對於大多數程序員來講，對於他們來講: 文檔是什麼。python
對於大規模，超大規模的項目，而且歷時很長，須要大量人員協同開發的項目，沒有文檔簡直不可想象。可是因爲時間緊，任務重，大多數的項目中的開發者都沒時間寫文檔，並且，文檔也不計入考覈指標，致使開發者也沒有動機寫文檔。這就形成了不少項目都缺乏規範化文檔，項目的交接和接口的對齊都是靠口口相傳，接口定義準確度低，而且項目的總體開發效率低下。程序員
做爲一個文檔愛好者的筆者來講，日常很重要的一件事兒就是將本身的工做概括總結並整理成文檔。即使如此，筆者也面臨着不少問題：正則表達式
- 需求很快就變了，光是改代碼就已經耗盡了個人精力了，哪有時間同步文檔。
- 要麼先改代碼，要麼先改文檔，總之文檔和代碼之間存在一個不一致錯位期。
除此以外，因爲咱們主要從事AI相關能力的研發，因此在開發過程當中還存在如下特殊的問題：編程
- 開發者不得不寫大量重複的網絡編程相關的業務代碼，這些代碼的質量一般不高，而且在後期的反覆修改中變得愈來愈臃腫，從而難以維護。
- 由於重複的業務代碼開發工做佔比過大，嚴重壓縮智能化研發人員在AI方面的精力投入，這就致使了企業投入大量人力卻沒法獲得好的效果。
通過不斷的摸索和實踐，AIMS項目組採起了一套文檔驅動的開發模式，能夠有效地解決上述在項目中普遍存在的問題。flask
1. AI接口開發的特色
不一樣於傳統API的CRUD接口的開發，AI的開發模式一般包含了如下步驟：後端
- 數據清洗；
- 模型訓練；
- 參數調優；
- API上線。
前三項都是咱們組的強項，也是咱們的工做重點。可是在實際工做中，倒是API上線消耗了咱們的大部分精力。AIMS項目組大都從事的是AI方向相關的工做，對於API的相關庫flask、tornado也不是很熟悉，這就致使開發人員須要花大量時間去了解網絡編程相關內容，開發出來的程序質量可能也不是很高。並且，在接口開發後，還須要準備一份Swagger UI給前端的開發人員，這又是一項繁重的工做。爲了解決如上所述的痛點問題，AI接口開發就須要知足如下兩個特色和需求：api
- 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 中的應用與實踐》，原文做者：zqmillet 。