美文网首页
如何写微服务的文档?

如何写微服务的文档?

作者: zlup | 来源:发表于2017-12-06 15:59 被阅读0次

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

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

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

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

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

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

指导原则

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

模板结构

  • 1 服务介绍

  • 2 服务维护者
    记录服务的开发、测试、运维人员,要有姓名、岗位、联系方式(邮件、QQ、手机等),要能直接联系到个人

  • 3 服务可用等级(SLA)
    服务的SLA说明(可用时间,服务保证等)

  • 4 运行环境

  • 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 问答章节
    收集常见的问题,并给出解答

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

相关文章

  • 如何写微服务的文档?

    前段时间,参与了一个SaaS产品的研发,产品的架构是基于Spring Cloud的微服务架构。产品被拆分为多个微服...

  • 微信公众号开发流程

    微信公众号开发配置文档: 申请微信公众服务号(服务号需要有公司认证) url : https://mp.weixi...

  • 微信公众号

    官方文档 微信公众平台提供的功能有限,需要用服务器做逻辑 对接微信服务器 1. 告诉微信我们的URL地址 2. 微...

  • 如何写好BRD?

    如何写好商业需求文档? 一、什么是商业需求文档 商业需求文档即BRD是产品生命周期中最早的文档,其内容涉及市场分析...

  • 微信支付 APP支付 Java 服务器端

    本文介绍微信支付中APP支付的java服务端。 微信APP支付文档:https://pay.weixin.qq.c...

  • 微信分账

    最近,微信分账终于更新了微信开发文档,普通商户和服务商都可以分账,微信现在文档还是比较全了,没那么坑了,认真通读文...

  • 如何写文档

    写文档基本套路,拿这个k8举例子1.把主题的历史来一遍,提一下作者 比如:https://juejin.im/po...

  • 微信服务商 微信小程序 支付

    服务商模式下的微信小程序支付 一 账号申请 参考微信官方文档:https://pay.weixin.qq.com/...

  • 5.3 原型设计 - 需求文档

    需求文档,产品经理最终产出的文档,也是产品设计最终的表述形式。本次分享呢,就是介绍如何写好一份需求文档。 1. 什...

  • 【onlyoffice中文指南】9-回调处理程序

    该文档编辑服务通知文件存储服务有关使用文档编辑的状态callbackUrl从的JavaScript API。该文档...

网友评论

      本文标题:如何写微服务的文档?

      本文链接:https://www.haomeiwen.com/subject/aqgkixtx.html