前段時間，參與了一個SaaS產品的研發(fā)，產品的架構是基于Spring Cloud的微服務架構。產品被拆分為多個微服務，每個微服務都有自己的文檔（word版）。這些文檔包括需求說明書、概要設計說明書、詳細設計說明書、項目立項書等等。但是，在開發(fā)微服務的過程中，發(fā)現這些文檔有如下缺點：

• 更新不及時或者寫完就沒有責任人維護了。
• 文檔上只列出了編寫人（有可能就是一個人），而不是該服務的開發(fā)團隊。
• 分了很多的word文檔（需求分析、詳細設計等等），信息都被分散了，找起來很麻煩。
• 這些文檔都是按照標準的軟件開發(fā)階段文檔格式來編寫的，對微服務描述不夠仔細。
• 這些文檔一般都是在svn上，訪問起來不方便。
• 有些文檔基本沒啥用，有問題還是要找人來問。

那么，在微服務架構下，我們到底應該需要什么樣的文檔？

最近在閱讀《生產微服務》和《微服務架構與實踐》時，發(fā)現這兩本書中給出了很好的解釋和實踐。

我們需要為每個微服務編寫一個服務描述文件。服務描述文件和代碼一樣，都是微服務的組成部分，微服務團隊有責任維護服務描述文件。服務描述文件的質量也是衡量團隊指標之一。

建議使用在線的wiki來編寫服務描述文件，而不是word文檔。具體如何編寫，請參考如下內容：

指導原則

• 落實團隊責任制。
• 每個微服務都要有詳盡的文檔。
• 文檔要定期更新。
• 文檔要包含如下內容：微服務描述、架構圖、待命人員的信息、重要信息的鏈接、開發(fā)上手指南、微服務請求消息流、端點的信息、依賴項的信息、運行手冊、以及常見問題答疑。
• 文檔能被開發(fā)人員、團隊和組織所理解。
• 文檔要符合生產就緒標準并且滿足相關要求。
• 文檔要經過評審。

模板結構

• 1 服務介紹

  • 1.1 服務名稱
    中英文都要有

  • 1.2 功能說明
    服務的功能描述
    關于微服務以及微服務在整個生態(tài)系統(tǒng)中所扮演角色的描述

  • 1.3 架構圖
    一個能夠詳細描述微服務架構及其客戶端和依賴項的架構圖，不需要用特別專業(yè)的軟件繪制，只要大家都能理解即可
    給出客戶端和依賴項的wiki地址
    評審記錄

    下圖以訂單服務為例，展示了一個簡化的架構圖，該圖參考DDD中的Context Map的繪制方法（《實現領域驅動設計》第3章），以及使用了六邊形架構（Hexagonal architecture來表示微服務）。下圖中的U表示上游服務（Upstream），D表示下游服務（Downstream）。
    

    訂單服務的依賴架構圖

  • 1.4 架構決策記錄
    參考：架構決策記錄
    格式參考：Architecture Decision Records in Node.js with Reporter, supported Windows, GNU/Linux, macOS - 輕量級架構決策記錄工具

• 2 服務維護者
  記錄服務的開發(fā)、測試、運維人員，要有姓名、崗位、聯系方式（郵件、QQ、手機等），要能直接聯系到個人

• 3 服務可用等級（SLA）
  服務的SLA說明（可用時間，服務保證等）

• 4 運行環(huán)境

  • 4.1 生產環(huán)境
    例如：http://order-service.prod.online.com
  • 4.2 測試環(huán)境
    例如：http://order-service.test.online.com
  • 4.3 開發(fā)環(huán)境
    例如：http://order-service.dev.online.com

• 5 開發(fā)指南

  • 5.1 開發(fā)環(huán)境搭建
    jdk的安裝，IDE的安裝，插件的安裝，以及其它的相關教程
  • 5.2 編程規(guī)范
  • 5.3 代碼庫
  • 5.4 如何運行服務
  • 5.5 如何調試
  • 5.6 其它
    任何有助于開發(fā)人員上手的信息

• 6 測試

  • 6.1 測試策略
  • 6.2 如果運行測試
  • 6.3 測試總結
    統(tǒng)計結果，bug，性能，指標等等

• 7 構建

  • 7.1 持續(xù)集成環(huán)境
  • 7.2 持續(xù)集成流程描述
  • 7.3 構建后的部署發(fā)布

• 8 部署

  • 8.1 如何部署到不同的環(huán)境
  • 8.2 部署后的功能驗證

• 9 運維手冊

  • 9.1 日志聚合訪問URL
  • 9.2 監(jiān)控聚合訪問URL
  • 9.3 事故處理流程
  • 9.4 用于診斷、緩解、解決告警問題的分步操作指南
  • 9.5 如何排查和調試問題

• 10 API端點
  詳細描述服務包含的API端點的信息或者API端點在線文檔的URL（比如swagger）

• 11 問答章節(jié)
  收集常見的問題，并給出解答

參考資料：
《生產微服務》
《微服務架構與實踐》