如何写微服务的文档？
前段时间，参与了一个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
- 4.1 生产环境
-
5 开发指南
- 5.1 开发环境搭建
jdk的安装，IDE的安装，插件的安装，以及其它的相关教程 - 5.2 编程规范
- 5.3 代码库
- 5.4 如何运行服务
- 5.5 如何调试
- 5.6 其它
任何有助于开发人员上手的信息
- 5.1 开发环境搭建
-
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 问答章节
收集常见的问题，并给出解答
参考资料：
《生产微服务》
《微服务架构与实践》
