应用架构定义文档怎么写？从基线到目标的 TOGAF 模板实操拆解

Sat, 20 Jun 2026 10:00:00 +0800

做企业架构的人，迟早要面对一个灵魂拷问：你写了那么多 PPT 和 Visio 图，最后到底沉淀成了什么文档？

在 TOGAF 体系里，这个问题的标准答案是——架构定义文档（Architecture Definition Document，简称 ADD）。它是整个架构开发方法（ADM）流转过程中最核心的交付物，贯穿了从业务架构到技术架构的全部层次，记录了基线状态、目标状态以及两者之间的差距分析。

但现实中，很多团队对 ADD 的理解停留在「写一个 Word 文档把所有架构图贴进去」的层面。结果就是：文档写了几百页，评审会上没人看得完，项目结束后再也没人打开过。

本文从一个实际项目的角度，把架构定义文档的写法拆开来聊。不讲空洞理论，只聊三件事：

ADD 到底应该包含什么内容？
概念层和逻辑层分别怎么写才能让人看懂？
ADM 每个阶段该产出哪些文档？

最后附一个可以直接复用的简化模板。

一、架构定义文档是什么？为什么它这么重要？

1.1 一句话定义

架构定义文档是 TOGAF 框架中描述一个架构项目全生命周期状态的核心交付物。它打包了三样东西：

基线架构（Baseline Architecture）：当前系统是什么样的
目标架构（Target Architecture）：未来系统应该是什么样的
差距分析（Gap Analysis）：从现在到未来，差在哪里

你可以把它理解为架构领域的「项目计划书 + 设计说明书 + 变更影响分析」的合体。

1.2 ADD 在 TOGAF 体系中的位置

TOGAF 的架构开发方法（ADM）是一个循环迭代的过程，从预备阶段到 Phase H，每个阶段都会产出特定的交付物。而 ADD 是其中贯穿时间最长、覆盖范围最广的文档。

它的生命周期大致是这样的：

Phase B（业务架构）→ 初稿 ADD（业务部分）
Phase C（信息系统架构）→ 更新 ADD（数据+应用部分）
Phase D（技术架构）→ 更新 ADD（技术基础设施部分）
Phase E（机会与方案）→ 最终版 ADD（含差距分析和迁移路径）

也就是说，ADD 不是一次性写完的，而是随着 ADM 的推进逐步丰富。每经过一个阶段，你就往里面追加该阶段的架构描述。

1.3 ADD 和架构需求文档的区别

很多人会把 ADD 和架构需求文档（Architecture Requirements Specification）搞混。简单区分：

维度	架构定义文档（ADD）	架构需求规格说明书
核心问题	「架构长什么样」	「架构必须满足什么条件」
内容侧重	结构描述、模型、视图	量化指标、约束条件、SLA
典型内容	组件图、交互图、部署拓扑	性能要求、安全要求、合规要求
受众	架构师、开发团队、项目管理	架构评审委员会、运维、合规团队

两者是配套使用的。ADD 描述「是什么」，需求规格描述「必须做到什么程度」。

二、架构定义文档的标准结构

根据 TOGAF 第 10 版的标准，一份完整的架构定义文档应该包含以下章节：

1. 文档概述与项目背景
2. 架构范围与约束条件
3. 架构原则与目标
4. 基线架构描述（当前状态）
5. 目标架构描述（未来状态）
6. 差距分析
7. 架构决策记录
8. 架构路线图（迁移概要）
9. 附录：术语表、参考资料

但在实操中，你不需要一次性把这九个章节全写完。根据项目规模和架构成熟度，可以做裁剪。下面逐个拆解关键章节的写法。

2.1 文档概述与项目背景

这一节不是写给自己看的，是写给六个月后接手这个项目的人看的。你需要回答：

这个架构项目是在什么业务背景下启动的？
核心驱动因素是什么？（合规要求？业务增长？技术债务？）
项目的利益相关方有哪些？

反面教材：「本项目旨在提升系统架构水平，优化技术栈。」——这种话等于什么都没说。

正确写法：「2025年Q3，业务部门反馈订单处理系统在日均订单量超过50万笔时出现响应延迟（P99 > 3s），同时核心数据库已达单表容量上限。本次架构改造的目标是支撑日均200万笔订单的处理能力，同时将系统可用性从 99.9% 提升至 99.95%。」

2.2 架构范围与约束条件

范围决定了你这份文档要覆盖哪些内容、不覆盖哪些内容。这一节需要明确：

时间范围：基线描述的是哪个时间点的状态？目标架构预计何时达成？
业务范围：覆盖哪些业务线、哪些业务流程？
技术范围：覆盖哪些系统、哪些技术层？
排除项：明确不纳入本次架构设计的部分

约束条件也很重要，比如预算上限、合规要求、遗留系统不可替换等。这些约束直接影响你在目标架构中做出的设计选择。

2.3 架构原则与目标

架构原则是指导设计决策的「宪法」，比如：

数据主权原则：核心数据不出境
云优先原则：新系统优先部署在私有云上
解耦原则：系统间通过 API 通信，禁止直连数据库

目标则是可衡量的终态描述，最好用 SMART 格式：

具体的：将订单系统从单体架构拆分为微服务架构
可衡量的：系统支持水平扩容至10个实例
可达成的：基于现有技术团队能力
相关的：与业务部门的增长计划对齐
有时限的：2026年Q4前完成核心拆分

三、概念层与逻辑层：两种写法该怎么拆

这是本文最核心的部分。架构定义文档的写法可以分为两个层次：概念层和逻辑层。很多文档之所以让人看不懂，就是因为把这两个层次混在一起写了。

3.1 概念层：告诉非技术人员「我们要做什么」

概念层的目标读者是业务负责人、项目管理者、架构评审委员会。这一层需要回答：

系统的核心业务能力是什么？
各模块之间的关系是什么？（不需要技术细节）
从现状到目标，业务上会发生什么变化？

概念层的典型产出物：

业务能力地图（Capability Map）：用树状结构展示企业具备哪些业务能力
价值流图（Value Stream）：从客户触发到价值交付的完整路径
组织架构图 + 角色职责矩阵：谁负责什么
概念级组件图：用业务语言描述系统模块（不是微服务，不是容器，是「订单管理」「库存中心」这种业务概念）

写法要点：

用业务术语，不要出现技术名词（Kafka、Redis、K8s 这些统统不要）
每个模块用一句话说明它的职责
模块之间的关系用业务语义描述（「订单创建后触发库存扣减」而不是「发送消息到 MQ」）
用颜色或标注区分「保留」「新建」「改造」「废弃」

3.2 逻辑层：告诉技术团队「系统怎么建」

逻辑层的目标读者是架构师、技术负责人、开发团队。这一层需要回答：

系统由哪些逻辑组件构成？
组件之间如何交互？（接口协议、数据流向）
数据在系统中如何流转和存储？
部署拓扑是什么样的？

逻辑层的典型产出物：

应用架构图（Application Architecture Diagram）：逻辑组件及其交互关系
数据架构图（Data Architecture Diagram）：数据实体、数据流向、存储选型
集成架构图（Integration Architecture Diagram）：系统间的接口定义
部署架构图（Deployment Architecture Diagram）：物理或云环境上的部署拓扑
安全架构图（Security Architecture Diagram）：认证、授权、数据加密方案

写法要点：

每张图配一段文字说明，解释设计决策背后的原因
标注技术选型及其依据（「选用 PostgreSQL 而非 MySQL，因为需要 JSONB 支持半结构化数据查询」）
标注非功能性需求在设计中的体现（「此处的读写分离是为了满足 P99 < 200ms 的查询延迟要求」）
对关键接口给出简要的契约定义（输入、输出、错误码）

3.3 概念层和逻辑层如何衔接？

两层之间的桥梁是架构构建块（Architecture Building Blocks，ABB） 和解决方案构建块（Solution Building Blocks，SBB） 的映射关系。

简单来说：

概念层定义 ABB：「我们需要一个订单处理能力」（What）
逻辑层定义 SBB：「我们用订单微服务 + 事件总线来实现这个能力」（How）

在文档中，你可以用一张映射表来衔接两层：

业务能力（ABB）	逻辑组件（SBB）	技术实现	状态
订单管理	订单服务	Spring Boot + PostgreSQL	改造
库存管理	库存服务	Go + Redis + TiDB	新建
支付处理	支付网关	Node.js + 第三方支付SDK	保留
物流跟踪	物流服务	Python + Kafka + MongoDB	新建

这张表就是概念层和逻辑层之间最直接的桥梁。业务方看左两列就能理解系统全貌，技术团队看右两列就知道要干什么。

四、基线架构和目标架构：怎么写才能形成有效对比

架构定义文档的核心价值在于从 A 到 B 的变化路径。基线和目标的写法直接决定了文档的实用性。

4.1 基线架构怎么写

基线不是「把所有现有系统的架构图贴一遍」，而是有选择性地描述与本次架构变更相关的现状。

基线架构应该包含：

现状概览图：一张图展示当前系统的全貌（不需要画到细节）
痛点清单：当前架构存在哪些问题？每个问题附上证据（监控数据、故障记录、性能报告）
技术债务清单：哪些已知的技术债需要在本次改造中处理？
依赖关系图：当前系统的外部依赖有哪些？（上下游系统、第三方服务）

基线描述的关键原则：只描述与变更相关的内容。 如果你的项目只改造订单系统，那基线中不需要详细描述 CRM 系统的内部架构，只需要说明订单系统和 CRM 之间的接口关系。

4.2 目标架构怎么写

目标架构描述的是改造完成后的预期状态。它需要足够详细，让开发团队能够据此进行详细设计，但又不能太详细以至于限制了实现层面的灵活性。

目标架构应该包含：

目标状态全景图：改造完成后的系统全貌
核心设计决策：列出 3-5 个关键的设计决策及其理由
组件详细描述：每个主要组件的职责、接口、约束
数据流图：核心业务流程在目标架构中的数据流转路径
非功能性架构：高可用、容灾、弹性伸缩、安全合规的设计方案

4.3 差距分析怎么写

差距分析是连接基线和目标的桥梁。它回答一个核心问题：从现在到未来，需要改变什么？

标准的差距分析表格式如下：

架构域	基线状态	目标状态	差距描述	变更类型	影响评估	优先级
订单处理	单体应用，Oracle数据库	微服务架构，PostgreSQL分库分表	需拆分服务+数据迁移	重构	高：影响核心交易链路	P0
库存查询	直连数据库查询	Redis缓存+异步同步	需引入缓存层	改造	中：影响查询性能	P1
支付对接	硬编码第三方支付SDK	支付网关统一对接	需抽象支付接口	新建	中：影响支付流程	P0
日志采集	本地文件日志	ELK集中式日志	需改造日志输出方式	改造	低：不影响业务	P2

差距分析的价值在于：它直接驱动了 Phase E（机会与解决方案）的工作包拆解。每一条差距都对应一个或多个实施项目。

五、TOGAF ADM 各阶段的文档产出

TOGAF ADM 共有 9 个阶段（含预备阶段），每个阶段都有明确的文档产出。下面从实操角度梳理每个阶段你应该产出什么文档。

预备阶段（Preliminary Phase）

核心产出：

架构能力框架（Architecture Capability Framework）
架构原则文档（Architecture Principles）
架构治理框架（Architecture Governance Framework）
定制化的架构方法论（根据组织情况裁剪 TOGAF）

实操要点： 预备阶段的文档通常是组织级别的，不是项目级别的。如果你是第一次在组织中推行 TOGAF，这些文档需要从头建；如果组织已有 EA 实践，则复用并更新。

Phase A：架构愿景

核心产出：

架构愿景文档（Architecture Vision）
架构工作请求（Request for Architecture Work）
利益相关方地图（Stakeholder Map）
能力评估（Capability Assessment）
架构定义文档的初始版本（仅有范围和目标部分）

实操要点： Phase A 的 ADD 只需要写第一章（项目背景）和第二章（范围与约束），以及第三章（原则与目标）的初稿。不需要涉及任何技术细节。

Phase B：业务架构

核心产出：

架构定义文档——业务架构部分
- 基线业务架构（组织结构、业务流程、业务能力地图）
- 目标业务架构
- 业务架构差距分析
架构需求规格说明书——业务需求部分

实操要点： 这一阶段的 ADD 重点是概念层的内容。产出物以业务能力地图、价值流图、组织架构图为主。如果你只做技术架构项目不涉及业务变革，这一部分可以精简。

Phase C：信息系统架构

Phase C 分为两个子阶段：数据架构和应用架构。

核心产出：

架构定义文档——数据架构部分
- 数据实体清单及关系（ER图或概念模型）
- 数据流向图
- 数据治理策略
- 数据架构差距分析
架构定义文档——应用架构部分
- 应用组件清单
- 应用交互关系图
- 接口定义（逻辑级别）
- 应用架构差距分析

实操要点： 这是 ADD 内容最丰富的阶段。应用架构部分需要同时覆盖概念层（业务能力 → 应用映射）和逻辑层（应用组件交互关系）。

Phase D：技术架构

核心产出：

架构定义文档——技术架构部分
- 技术组件清单（计算、存储、网络、中间件）
- 部署拓扑图
- 技术选型决策记录
- 技术架构差距分析
架构需求规格说明书——技术需求部分（性能、可用性、安全等量化指标）

实操要点： 技术架构部分主要面向逻辑层。这里需要给出具体的技术选型和部署方案，但注意保持在「逻辑级别」——不需要给出详细的运维脚本或配置参数。

Phase E：机会与解决方案

核心产出：

架构定义文档——最终版（整合 B/C/D 的全部内容）
架构路线图（Architecture Roadmap）
实施与迁移计划初稿（Implementation and Migration Plan — Draft）

实操要点： Phase E 的 ADD 重点是整合和差距分析。你需要把 B/C/D 阶段发现的差距汇总，评估优先级，然后规划出分阶段的实施路径。这一阶段的 ADD 是评审委员会审批的核心依据。

Phase F：迁移规划

核心产出：

实施与迁移计划——最终版
架构路线图——最终版
过渡架构（Transition Architecture）：如果有多个中间状态，需要描述每个过渡态

实操要点： 这一阶段 ADD 不再是主角，实施与迁移计划成为核心交付物。但 ADD 中的架构路线图需要与迁移计划保持一致。

Phase G：实施治理

核心产出：

架构契约（Architecture Contract）
合规性评估（Compliance Assessment）
变更请求（如有）

实操要点： 实施阶段 ADD 作为「参照基线」使用——开发团队按照 ADD 中描述的目标架构进行建设，架构治理团队依据 ADD 进行合规性审查。

Phase H：架构变更管理

核心产出：

架构变更请求
更新后的架构定义文档
经验教训文档

实操要点： 任何对已批准的目标架构的变更，都需要走变更管理流程。ADD 需要根据变更请求进行更新，并记录变更原因。

六、实操建议：让架构定义文档真正被用起来

6.1 文档不是越多越好

TOGAF 标准列出了大量的交付物和制品（Artifacts），但并不意味着每个项目都需要产出全部文档。根据项目规模做裁剪：

小型项目（单系统改造）：ADD 可以精简为 10-20 页，重点写基线/目标/差距
中型项目（跨系统改造）：ADD 通常 30-60 页，需要完整的概念层和逻辑层
大型项目（企业级转型）：ADD 可能超过 100 页，建议按架构域拆分为子文档

6.2 图比文字重要

架构定义文档中最有价值的内容是架构图。一张好的架构图胜过十页文字描述。

画图的几个原则：

一张图只说一件事：不要试图在一张图中塞入所有信息
分层展示：概念图给业务方看，逻辑图给技术团队看
用颜色编码：绿色=新建、蓝色=保留、黄色=改造、红色=废弃
图例必须有：每个符号、每种颜色都要在图例中说明

6.3 版本管理

ADD 是活文档，它会随着项目推进不断更新。建议：

每个 ADM 阶段结束时更新一次版本号
用变更日志记录每次更新的内容和原因
重大变更（如目标架构调整）需要走正式的评审和审批流程

6.4 用架构决策记录（ADR）补充 ADD

ADD 描述的是「架构长什么样」，但很多时候你需要记录「为什么这样设计」。这就是架构决策记录（Architecture Decision Record，ADR）的价值。

每条 ADR 包含：

背景：遇到了什么问题？
决策：做了什么选择？
后果：这个选择带来了什么影响？（正面的和负面的）

ADR 作为 ADD 的附录存在，让文档既有「是什么」，也有「为什么」。

七、简化版架构定义文档模板

以下是一个可以直接复用的简化版模板，适用于中型项目的架构设计：

# [项目名称] 架构定义文档

**版本：** v1.0  
**日期：** YYYY-MM-DD  
**作者：** [架构师姓名]  
**状态：** 草案 / 评审中 / 已批准

---

## 1. 概述

### 1.1 项目背景
[描述业务背景、触发因素、项目目标，200字以内]

### 1.2 文档范围
- 覆盖范围：[列出涉及的系统/业务域]
- 排除范围：[明确不纳入的部分]
- 时间范围：基线=[当前日期]，目标=[预期达成日期]

### 1.3 利益相关方
| 角色 | 关注点 | 参与方式 |
|------|--------|---------|
| 业务负责人 | 业务连续性、交付时间 | 评审会 |
| 技术负责人 | 技术选型、团队能力 | 架构评审 |
| 运维负责人 | 可运维性、监控告警 | 方案评审 |

---

## 2. 架构原则与目标

### 2.1 适用原则
- [原则1]：[简要说明]
- [原则2]：[简要说明]

### 2.2 架构目标
| 目标 | 衡量标准 | 达成时间 |
|------|---------|---------|
| [目标1] | [量化指标] | [时间节点] |
| [目标2] | [量化指标] | [时间节点] |

---

## 3. 基线架构（当前状态）

### 3.1 现状全景图
[插入架构图 + 图例说明]

### 3.2 核心组件描述
| 组件 | 职责 | 技术栈 | 已知问题 |
|------|------|--------|---------|
| [组件1] | [职责] | [技术] | [问题] |

### 3.3 痛点与技术债务
| 编号 | 问题描述 | 影响范围 | 严重程度 | 证据 |
|------|---------|---------|---------|------|
| P1 | [描述] | [范围] | 高/中/低 | [监控数据/故障记录] |

---

## 4. 目标架构（未来状态）

### 4.1 目标全景图
[插入架构图 + 图例说明]

### 4.2 概念层：业务能力与组件映射
| 业务能力 | 逻辑组件 | 职责描述 |
|---------|---------|---------|
| [能力1] | [组件1] | [描述] |

### 4.3 逻辑层：组件详细描述

#### 4.3.1 [组件名称]
- **职责**：[一句话描述]
- **接口**：[主要接口列表]
- **依赖**：[依赖的其他组件]
- **技术选型**：[选型及理由]
- **约束**：[非功能性约束]

### 4.4 数据架构
[数据实体关系图 + 数据流图 + 存储选型说明]

### 4.5 集成架构
[系统间接口清单 + 交互协议]

### 4.6 部署架构
[部署拓扑图 + 环境规划]

### 4.7 关键设计决策
| 编号 | 决策 | 选项 | 选择理由 |
|------|------|------|---------|
| D1 | [决策] | [可选方案A/B] | [理由] |

---

## 5. 差距分析

| 架构域 | 基线 | 目标 | 差距 | 变更类型 | 影响 | 优先级 |
|--------|------|------|------|---------|------|--------|
| [域1] | [现状] | [目标] | [差距] | 新建/改造/废弃 | 高/中/低 | P0/P1/P2 |

---

## 6. 架构路线图

### 6.1 阶段划分
| 阶段 | 时间 | 主要内容 | 交付物 |
|------|------|---------|--------|
| 第一阶段 | [时间] | [内容] | [交付物] |
| 第二阶段 | [时间] | [内容] | [交付物] |

### 6.2 依赖关系
[阶段间的依赖关系说明]

---

## 7. 风险与约束

| 风险 | 可能性 | 影响 | 缓解措施 |
|------|--------|------|---------|
| [风险1] | 高/中/低 | 高/中/低 | [措施] |

---

## 附录

### A. 术语表
| 术语 | 定义 |
|------|------|
| [术语] | [定义] |

### B. 架构决策记录（ADR）
[ADR 列表]

### C. 参考资料
[参考文档列表]

八、常见踩坑与应对

8.1 坑一：基线描述过于详细

现象： 花了三周时间把现有系统的所有细节都画了出来，ADD 基线部分写了80页。

应对： 基线只描述与变更相关的内容。问自己：「这个信息对理解差距分析有帮助吗？」如果没有，删掉。

8.2 坑二：目标架构过于理想化

现象： 目标架构画得像教科书案例，完全忽略了团队能力、预算限制、时间约束。

应对： 目标架构必须在约束条件下可达成。写目标的时候，每条设计决策都要回答：「以当前的团队能力和预算，这个方案能落地吗？」

8.3 坑三：差距分析流于形式

现象： 差距分析只写了「需要改造」「需要新建」，没有说明影响评估和优先级。

应对： 差距分析必须包含影响评估（影响哪些业务流程、哪些上下游系统）和优先级排序。它是后续迁移规划的直接输入。

8.4 坑四：概念层和逻辑层混写

现象： 同一张图里既有「订单管理」这样的业务概念，又有「Kafka Topic: order-events」这样的技术细节。

应对： 严格分层。概念层的图只出现业务术语，逻辑层的图才出现技术组件。两层之间用映射表衔接。

8.5 坑五：文档写完就束之高阁

现象： ADD 在评审会上通过了，之后再也没有人更新过，实际开发偏离了设计也没人知道。

应对： 建立架构治理机制——每个迭代结束时，对照 ADD 检查实施是否符合设计；如有偏差，走变更管理流程更新 ADD。

九、工具推荐

写架构定义文档，以下工具组合比较实用：

用途	推荐工具	说明
文档编写	Confluence / Notion / Markdown	支持协作和版本管理
架构图绘制	Draw.io / Lucidchart / PlantUML	Draw.io 免费，PlantUML 适合代码化
架构建模	ArchiMate / Sparx EA	支持 TOGAF 标准建模语言
决策记录	ADR Tools / 项目 Wiki	轻量级，跟代码一起版本管理
差距跟踪	JIRA / 飞书多维表格	差距条目直接转为工作项

十、总结

架构定义文档不是一个形式主义的产物，而是架构工作中投入产出比最高的文档。一份好的 ADD 能够：

对齐认知：让业务方和技术团队对系统现状和未来方向达成一致理解
驱动决策：通过差距分析明确优先级，避免「拍脑袋」决定先做什么
沉淀知识：让架构决策有据可查，新人接手时不用从零开始
支撑治理：为实施阶段的合规性检查提供参照基线

写好 ADD 的核心要诀就是八个字：分层表达，基线对齐。

概念层让业务方看得懂，逻辑层让技术团队做得出。基线描述现状的痛点，目标描述未来的蓝图。差距分析连接两者，架构路线图指明路径。

如果你正在着手写一份架构定义文档，不妨从上面的简化模板开始，先把骨架搭起来，再逐步丰富内容。记住：一份 20 页但被团队持续使用的 ADD，远胜于一份 200 页但没人看的文档。

架构定义文档 on 文艺技术笔记

应用架构定义文档怎么写？从基线到目标的 TOGAF 模板实操拆解

一、架构定义文档是什么？为什么它这么重要？

1.1 一句话定义

1.2 ADD 在 TOGAF 体系中的位置

1.3 ADD 和架构需求文档的区别

二、架构定义文档的标准结构

2.1 文档概述与项目背景

2.2 架构范围与约束条件

2.3 架构原则与目标

三、概念层与逻辑层：两种写法该怎么拆

3.1 概念层：告诉非技术人员「我们要做什么」

3.2 逻辑层：告诉技术团队「系统怎么建」

3.3 概念层和逻辑层如何衔接？

四、基线架构和目标架构：怎么写才能形成有效对比

4.1 基线架构怎么写

4.2 目标架构怎么写

4.3 差距分析怎么写

五、TOGAF ADM 各阶段的文档产出

预备阶段（Preliminary Phase）

Phase A：架构愿景

Phase B：业务架构

Phase C：信息系统架构

Phase D：技术架构

Phase E：机会与解决方案

Phase F：迁移规划

Phase G：实施治理

Phase H：架构变更管理

六、实操建议：让架构定义文档真正被用起来

6.1 文档不是越多越好

6.2 图比文字重要

6.3 版本管理

6.4 用架构决策记录（ADR）补充 ADD

七、简化版架构定义文档模板

八、常见踩坑与应对

8.1 坑一：基线描述过于详细

8.2 坑二：目标架构过于理想化

8.3 坑三：差距分析流于形式

8.4 坑四：概念层和逻辑层混写

8.5 坑五：文档写完就束之高阁

九、工具推荐

十、总结