前段时间,参与了一个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 问答章节
收集常见的问题,并给出解答
参考资料:
《生产微服务》
《微服务架构与实践》
网友评论