如何写微服务的文档？

前段时间，参与了一个SaaS产品的研发，产品的架构是基于Spring Cloud的微服务架构。产品被拆分为多个微服务，每个微服务都有自己的文档（word版）。这些文档包括需求说明书、概要设计说明书、详细设计说明书、项目立项书等等。但是，在开发微服务的过程中，发现这些文档有如下缺点：

• 更新不及时或者写完就没有责任人维护了。
• 文档上只列出了编写人（有可能就是一个人），而不是该服务的开发团队。
• 分了很多的word文档（需求分析、详细设计等等），信息都被分散了，找起来很麻烦。
• 这些文档都是按照标准的软件开发阶段文档格式来编写的，对微服务描述不够仔细。
• 这些文档一般都是在svn上，访问起来不方便。
• 有些文档基本没啥用，有问题还是要找人来问。

那么，在微服务架构下，我们到底应该需要什么样的文档？

最近在阅读《生产微服务》和《微服务架构与实践》时，发现这两本书中给出了很好的解释和实践。

我们需要为每个微服务编写一个服务描述文件。服务描述文件和代码一样，都是微服务的组成部分，微服务团队有责任维护服务描述文件。服务描述文件的质量也是衡量团队指标之一。

建议使用在线的wiki来编写服务描述文件，而不是word文档。具体如何编写，请参考如下内容：

指导原则

• 落实团队责任制。
• 每个微服务都要有详尽的文档。
• 文档要定期更新。
• 文档要包含如下内容：微服务描述、架构图、待命人员的信息、重要信息的链接、开发上手指南、微服务请求消息流、端点的信息、依赖项的信息、运行手册、以及常见问题答疑。
• 文档能被开发人员、团队和组织所理解。
• 文档要符合生产就绪标准并且满足相关要求。
• 文档要经过评审。

模板结构

• 1 服务介绍

  • 1.1 服务名称
    中英文都要有

  • 1.2 功能说明
    服务的功能描述
    关于微服务以及微服务在整个生态系统中所扮演角色的描述

  • 1.3 架构图
    一个能够详细描述微服务架构及其客户端和依赖项的架构图，不需要用特别专业的软件绘制，只要大家都能理解即可
    给出客户端和依赖项的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 服务维护者
  记录服务的开发、测试、运维人员，要有姓名、岗位、联系方式（邮件、QQ、手机等），要能直接联系到个人

• 3 服务可用等级（SLA）
  服务的SLA说明（可用时间，服务保证等）

• 4 运行环境

  • 4.1 生产环境
    例如：http://order-service.prod.online.com
  • 4.2 测试环境
    例如：http://order-service.test.online.com
  • 4.3 开发环境
    例如：http://order-service.dev.online.com

• 5 开发指南

  • 5.1 开发环境搭建
    jdk的安装，IDE的安装，插件的安装，以及其它的相关教程
  • 5.2 编程规范
  • 5.3 代码库
  • 5.4 如何运行服务
  • 5.5 如何调试
  • 5.6 其它
    任何有助于开发人员上手的信息

• 6 测试

  • 6.1 测试策略
  • 6.2 如果运行测试
  • 6.3 测试总结
    统计结果，bug，性能，指标等等

• 7 构建

  • 7.1 持续集成环境
  • 7.2 持续集成流程描述
  • 7.3 构建后的部署发布

• 8 部署

  • 8.1 如何部署到不同的环境
  • 8.2 部署后的功能验证

• 9 运维手册

  • 9.1 日志聚合访问URL
  • 9.2 监控聚合访问URL
  • 9.3 事故处理流程
  • 9.4 用于诊断、缓解、解决告警问题的分步操作指南
  • 9.5 如何排查和调试问题

• 10 API端点
  详细描述服务包含的API端点的信息或者API端点在线文档的URL（比如swagger）

• 11 问答章节
  收集常见的问题，并给出解答

参考资料：
《生产微服务》
《微服务架构与实践》