声明
此文章不是我写的,是来自于我之前的团队的,主要是我们当时的leader@闫华做的,微信搜索codeasy可以关注他的公众号。个人觉得此模板还是很不错的,按照这个模板既可以锻炼大家写设计的能力,又能让大家对自己的系统产生一定的思考,所以想要给大家分享出来。因为是维护在内网,要不然我只需要分享一个链接就好了。。。以下是内容:
背景简介
此部分必须要有。
回答以下内容:
- 这个系统是关于什么的,职责是什么
- 给谁使用
但不限于以上这些内容。这部分非常重要但要高度凝练,要简洁。目的是提供必要的背景知识,以便读者理解下面章节的内容。
这部分可以与产品经理一起,紧密协作编写。
领域模型
此部分必须要有。
领域模型是对业务的一个抽象建模,可以用粗类度的类图(类和类的关系)来表示,并加上必要的名词解释。
如果领域对象特别多,有必要建立分组。如何分而治之,可以参考DDD的界限上下文的分析方法。
领域模型是和技术无关的,所以,领域模型不等同于表设计,这里不应该出现表设计相关的内容。
领域模型非常重要,没有特殊情况,本部分必须要有。特殊情况请说明。
这部分可以与产品经理一起,紧密协作编写。
功能概览
这里用用例图表示。不要用UI原型图。
用例图是必须的。可选的补充包括用例描述、用户故事、用户场景。
这部分可以与产品经理一起,紧密协作编写。
原则/约束/质量属性
原则、约束和质量属性(非功能需求)都会影响设计决策。
通用的设计原则不在这里写,这里写本系统需要特殊遵循的原则,或者没有遵循某项通用原则的原因。参考《系统设计通用原则》。
一些设计上的妥协,往往都是由约束产生的。要明确说明。常见的约束有:
- 时间,预算和资源
- 允许/不允许使用的技术组件,部署平台,公司的标准要求
- 团队的规模和技能配置
- 本系统的的本质(战术的还是战略的,项目的还是产品的)
- 政治约束(请客观并含蓄地表达,但如果不写的话,后来维护系统的人,会感觉很多东西都莫名其妙)
- 知识产权和安全等
不用所有都写,影响到设计决策的,尤其是让人感觉到奇怪的设计决策的约束写出来。
性能、安全等质量属性,如果有特殊的要求,也在这里说明。如果没有特殊之处,不用写。
系统架构
按C4模型。C1图可选,C2图必须有。C2中关键应用的C3图推荐写在其对应的主代码视图的README中,这里可以给出链接。
这里主要描述的是运行时架构。比如POS服务中心这个应用,依赖与商品系统,那直接画上这个依赖关系即可。实际上,这个依赖是通过SPI来解耦隔离的,那在这里也不需要描述,而是在下一节代码结构里描述。
代码结构
需要写有哪些代码工程,给出git地址,描述其职责,并说明代码和系统架构中的对应关系。
工程下的module也需要说明。如果遵循了产品化规范的话,简单说明其对应产品化规范那个部分即可,否则需要详细说明。
遵循产品化的规范,意味着,每个系统和外部系统的依赖的部分,都要抽象成SPI,然后提供一个SPI的默认实现,由BOOTSTRAP来组织起来运行。参考《多租户可复用软件的设计原则 - ACL的实现》。为了便于开发,SPI的代码和SPI默认实现以及BOOTSTRAP的代码都可以是一个主代码工程下的module,但必须严格遵循依赖原则,即,主体module不能依赖于SPI默认实现(bootstrap除外),SPI的默认实现也不依赖于主体module,它们都依赖于SPI。这个依赖关系会作为架构规范自动化检查的一条规则。当SPI有多个实现的时候,需要将SPI/SPI实现/BOOTSTRAP都独立成一个工程。
SPI模块或工程的命名模式是 artifactId-<子模块>-spi,子模块是可选的,实现模块或工程的命名模式是artifactId-<子模块>-spi-实现名,比如: xstore-pos-center-purchase-spi 和 xstore-pos-center-purchase-spi-fresh。模块内的报名的命名原则相同。
开发部署
快速开始
开发的时候需要做哪些事情可以搭建好环境及快速运行起来。参考上面的系统架构中的C2图,重点描述系统搭建起来时,应用间配合的部分。每个应用自己如何 快速开始 不写在这里,写在应用对应的主代码视图的README中。
测试环境搭建如果有特殊注意也需要说明。
生产部署
系统架构中的C2图中已经体现了部分部署架构,如果需要进一步说明,可以在这个地方丰富。本节内容可选。但建议进一步丰富,比如当前系统中部署情况(哪个应用有多少个docker、JSF的分组等等)。
其它
有其它需要补充的内容,写在这里。本节可选。