对于每一个服务而言，都应有一个清晰的服务说明，描述当前服务的信息，同时帮助团队更快地理解并快速上手。 譬如，在笔者的微服务实践过程中，对于每一个代码库，其服务说明都包括如下几个部分。
服务介绍
- 服务提供什么功能，譬如产品服务主要提供产品数据的获取或者存储。
- 谁是服务的消费者。譬如产品服务的消费者为电商的前端网站系统或者CRM系统。
服务维护者
- 挑选1~2个团队的成员，作为服务的负责人，登记其姓名、电子邮件、电话等联系方式，以便其他团队遇到问题能及时找到服务的负责人。
服务可用期
- 服务可用周期，如7×24小时，或周一~周五（7:00~19:00）等。
- 可用率，可用率是指服务可以正常访问的时间占总时间的百分比，如99.9%或者99%。 如果服务一天内都可以访问，则服务当天的可用率为100%。 如果服务有3分钟访问中断，而一天共有1440分钟，那么服务的可用率为： ((1440 - 3) / 1440) * 100%，也就是99.79%。
- 响应时间，指服务返回数据的可接受响应时间。譬如为0.5~1秒。
定义环境
- 生产环境
- 类生产环境
- 测试环境
开发
- 如何搭建开发环境
- 如何运行服务
- 如何定位问题
测试
- 测试策略
- 如何运行测试
- 如何查看测试的统计结果，譬如测试覆盖率、运行时间、性能等。
构建
- 持续集成访问的URL
- 持续集成的流程描述
- 构建后的部署包
部署
- 如何部署到不同环境
- 部署后的功能验证
运维
- 日志聚合的访问
- 告警信息的访问
- 监控信息的访问