聊聊架构（1）如何编写架构文档

今天给大家分享下如何编写架构文档。本文源自2022年在蚂蚁内部分享的课程，在此基础上做了一些更新。

自我介绍

1 架构的目标

1.1 为什么要做架构

架构首先要从企业的核心目标讲起，企业的核心目标不是5%-%10的增长，而是在追求十倍速的利润增长。利润的增长核心就是在于不断地增加收入、并不断地降低成本。

提升收入分为提升效率和提升效果。提效率是指提升产品的研发效率和迭代效率，功能或产品早一个月上线就能帮助业务早获得一个月获得收入。以前我们是三个月完成一个大需求，1个月完成一个小需求，那么我们能不能实现一周完成一个小需求，一个月完成一个大需求。在效果上，以前我们一个支付功能上线渗透率很低，未来是否可以通过产运一体的架构提升渗透率。

降低公司成本分为降低研发成本和降低资源成本。降低研发成本分为降低创新成本和维护成本。业务有很多新的创新想法和IDEA，我们是不是可以。资源成本包括研发资源和机器资源，比如一个项目要投入的人员数量，一个项目需要投入的机器数量和存储成本等，很多架构师喜欢做架构升级，但是如果我们的业务没有增长，但是我们却在架构升级时新增应用，从而增加很多服务器，这个非常不合理。

1.2 如何做好应用架构

如何做好应用架构分为两个维度，首先是要掌握常用的架构方法，目前分层架构和领域建模都取向成熟，而变化的主要就是业务。所以第二个关键点是要深入业务，我们需要熟悉业务的目标、趋势、策略、打法和挑战。而业务面临的挑战是多元化的，在当下有收入挑战、用增挑战、利润挑战、拓场景挑战和运营ROI挑战。同时还要考虑未来的第二增长曲线是什么，未来的趋势和方向是什么？为了解决业务当下和未来的问题我才需要做架构升级。在做架构方案的时候更多的是在一个取舍，比如当我们刚接触一个新业务的时候我们是否要做架构升级，当我判断业务可能要爆发式增长时，果断选择平台化架构升级，从而更好的支撑业务快速增长，这就是我们当时的取舍。

最后，我想重点说明下，技术只有结合业务才能产生价值，不能为了技术而技术，不能为了架构而架构，一切从业务出发。

1.3 架构文档目录

架构文档的目录分为以下六部分。

1.4 架构目标

架构目标一定要符合SMART原则，既架构目标要满足四个条件，第一是要有一个具体的事，比如XX业务交付小需求周期缩短到一周内，第二个是目标一定是要可达成。第三个是有准确的完成时间，比如7月底。第四个是要和业务问题有关联性，第五个是可衡量，要有一个数字化的目标，比如降低1000台服务器。架构目标的方向可以是提效率、提效果、降成本、保稳定等维度。同时架构目标可以继续拆解成二级目标进行细化。

1.5 三种架构

2 业务架构

上图是我做业务架构的整体思路。我认为做业务架构就是一个逐步化繁为简的过程。我们经常会讨论作为架构师最核心的能力是什么呢？我觉得是抽象能力和取舍决策能力，那什么是抽象能力？抽象能力就是一种化繁为简的能力。

那么如何做到化繁为简？主要分为三个步骤，第一步我通过PD的需求或用户的需求推导出业务用例，第二步通过业务用例推导出业务架构，第三步骤通过业务架构推导出领域建模和领域的划分。通过以上步骤就可以把复杂多变的需求抽象成极简且不变的信息模型。

2.1 业务用例图

主动名组成用例：业务用例格式=主语+动词+名词，如用户还账单。主语是用户，动词是还，名词是账单。

三要素描述用例：一句话描述还账单的用例详情。作为用户（用户是谁），我希望有一个提前还账单的功能，以便于一次还完账单（系统提供什么功能），避免我每个月来还（产生什么用户价值）。

2.2 业务架构图

用例放在一起就是业务架构图，但是要把用例进行分类。第一步：找用例之间的共性和关系确认分类。第二步：将用例按照分类放在一个图中，比如贷前、贷中和贷后。

2.3 业务流程图

业务流程图类似产品经理的PRD流程图。将用例转换成一个多角色的业务流程图，一个业务流程图有多个业务活动组成，如用户签约、用户支用和用户还款等。

2.4 领域模型图

领域模型（Domain Model）是一种用于描述业务领域的概念模型，它通过识别和组织业务领域中的关键概念、实体及其关系，帮助我们更好地理解和表达业务需求。

领域模型由实体、实体属性、关系和行为组成。从用例里的名词里找模型名或属性名，可分隔的就是模型，比如合约可以分隔为签约时间和签约用户。不可分隔的就是属性，比如签约时间。通过状语和定语分期出模型之间的关系，模型和属性之间的关系。关系有1：N，N：1和1：1，建议避免使用N：N，可以转换为1：N或N：1关系。

何为一个领域？每个领域都管理一个或多个单独的实体。

3 系统架构

3.1 由外而内架构系统

首先设计一级架构域，每个一级架构域有几个子域组成，如何去做分层。第二是在二级域里每个域内的职责是什么，这个域里面有哪些系统组成，为什么这个系统放在这个域里，比如有的系统既有息费的属性又有结算的属性，应该属于哪个域呢？通常情况下，我们会判断它营销属性更多一点就会放在营销域里。第三个是系统间设计，主要设计系统之间的交互方式是什么，比如系统之间通过HTTP、SFTP、RPC，消息或数据库等进行通讯。

3.2 分层架构

分层架构。我们可以用以下方式对业务系统进行分层。

第一层渠道层，按照流量入口垂直切分系统，比如无线渠道、批处理渠道和后台渠道等。

第二层业务产品层，按照不同的业务垂直切分系统，比如信用贷业务、抵押贷业务和支付业务等。

第三层核心能力层，可以按照不同的业务能力水平切分系统，比如签约系统、还款系统，放款系统等，这一层使用动词来切分系统，主要是给业务层提供系统能力复用。

第四层是基础能力层，按照基础能力水平切分系统，比如特征加工系统。

第五层是运营支撑层，这一层按照运营目标来拆分系统，比如用户增长后台系统、催收后台系统等。

分层架构的问题？第一个是问题是边界问题多，比如业务提了一个批量放款的需求，这个是做在产品层还是核心能力层，产品层认为这是个通用能力应该做在核心能力层，但是核心能力层认为这是一个一次性需求，只有这个业务有。第二个问题是链路长，当你做一个业务时，很有可能贯穿所有系统，也就是所有层的系统都要为支持某个业务功能而修改，一个大项目就会涉及到10几个系统Owner进行研发。

3.3 中台架构

为了解决以上问题，可以进行中台化架构升级。中台架构相对于分层架构主要升级了三个特性。

• 第一个是从提供系统能力复用升级成提供流程复用。

• 第二个是从提供能力复用到面向不确定性提供扩展能力。

从而实现了既提供领域复用性，又提供业务复用性，并提供业务扩展性，还提供业务隔离性。至于中台架构如何做，后续会单独写一篇文章详细介绍。

3.4 分层架构的优缺点

域服务类似原子化的乐高积木块，你需要有专家经验或PRD才能组装出乐高房子，但是复用性非常强。业务能力层虽然可以给业务提供服用，但是只能在当前业务上提供复用，有很强的局限性。而解决方案层或者业务产品层都是直面业务基本上不提供复用性。

3.5 系统间依赖架构图

系统之间交互的方式有很多种，分为直接交互和间接交互，直接交互包括RPC服务、HTTP服务和数据库服务。间接交互包括SFTP服务和消息服务。通过情况下AB两个系统不能循环依赖，如果出现这种情况只能选择A直接依赖B，但是B可以通过发消息间接依赖A。

架构图里可以通过不同的颜色表达状态。蓝色表示本次架构依赖的服务/系统，黄色表示修改的服务/系统，红色表示新增的服务/系统。

3.6 系统服务描述

系统服务包括服务名、服务描述，入参和出参。入参设计规范：为了方便扩展，入参尽量设计成对象，比如XXRequest，同时需要默认增加一个扩展字段XXExt方便扩展传参。入参字段要用示例，枚举要有具体数值描述。出参设计规范：为了方便扩展，出参尽量设计成对象，比如XXResponse，同时需要默认增加一个扩展字段XXExt。出参要明确错误码。

4 非功能性设计

5 推荐工具