概述

手册是一份指导性文档，而非固定模板。它旨在帮助系统架构师回答三个核心问题：

1. 1. 做什么——每个架构章节要完成的目标
2. 2. 怎么做——具体的设计方法和实践要点
3. 3. 做成什么样——标准示例和评估标准

本手册融合了多个国际国内标准的精髓：ISO/IEC/IEEE 42010（架构描述国际标准）的“视图-关注点”框架[reference:0]、、C4模型的层次化可视化方法[reference:2]、TOGAF ADM的架构制品体系[reference:3]，以及GB/T 45630-2025《系统与软件工程 架构描述》国家标准[reference:4]。同时，本手册也适用于敏捷开发环境，强调轻量级与实用主义——在迭代过程中逐步完善架构文档，而非大型预先设计[reference:5]。

快速索引

系统架构设计文档：架构师指导手册

第1节 文档概述与目标

本节目的：为所有读者建立对本文档的统一理解，明确文档的用途、范围和读者对象，确保干系人能够快速定位到自己关注的内容。

1.1 编写目的

做什么：说明编写这份架构文档的原因和预期用途。

关键思考：

• • 本文档是为哪类读者服务的？（业务方、开发、测试、运维、安全、合规）
• • 文档要支撑哪些活动？（设计评审、开发实施、测试验证、部署运维、安全审计）
• • 文档的生命周期是多久？（项目交付后是否继续维护）

示例：

本文档旨在为“XX电商平台”提供完整的系统架构蓝图，目标读者包括：- 业务架构师：确认业务能力与技术实现的映射关系- 开发工程师：理解模块职责和接口契约，指导代码实现- 测试工程师：理解系统边界和集成点，设计测试用例- 运维工程师：理解部署拓扑和监控指标，制定运维方案- 安全审计员：理解安全控制点，进行等保合规评估本文档将作为系统设计、开发、测试、部署和运维的统一基线，在系统全生命周期内持续维护和更新。

1.2 文档范围

做什么：界定本文档覆盖的架构层级和范围，明确哪些内容包含、哪些内容不包含。

关键思考：

• • 文档涵盖哪些架构视图？（业务、应用、数据、技术、部署、安全）
• • 是否有超出范围的系统或模块？（如第三方黑盒系统）
• • 文档与概要设计、详细设计的分界是什么？

示例：

本文档覆盖架构设计层面，包括业务架构、应用架构、数据架构、技术架构、部署架构和安全架构。概要设计和详细设计（如类图、序列图、伪代码）不在本文档范围内，将在后续设计阶段产出。

1.3 术语表

做什么：定义文档中使用的专业术语和缩写，确保所有干系人使用统一语言。

关键思考：

• • 哪些术语容易引起歧义？
• • 是否使用了团队不熟悉的缩写或技术名词？
• • 是否有领域特定的业务术语需要定义？

示例：

1.4 参考文献

做什么：列出本架构文档所依据或引用的外部文档、标准、规范。

关键思考：

• • 是否有项目立项文档、业务需求文档需要引用？
• • 是否有行业标准、法律法规需要遵循？
• • 是否有外部系统的接口文档需要关联？

示例：

[1] 项目立项报告：XX电商平台项目V1.0[2] 产品需求规格说明书：XX电商平台PRD_V2.3[3] GB/T 22239-2019《信息安全技术 网络安全等级保护基本要求》[4] GB/T 45630-2025《系统与软件工程 架构描述》[5] ISO/IEC/IEEE 42010:2011《Systems and software engineering — Architecture description》[6] 第三方支付系统接口规范（支付宝开放平台API V3）

第2节 架构背景与约束

本节目的：建立架构设计的上下文环境，明确设计的目标、约束条件和成功标准，确保架构决策与业务目标对齐。

2.1 业务目标

做什么：明确系统要解决的业务问题和核心价值主张。

关键思考：

• • 业务方最关心的2-3个核心问题是什么？
• • 系统成功的关键业务指标有哪些？
• • 业务的发展预期是怎样的？（用户量、交易量增长）

示例：

1. 核心业务目标：   - 支持日峰值100万订单的处理能力   - 将系统平均响应时间控制在200ms以内   - 实现全年99.99%的系统可用性2. 业务价值指标：   - 提升用户下单转化率10%   - 降低支付失败率至0.5%以下   - 支持双11大促期间峰值流量冲击

2.2 关键质量指标（量化）

做什么：将质量属性转化为可量化的指标目标，为架构设计提供明确的成功标准。

关键思考：

• • 每个质量属性如何量化？（可用性用百分比还是MTBF？）
• • 指标的测量方法和数据来源是什么？
• • 是否有历史数据或行业基准可参考？

示例：

2.3 业务约束

做什么：记录来自业务方的限制条件，如预算、时间、资源、合规等。

关键思考：

• • 项目的时间约束是什么？（上线日期、里程碑）
• • 预算限制会影响哪些架构选择？
• • 是否有组织层面的限制？（如必须使用集团统一中间件）
• • 是否有合规要求？（金融合规、数据出境）

示例：

1. 时间约束：系统需在6个月内上线V1.0版本2. 预算约束：首年IT基础设施预算不超过200万元3. 组织约束：必须使用公司统一的微服务框架和配置中心4. 数据合规：用户数据必须存储在中国境内，满足数据安全法要求

2.4 技术约束

做什么：明确技术层面的限制条件，包括必须使用的技术栈、禁止使用的技术、集成限制等。

关键思考：

• • 是否有遗留系统必须集成？
• • 团队的技术能力边界在哪里？
• • 是否存在供应商锁定问题需要规避？

示例：

1. 技术栈强制要求：   - 后端语言：Java 17+   - 数据库：MySQL 8.0（主库）/ PostgreSQL（备选）   - 部署平台：Kubernetes 1.24+2. 禁止使用：   - 禁止在生产环境使用内存数据库作为主存储   - 禁止使用未经安全审计的开源组件3. 集成限制：   - 必须与公司统一身份认证系统（SSO）集成   - 必须对接公司统一日志平台（ELK）

第3节 核心架构决策（ADR）

本节目的：记录架构设计中的关键决策及其背景、理由和影响，确保决策可追溯、可复用。ADR是架构文档中“最有价值”的部分，它回答了“为什么”的问题——这些知识最容易在项目交接时丢失。

3.1 ADR模板与规范

做什么：建立统一的ADR记录格式和编号规范。

关键思考：

• • ADR应包含哪些必要字段？（编号、标题、状态、上下文、决策、理由、影响、备选方案）
• • ADR的生命周期如何管理？（提案→接受→废弃→取代）
• • ADR应该存放在哪里？（与代码同仓库，便于版本追踪）

标准ADR模板：

# ADR-XXX: [决策标题]**状态**: [提案中 / 已接受 / 已废弃 / 已取代]**决策者**: [姓名/角色]**决策日期**: YYYY-MM-DD## 上下文[描述做出决策的背景、问题和约束条件]## 决策[明确陈述最终的决策结论]## 理由[解释为什么做出这个决策，包括技术、业务、团队等方面的考量]## 影响[列出此决策带来的正面和负面影响]## 备选方案[列出考虑过的替代方案及其优缺点]## 关联决策[引用相关的其他ADR编号]## 备注[补充说明、参考资料链接]

3.2 ADR编写方法

做什么：掌握如何系统化地编写高质量的ADR。

关键思考：

• • 什么级别的决策需要记录为ADR？
• • 如何确保ADR的“五W一H”完整？（Why、What、Who、When、Where、How）
• • ADR如何与代码、配置保持同步？

编写要点：

1. 1. 及时记录：决策做出后立即记录，而非事后补充
2. 2. 保持精简：每个ADR聚焦单一决策，避免“大包大揽”
3. 3. 版本可控：ADR纳入Git管理，每次变更产生可追溯的记录
4. 4. 链接代码：在代码注释中引用ADR编号，实现决策与实现的双向追溯

实践要点：在敏捷开发中，采用轻量级架构决策记录方式，将其与代码等其他项目资产一同纳入版本控制系统，以应对项目知识传递的挑战[reference:6]。

3.3 ADR示例

做什么：通过实际案例展示ADR的标准写法。

示例1：微服务拆分策略

# ADR-001: 采用微服务架构**状态**: 已接受**决策者**: 技术委员会**决策日期**: 2026-01-15## 上下文当前业务增长迅速，预计6个月内用户数增长10倍。团队规模将从5人扩展至20人。需要决定系统的整体架构风格。## 决策采用微服务架构，按业务域拆分为订单服务、库存服务、支付服务、用户服务四个独立服务。## 理由1. 团队规模扩大后，不同小组可以独立开发和部署各自负责的服务2. 核心业务（支付、订单）需要独立扩展，单体架构无法满足3. 不同服务对数据库有不同要求（订单用MySQL、库存用Redis）4. 微服务架构符合公司现有技术生态## 影响- 正面：独立部署、独立扩展、技术栈灵活、故障隔离- 负面：分布式事务复杂度增加、运维成本上升、服务间调用延迟## 备选方案- 单体架构：实现简单，但无法满足扩展性要求- 模块化单体：折中方案，但模块间仍存在耦合风险

示例2：缓存选型

# ADR-002: 选择Redis作为分布式缓存**状态**: 已接受**决策者**: 技术架构组**决策日期**: 2026-01-20## 上下文系统需要缓存热点数据（商品信息、库存、Session），预估缓存数据量约100GB，QPS峰值约5万。需要选择分布式缓存方案。## 决策选择Redis 7.0，部署为集群模式，采用Redis Sentinel实现高可用。## 理由1. Redis支持丰富的数据结构（String、Hash、Set、ZSet），满足业务多样性需求2. 单实例可达10万QPS，性能满足要求3. 公司已有成熟的Redis运维经验4. 社区活跃，问题解决速度快## 影响- 正面：高性能、高可用、易于使用- 负面：需要额外运维成本（哨兵集群）## 备选方案- Memcached：仅支持String，无法满足库存ZSet排序需求- Hazelcast：Java原生集成，但社区规模较小

3.4 架构风格

做什么：明确系统的整体架构风格，作为后续所有架构设计的基础假设。

关键思考：

• • 当前业务场景最适合哪种架构风格？
• • 架构风格选择是否符合团队能力？
• • 是否需要混合多种架构风格？

示例：

系统采用**微服务+事件驱动**混合架构风格：- 微服务部分：业务域按功能垂直拆分，服务间通过REST/gRPC同步调用- 事件驱动部分：跨服务状态变更（订单创建、库存变更）通过Kafka异步事件解耦- 分层结构：API网关 → 业务服务层 → 基础服务层 → 数据层

第4节 业务架构

本节目的：将业务需求转化为系统化的业务能力模型，作为应用架构设计的输入。业务架构是所有架构的“翻译器”——它将业务方的语言翻译为技术团队可以理解的结构。

4.1 核心业务流程

做什么：使用流程图描述系统支持的核心业务场景，展示业务流转路径和关键决策点。

关键思考：

• • 哪些是系统的核心业务场景？（通常不超过5个）
• • 业务流程中的关键决策点和分支条件是什么？
• • 异常流程如何处理？

示例：电商下单流程

用户提交订单    │    ▼[订单创建] ──→ 校验商品信息 ──→ 校验用户权限    │                      │    │                      ├── 失败 → 返回错误信息    │                      │    ▼                      ▼[库存预扣] ←───────────────┘    │    ├── 库存不足 → 释放预扣 → 返回失败    │    ▼[生成支付单] ──→ 调用支付网关 ──→ 等待支付回调    │    ▼[支付成功] ──→ 确认扣库存 ──→ 更新订单状态

建议：使用BPMN 2.0或UML活动图绘制，确保业务和技术人员都能理解。

4.2 业务能力清单

做什么：将业务功能组织为层次化的业务能力模型，确保完整覆盖业务需求。

关键思考：

• • 业务能力如何分类和分层？
• • 每个能力的价值和优先级是什么？
• • 能力之间的依赖关系如何？

示例：

说明：P0为最高优先级，系统必须支持；P1为高优先级，建议V1.0支持；P2为后续版本。

4.3 业务对象与数据字典

做什么：定义业务中的核心概念和实体，作为数据架构的输入。

关键思考：

• • 哪些是系统的核心业务实体？
• • 实体之间的关系是什么？
• • 每个实体包含哪些关键属性？

示例：

核心业务对象：1. 订单（Order）：订单ID、用户ID、商品列表、订单金额、订单状态、创建时间2. 用户（User）：用户ID、用户名、手机号、会员等级、注册时间3. 商品（Product）：商品ID、商品名称、价格、库存量、上架状态4. 支付单（Payment）：支付单ID、订单ID、支付金额、支付方式、支付状态业务对象关系：- 用户（1） ── 拥有 ──► 订单（N）- 订单（1） ── 包含 ──► 商品（N）- 订单（1） ── 产生 ──► 支付单（1）

4.4 业务规则

做什么：记录关键的逻辑约束和业务策略，这些规则直接影响架构设计。

关键思考：

• • 哪些业务规则对架构有重要影响？（如事务一致性要求）
• • 规则是否可能频繁变更？（影响配置化设计）
• • 规则之间的冲突如何处理？

示例：

1. 订单规则：   - 单笔订单金额超过10,000元需人工审核   - 订单超过30分钟未支付自动取消（定时任务实现）   - 同一用户30分钟内最多下单100次（限流策略）2. 库存规则：   - VIP用户可购买超出普通库存量20%   - 下单时预扣库存，支付成功时确认扣减，超时未支付释放   - 库存低于安全阈值（10件）时触发补货通知3. 优惠规则：   - 优惠券不可与平台满减叠加使用   - 秒杀商品不参与任何优惠活动

第5节 应用架构

本节目的：将业务能力映射为具体的软件服务/应用，定义服务的边界、职责和交互方式。应用架构是业务架构与技术架构之间的“桥梁”。

5.1 服务/应用划分

做什么：识别并划分系统的各个应用或服务，明确每个服务的职责边界。

关键思考：

• • 服务划分原则是什么？（按业务域、按数据边界、按变更频率）
• • 每个服务的“大小”如何把握？（既要避免“上帝服务”，也要避免“微服务碎成沙”）
• • 服务之间的依赖关系如何管理？

划分原则：

1. 1. 单一职责：每个服务聚焦一个明确的业务能力
2. 2. 高内聚低耦合：内部逻辑高度相关，外部依赖最小化
3. 3. 独立部署：服务可独立构建、测试、部署和回滚
4. 4. 独立数据：每个服务拥有自己的数据库或Schema

示例：

5.2 应用间交互

做什么：定义服务之间的通信方式、协议和数据格式，绘制应用交互图。

关键思考：

• • 同步调用 vs 异步消息的边界在哪里？
• • 服务发现和服务路由如何实现？
• • 跨服务的分布式事务如何处理？

交互方式选择：

• • 同步（REST/gRPC）：需要即时响应、强一致性的场景（如用户登录、订单查询）
• • 异步（Kafka/RabbitMQ）：可最终一致、需要削峰填谷的场景（如订单创建后发送通知、库存预扣后的状态同步）

示例：订单创建服务调用链

API网关   │   ├──→ 订单服务 (同步)   │      ├──→ 商品服务 (同步) ── 校验商品信息   │      ├──→ 用户服务 (同步) ── 校验用户状态   │      └──→ 库存服务 (同步) ── 预扣库存   │   └──→ 消息队列 (异步)          ├──→ 通知服务 ── 发送订单成功通知          ├──→ 统计服务 ── 记录业务埋点          └──→ 数据同步 ── 同步至数仓

5.3 关键业务流程序列图

做什么：针对核心业务场景，使用时序图（Sequence Diagram）详细描述参与对象的交互过程。

关键思考：

• • 序列图应展示哪些参与者？（用户、前端、网关、各微服务、数据库、消息队列）
• • 异常分支和超时处理是否需要体现？
• • 是否区分同步调用和异步调用？

示例：下单支付完整时序图

提示：在敏捷开发中，序列图应聚焦核心场景（Happy Path），异常流程可在详细设计阶段补充[reference:7]。

第6节 数据架构

本节目的：设计系统的数据模型、存储策略、分布方案和生命周期管理。数据架构是系统中最稳定、变更成本最高的部分，需要重点设计。

6.1 数据模型设计

做什么：建立概念模型、逻辑模型和物理模型，定义核心实体的结构和关系。

关键思考：

• • 哪些是核心实体，哪些是弱实体？
• • 实体之间的关系是1:N、N:N还是1:1？
• • 是否需要考虑数据的历史版本和变更追踪？

设计方法：

1. 1. 概念模型：从业务实体出发，抽象出核心实体及其关系（与技术实现无关）
2. 2. 逻辑模型：在概念模型基础上加入属性、主键、外键等细节（ER图）
3. 3. 物理模型：根据数据库特性进行优化（索引、分区、存储参数）

示例：订单模块物理模型

-- 订单主表CREATE TABLE t_order (    order_id BIGINTPRIMARY KEY COMMENT '订单ID',    user_id BIGINTNOT NULL COMMENT '用户ID',    order_amount DECIMAL(10,2) NOT NULL COMMENT '订单金额',    order_status TINYINT NOT NULL COMMENT '订单状态:0-待支付,1-已支付,2-已取消,3-已完成',    pay_time DATETIME COMMENT '支付时间',    create_time DATETIME NOT NULL COMMENT '创建时间',    update_time DATETIME NOT NULL COMMENT '更新时间',    INDEX idx_user_id (user_id),    INDEX idx_create_time (create_time)) COMMENT='订单主表'PARTITIONBYRANGE (YEAR(create_time));-- 订单商品明细表CREATE TABLE t_order_item (    item_id BIGINTPRIMARY KEY,    order_id BIGINTNOT NULL,    product_id BIGINTNOT NULL,    quantity INTNOT NULL,    price DECIMAL(10,2) NOT NULL,    INDEX idx_order_id (order_id)) COMMENT='订单明细表';

6.2 数据分布与分片策略

做什么：设计数据在不同存储节点间的分布方式，解决单库性能瓶颈和扩展性问题。

关键思考：

• • 数据量预估是多少？（百万、千万、亿级？）
• • 查询模式是怎样的？（按用户查询、按时间查询、还是按订单号查询？）
• • 分片键如何选择？（需要保证数据均匀分布）

常见分片策略：

示例：

订单数据分片策略：- 分片键：user_id（业务查询通常带用户维度）- 分片数：16个分片（预估未来3年增长）- 分片算法：hash(user_id) % 16- 路由规则：应用层Sharding（ShardingSphere）热冷分离：- 热数据（近30天订单）：SSD存储，保留在在线库- 冷数据（30天-1年）：SATA存储，迁移至历史库- 归档数据（>1年）：压缩存储至对象存储

6.3 数据存储选型矩阵

做什么：根据数据特性和访问模式，为不同数据选择最适合的存储引擎。

关键思考：

• • 数据是结构化还是非结构化？
• • 读写比例是多少？（读多写少 vs 写多读少）
• • 是否需要全文搜索或复杂聚合？

示例：

6.4 数据生命周期管理

做什么：定义数据从创建到销毁的完整生命周期，包括保留策略、归档机制和清理流程。

关键思考：

• • 各类数据应保留多长时间？（法律法规要求 vs 业务需求）
• • 数据销毁时是否需要脱敏或加密？
• • 归档数据的查询需求如何满足？

示例：

订单数据生命周期：- 创建：下单时写入在线库- 在线期（0-30天）：保持在高性能存储，支持实时查询- 温数据期（31-365天）：迁移至历史库，支持查询（响应时间≤2秒）- 冷数据期（1-3年）：压缩归档至OSS，仅支持离线查询- 销毁期（>3年）：物理删除，销毁前需脱敏处理自动调度策略：- 每日凌晨2点：将>30天订单迁移至历史库- 每周日凌晨3点：将>1年订单导出压缩并上传OSS- 每月1日凌晨4点：清理>3年订单记录并记录审计日志

6.5 数据一致性设计

做什么：明确不同场景下的一致性要求，并设计相应的一致性保障机制。

关键思考：

• • 哪些场景必须强一致性？（支付、扣库存）
• • 哪些场景可以接受最终一致性？（订单状态同步、用户积分更新）
• • 分布式事务如何处理？

示例：

一致性分级：1. 强一致性（支付流程）：   - 使用本地事务（@Transactional）   - 跨服务事务使用TCC（Try-Confirm-Cancel）模式   - 幂等性设计（唯一请求ID + Redis锁）2. 最终一致性（订单状态同步）：   - 使用消息队列异步处理   - 消息重试机制（最多3次，指数退避）   - 死信队列 + 人工介入3. 弱一致性（用户浏览记录）：   - 异步写入，允许丢失   - 不需要事务保障

6.6 数据库设计规范

1. 命名规范

1.1 基本规则

1.2 表命名

1.3 字段命名

1.4 索引命名

2. 表设计规范

2.1 必备字段

每个业务表必须包含以下6个字段：

建表语句示例：

CREATE TABLE `t_order` (    `id` BIGINT UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '主键ID',    `user_id` BIGINT UNSIGNED NOT NULL COMMENT '用户ID',    `order_amount` DECIMAL(10,2) NOT NULL COMMENT '订单金额',    `order_status` TINYINT NOT NULLDEFAULT0 COMMENT '订单状态：0-待支付，1-已支付，2-已取消',    `created_time` DATETIME(3) NOT NULLDEFAULTCURRENT_TIMESTAMP(3) COMMENT '创建时间',    `updated_time` DATETIME(3) NOT NULLDEFAULTCURRENT_TIMESTAMP(3) ONUPDATECURRENT_TIMESTAMP(3) COMMENT '更新时间',    `version` INT UNSIGNED NOT NULLDEFAULT1 COMMENT '版本号',    `is_deleted` TINYINT(1) NOT NULLDEFAULT0 COMMENT '逻辑删除',    `create_by` VARCHAR(64) DEFAULTNULL COMMENT '创建人',PRIMARY KEY (`id`),    KEY `idx_user_id` (`user_id`)) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci COMMENT='订单表';

2.2 存储引擎与字符集

2.3 表注释

每个表必须有注释，说明表的业务用途。

COMMENT='订单主表，记录用户每次下单的核心信息'

2.4 表分区规范

3. 字段设计规范

3.1 数据类型选择

关键约束：

• • 禁止使用 FLOAT/DOUBLE 存储金额，必须使用 DECIMAL
• • 禁止使用 NULL 替代默认值，除非业务明确允许（见3.2）
• • 禁止使用 ENUM 类型（扩展性差、跨数据库兼容性差）

3.2 NULL与默认值

例外情况：业务语义上确实“不存在”的字段（如订单的取消原因），可以使用NULL。

3.3 字段注释

每个字段必须有注释，说明业务含义、单位、枚举值映射。

`order_amount` DECIMAL(10,2) NOT NULL COMMENT '订单金额（单位：元），用户实际支付金额',`order_status` TINYINT NOT NULLDEFAULT0 COMMENT '订单状态：0-待支付，1-已支付，2-已取消，3-已完成',

3.4 字段顺序

建议按以下逻辑顺序排列字段：

1. 1. 主键（id）
2. 2. 业务核心字段（如 user_id、order_no）
3. 3. 业务描述字段（如 remark）
4. 4. 状态、计数字段
5. 5. 审计字段（created_time、updated_time、version、is_deleted、create_by）

4. 索引设计规范

4.1 索引创建原则

4.2 必须创建索引的场景

4.3 索引规范示例

-- 单列索引KEY `idx_user_id` (`user_id`)-- 联合索引（等值查询在前，范围查询在后）KEY `idx_user_id_status` (`user_id`, `order_status`)-- 唯一索引UNIQUE KEY `uk_order_no` (`order_no`)-- 覆盖索引（查询只访问索引，不回表）KEY `idx_user_id_amount` (`user_id`, `order_amount`)

4.4 索引禁止项

5. SQL与编程规范

5.1 查询规范

5.2 写入规范

5.3 函数与表达式

6. 主键与外键规范

6.1 主键规范

6.2 外键规范

7. 版本管理与迁移

7.1 DDL变更规范

7.2 迁移脚本规范

• • 使用版本化迁移工具（Flyway / Liquibase）
• • 每个脚本格式：V{版本号}__{描述}.sql
• • 脚本必须幂等（可重复执行）
• • 示例：V1.0.1__add_index_user_mobile.sql

7.3 数据归档与清理

• • 定期清理逻辑删除超过90天的数据
• • 归档表命名：t_order_archive_YYYYMM
• • 清理操作在业务低峰期执行，每次删除 ≤ 1000行

8. 检查清单

设计评审时逐项确认：

• • 表名、字段名符合命名规范
• • 每个表有注释，每个字段有注释
• • 存储引擎 = InnoDB，字符集 = utf8mb4
• • 包含6个必备字段（id, created_time, updated_time, version, is_deleted, create_by）
• • 金额字段使用 DECIMAL，禁止 FLOAT/DOUBLE
• • 禁止使用 ENUM
• • 设置了合理的默认值，尽可能 NOT NULL
• • 主键为 BIGINT UNSIGNED，禁止业务主键
• • 索引数量 ≤ 5，没有冗余索引
• • 外键无数据库约束，但有索引
• • 无 SELECT * 风险查询
• • 无存储过程/触发器依赖

9. 附录：常见反模式与修正

本规范自发布之日起执行，所有新建表和重大表变更必须遵守。

第7节 技术架构

本节目的：选择具体的技术组件和框架，将逻辑设计转化为可执行的技术方案。技术架构是架构设计的“实现层”，直接影响系统的性能、可维护性和演进能力。

7.1 技术选型原则

做什么：建立技术选型的决策框架，确保选型决策有据可依。

关键思考：

• • 选型的核心考量维度有哪些？（团队能力、社区活跃度、性能、可维护性、成本）
• • 新技术的引入门槛是什么？
• • 是否存在供应商锁定风险？

选型评估维度：

7.2 技术栈清单

做什么：列出系统使用的全部技术组件及其版本，形成统一的技术栈基线。

关键思考：

• • 各组件版本之间是否兼容？（Spring Boot与Spring Cloud、MySQL驱动等）
• • 是否需要锁定特定版本以避免“依赖地狱”？
• • 是否有技术组件需要定制或扩展？

示例：

7.3 核心组件设计

做什么：对关键技术组件（网关、注册中心、消息队列、缓存）进行详细设计。

关键思考：

• • 网关的路由规则、认证机制和限流策略如何设计？
• • 服务注册与发现的健康检查机制是什么？
• • 消息队列的主题划分、分区策略和消费模式如何设计？

示例：API网关设计

技术选型：Spring Cloud Gateway路由规则：- /order/** → order-service (负载均衡策略：RoundRobin)- /user/** → user-service- /product/** → product-service- /payment/** → payment-service认证机制：- 统一JWT Token校验（集成SSO）- 白名单URL免校验（/login, /register, /health）限流策略：- 全局限流：集群QPS上限10,000- 用户级限流：单用户QPS上限100- 实现方式：令牌桶算法 + Redis计数器熔断配置：- 熔断阈值：5秒内错误率>50%- 熔断时长：30秒- 半开请求数：5

7.4 通信协议规范

做什么：定义服务间通信的协议、数据格式和接口规范。

关键思考：

• • 同步通信和异步通信的使用场景分别是什么？
• • 接口版本管理策略是什么？
• • 错误码和响应格式是否统一？

示例：

同步通信：- 协议：HTTP/1.1 with TLS 1.3- 数据格式：JSON (Content-Type: application/json)- 字符编码：UTF-8异步通信：- 消息中间件：Kafka- 消息格式：JSON + 消息头（traceId, eventType, timestamp）- 分区策略：按业务主键哈希- 消费模式：至少一次 + 幂等处理统一响应格式：{  "code": 200,  "message": "success",  "data": {...},  "traceId": "a1b2c3d4e5f6"}错误码规范：- 200-299: 成功- 400-499: 客户端错误（400参数错误、401未认证、403无权限、404资源不存在）- 500-599: 服务端错误（500内部错误、503服务不可用）

7.5 开发框架与规范

做什么：建立统一的开发规范和代码约定，确保团队开发的一致性。

关键思考：

• • 分层结构如何定义？（Controller → Service → Repository → Mapper）
• • DTO、VO、BO的使用场景分别是什么？
• • 日志、异常、事务的处理规范是什么？

示例：

代码分层规范：┌─────────────────────────────────────────┐│  Controller层  - 接收请求、参数校验、响应封装 │├─────────────────────────────────────────┤│  Service层    - 业务逻辑、事务管理         │├─────────────────────────────────────────┤│  Manager层    - 通用业务逻辑复用           │├─────────────────────────────────────────┤│  Repository层 - 数据访问、缓存操作         │└─────────────────────────────────────────┘对象转换规范：- DTO：接收前端请求参数- VO：返回给前端的响应对象- BO：Service层内部业务对象- PO：持久层对象，与数据库表对应日志规范：- 日志级别：ERROR（系统错误）、WARN（业务异常）、INFO（关键操作）、DEBUG（调试）- 格式：JSON格式，包含traceId、timestamp、level、message、class- 敏感信息：手机号、身份证等需掩码处理异常处理规范：- 业务异常：抛出BusinessException，前端显示友好提示- 系统异常：统一捕获，记录ERROR日志，返回500- 异常码：6位数字，前2位模块、中间2位类型、后2位具体错误

第8节 部署架构

本节目的：设计系统的部署方案，包括物理环境、网络拓扑、容器化策略和发布流程。部署架构决定了系统的运行稳定性、扩展能力和运维效率。

8.1 部署拓扑设计

做什么：绘制系统的部署拓扑图，展示各组件在物理/虚拟环境中的分布和连接关系。

关键思考：

• • 系统部署在哪个云平台或数据中心？
• • 高可用策略是什么？（多可用区、多地域）
• • 各组件之间的网络路径和带宽是否满足要求？

示例拓扑图结构：

Internet    │    ▼┌───────────────────────────────────────────┐│              CDN (静态资源加速)              │└───────────────────────────────────────────┘    │    ▼┌───────────────────────────────────────────┐│          WAF + SLB (负载均衡器)             ││            4层/7层分发                      │└───────────────────────────────────────────┘    │    ▼┌───────────────────────────────────────────┐│         API Gateway 集群 (3节点)            ││        认证/路由/限流/熔断                   │└───────────────────────────────────────────┘    │    ▼┌───────────────────────────────────────────┐│          微服务集群 (Kubernetes)            ││  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐      ││  │订单服务│ │用户服务│ │库存服务│ │支付服务│ ... ││  └──────┘ └──────┘ └──────┘ └──────┘      │└───────────────────────────────────────────┘    │    ┌──────────────┬──────────────┐    ▼              ▼              ▼┌───────┐    ┌───────┐    ┌───────────┐│MySQL  │   │Redis  │    │  Kafka    ││主从集群│   │哨兵集群│    │ 集群      │└───────┘    └───────┘    └───────────┘

8.2 环境与资源规格

做什么：定义各环境（开发、测试、预发布、生产）的资源配置和实例数量。

关键思考：

• • 不同环境的配置差异如何管理？
• • 生产环境的资源预留是否考虑峰值和冗余？
• • 是否需要启用弹性伸缩？

示例：

生产环境资源规划：

Kubernetes集群配置：- Master节点：3台 4C8G（高可用）- Worker节点：10台 16C64G（可根据负载弹性增减）- 存储：云盘（SSD）持久化卷，容量按需配置网络规划：- VPC CIDR：10.0.0.0/16- 子网划分：  - 公网子网 10.0.1.0/24（SLB、网关）  - 应用子网 10.0.2.0/20（微服务Pod）  - 数据子网 10.0.16.0/20（数据库、缓存、MQ）

8.3 容器化与编排策略

做什么：设计Docker容器化方案和Kubernetes编排策略。

关键思考：

• • 容器的基础镜像选择是什么？（Alpine vs Ubuntu）
• • 容器的资源限制如何设置？（requests/limits）
• • 如何管理配置和环境变量？（ConfigMap、Secret）

示例：Dockerfile示例

# 多阶段构建FROM openjdk:17-jdk-slim as builderWORKDIR /appCOPY . .RUN ./gradlew buildFROM openjdk:17-jre-slimWORKDIR /appCOPY --from=builder /app/build/libs/*.jar app.jarEXPOSE8080ENTRYPOINT ["java", "-jar", "app.jar"]

K8s部署配置：

apiVersion:apps/v1kind:Deploymentmetadata:name:order-servicespec:replicas:3strategy:type:RollingUpdaterollingUpdate:maxSurge:25%maxUnavailable:0template:spec:containers:-name:order-serviceimage:order-service:latestresources:requests:memory:"512Mi"cpu:"500m"limits:memory:"2Gi"cpu:"2000m"livenessProbe:httpGet:path:/healthport:8080initialDelaySeconds:30periodSeconds:10readinessProbe:httpGet:path:/readyport:8080initialDelaySeconds:10periodSeconds:5

8.4 发布与回滚策略

做什么：定义代码和配置的发布流程、版本管理和回滚机制。

关键思考：

• • 发布策略选择？（滚动更新、蓝绿部署、金丝雀发布）
• • 如何快速回滚？
• • 配置变更如何与代码发布解耦？

示例：

发布流程：1. 开发完成 → 单元测试 → 代码审查2. 构建镜像 → 推送到镜像仓库3. 部署到测试环境 → 自动化测试4. 部署到预发布环境 → 回归测试5. 生产环境金丝雀发布：   - 阶段1：替换1个Pod，观察10分钟   - 阶段2：替换25% Pod，观察30分钟   - 阶段3：替换50% Pod，观察30分钟   - 阶段4：全量替换6. 发布完成 → 更新文档回滚机制：- 保留最近5个版本的镜像- 生产环境保留最近3次部署的配置备份- 回滚触发条件：  - 错误率上升超过20%  - TP99响应时间超过1秒  - 核心接口成功率低于99%- 回滚命令：kubectl rollout undo deployment/order-service

第9节 安全架构

本节目的：设计系统的安全防护体系，确保满足网络安全等级保护（等保2.0/3.0）等合规要求。安全架构是横切关注点，必须融入所有架构层面。

9.1 安全设计原则

做什么：建立安全设计的核心指导原则，贯穿整个架构设计过程。

关键思考：

• • 系统面临的主要安全威胁是什么？
• • 安全控制应部署在哪些层面？
• • 如何平衡安全与用户体验？

示例：

9.2 等保2.0合规映射

做什么：将等保标准的控制要求映射到系统设计中，确保满足合规要求。

关键思考：

• • 系统定级是几级？（一级最低，五级最高，通常三级系统需满足“适度安全”原则）[reference:8]
• • 哪些控制点需要重点关注？
• • 技术实现与管理制度的边界在哪里？

等保2.0技术框架：等保2.0以GB/T 22239-2019为核心标准，构建了“一个中心、三重防护”的技术框架——安全管理中心 + 安全通信网络/安全区域边界/安全计算环境防护，并通过“通用要求+扩展要求”实现云计算、物联网等新兴技术场景全覆盖[reference:9]。

示例：

9.3 网络安全架构

做什么：设计网络的隔离、防护和监控策略，确保网络层面的安全。

关键思考：

• • 网络分层和隔离策略是什么？
• • 入向流量和出向流量的安全控制有何不同？
• • 东西向流量（服务间）是否需要加密？

示例：

网络分层与隔离：Internet   │   ▼[WAF] ── 应用层防护（SQL注入、XSS、CC攻击拦截）   │   ▼[SLB] ── 4层负载均衡 + DDoS防护   │   ▼[API网关] ── 认证、鉴权、限流   │   ▼┌─────────────────────────────────────────┐│            VPC (10.0.0.0/16)            ││  ┌─────────┐    ┌─────────┐            ││  │ 公网子网 │    │ 内网子网 │            ││  │ DMZ     │───▶│ 应用子网 │            ││  │10.0.1.0 │    │10.0.2.0 │            ││  └─────────┘    └────┬────┘            ││                      │                 ││                ┌─────▼─────┐           ││                │ 数据子网  │           ││                │10.0.3.0   │           ││                │ DB/Cache  │           ││                └───────────┘           │└─────────────────────────────────────────┘安全组规则：- 公网子网：仅开放80、443端口，来源：0.0.0.0/0- 应用子网：仅接收来自公网子网的流量，端口8080-8090- 数据子网：仅接收来自应用子网的流量，端口3306(MySQL)、6379(Redis)、9092(Kafka)- 服务间：启用mTLS双向认证，禁止明文调用

9.4 身份认证与访问控制

做什么：设计用户身份验证、授权和访问控制机制。

关键思考：

• • 支持哪些认证方式？（用户名密码、短信验证码、SSO、MFA）
• • 权限模型如何设计？（RBAC、ABAC还是混合）
• • 服务间调用的认证如何实现？

示例：

认证架构：| 场景 | 方式 | 凭证 | 有效期 ||-----|------|-----|-------|| 用户登录 | OAuth2 + JWT | Access Token + Refresh Token | AT:2h / RT:7d || 服务间调用 | mTLS + 服务账号 | X.509证书 | 1年轮换 || 管理员操作 | SSO + MFA | 密码 + 动态验证码 | 强制MFA || 第三方API | API Key + 签名 | AK/SK + HMAC-SHA256 | 定期轮换 |授权模型（RBAC+）：用户 ──拥有──▶ 角色 ──关联──▶ 权限 ──操作──▶ 资源密码策略：- 长度：≥8字符- 复杂度：大写+小写+数字+特殊符号，至少3类- 存储：bcrypt（cost=10）- 尝试锁定：5次失败锁定15分钟- 修改周期：90天强制修改

9.5 数据安全

做什么：设计数据的加密、脱敏、留存和销毁策略。

关键思考：

• • 数据如何分级分类？
• • 不同级别的数据需要什么样的保护？
• • 合规要求对数据留存有何规定？

示例：

数据分类分级：| 等级 | 分类 | 示例 | 保护要求 ||-----|------|-----|---------|| L4 极高 | 核心商业机密 | 数据库密码、私钥 | HSM/KMS || L3 高 | 用户敏感信息 | 手机号、身份证、地址 | 加密存储 + 脱敏展示 || L2 中 | 业务核心数据 | 订单金额、库存 | 访问控制 + 审计日志 || L1 低 | 公开数据 | 商品名称、描述 | 基础防护 |加密策略：| 数据类型 | 传输加密 | 存储加密 | 算法 ||---------|---------|---------|------|| 用户密码 | TLS | bcrypt哈希 | bcrypt(cost=10) || 手机/身份证 | TLS | AES-256-GCM | 密钥来自KMS || 支付卡号 | TLS + 内部API | 脱敏 + Token化 | 支付令牌 |脱敏规则：- 手机号：138****1234- 身份证：110101********1234- 邮箱：a***@example.com

9.6 应用安全

做什么：设计应用层面的安全防护，包括漏洞防护、API安全和供应链安全。

关键思考：

• • OWASP Top 10中哪些漏洞是系统最需要关注的？
• • API安全如何保障？（认证、限流、防重放）
• • 开源组件依赖如何管理？

示例：

漏洞防护：| 漏洞类型 | 防护措施 | 验证方式 ||---------|---------|---------|| SQL注入 | 参数化查询 + MyBatis | SAST + DAST扫描 || XSS | 输出转义 + CSP头 | 自动化扫描 || CSRF | CSRF Token + SameSite Cookie | 代码审查 || 越权 | 资源级权限校验 + 随机ID | 代码审查 + 自动化测试 |API安全：- 请求限流：令牌桶，每用户100次/分钟- 请求签名：防重放，时间戳+Nonce+签名- 敏感接口：二次验证依赖安全：- SBOM：记录所有依赖包及版本- 漏洞扫描：每周运行dependency-check- 策略：禁止使用未审核的开源组件

9.7 安全审计与日志

做什么：设计安全审计事件的记录、存储和分析机制。

关键思考：

• • 哪些操作必须记录审计日志？
• • 审计日志保留多久？（等保三级要求≥180天）
• • 如何防止审计日志被篡改？

示例：

必须审计的事件：| 事件类型 | 记录内容 | 保留期 ||---------|---------|-------|| 登录成功/失败 | 用户、IP、时间、结果 | 180天 || 权限变更 | 操作人、变更前后角色 | 180天 || 核心数据操作 | 操作人、时间、数据ID、变更内容 | 180天 || 配置变更 | 变更人、配置项、新旧值 | 180天 |日志格式规范：{  "timestamp": "2026-04-04T10:30:00Z",  "traceId": "a1b2c3d4e5f6",  "eventType": "USER_LOGIN",  "userId": "user123",  "clientIp": "192.168.1.1",  "result": "SUCCESS",  "details": {}}

第10节 质量属性

本节目的：详细定义系统的非功能需求，包括性能、可用性、可扩展性、可维护性等，并设计相应的实现策略。质量属性是架构设计的“质量驱动因素”，直接影响系统架构风格和模式的选择[reference:10]。

10.1 质量属性分类

做什么：识别和分类系统需要满足的质量属性，区分运行期质量属性和开发期质量属性。

关键思考：

• • 运行期质量属性：性能、可用性、安全性、可扩展性、可靠性、可观测性
• • 开发期质量属性：可维护性、可测试性、可移植性、可复用性

示例：

运行期质量属性：- 性能：响应时间、吞吐量、资源利用率- 可用性：SLA目标、故障恢复时间- 安全性：认证、授权、加密、审计- 可扩展性：水平扩展能力、垂直扩展能力- 可靠性：故障容错、数据一致性- 可观测性：监控、日志、链路追踪开发期质量属性：- 可维护性：代码可读性、模块化程度- 可测试性：单元测试覆盖、集成测试可行性- 可移植性：跨环境部署能力

10.2 质量属性场景

做什么：为每个关键质量属性编写具体场景，明确评估方法。

关键思考：

• • 场景包含哪些要素？（刺激源、刺激、环境、制品、响应、响应度量）
• • 如何为场景排定优先级？
• • 场景如何指导架构决策？

质量属性场景模板：

## [质量属性名称] 场景**刺激源**：[触发事件的来源]**刺激**：[触发的事件]**环境**：[系统所处的状态]**制品**：[被影响的系统部分]**响应**：[系统应表现的行为]**响应度量**：[如何量化评估]

示例：性能场景

## 性能场景**刺激源**：用户**刺激**：发起订单创建请求**环境**：系统处于正常负载状态**制品**：订单服务**响应**：完成订单创建并返回结果**响应度量**：95%的请求在200ms内完成

示例：可用性场景

## 可用性场景**刺激源**：基础设施**刺激**：订单服务的一个实例宕机**环境**：系统运行中**制品**：订单服务集群**响应**：请求自动切换到其他健康实例**响应度量**：故障检测<10秒，恢复时间<30秒

10.3 质量属性实现策略

做什么：为每个质量属性设计具体的实现战术和模式。

关键思考：

• • 性能：缓存、异步处理、读写分离、CDN加速
• • 可用性：冗余部署、健康检查、自动恢复、降级熔断
• • 可扩展性：无状态设计、水平分片、消息解耦
• • 可维护性：分层架构、设计模式、代码规范

示例：

第11节 附录与演进计划

本节目的：提供补充信息和未来的架构演进规划。

11.1 代码目录结构

做什么：给出项目的代码组织示例，便于新成员快速上手。

示例：

src/├── main/│   ├── java/com/company/service/│   │   ├── controller/      # REST API控制器│   │   ├── service/         # 业务逻辑层│   │   ├── repository/      # 数据访问层│   │   ├── dto/             # 数据传输对象│   │   ├── entity/          # 持久化实体│   │   ├── config/          # 配置类│   │   ├── util/            # 工具类│   │   └── exception/       # 异常定义│   └── resources/│       ├── application.yml  # 主配置文件│       ├── application-dev.yml│       ├── application-prod.yml│       └── db/│           ├── migration/   # 数据库迁移脚本│           └── seed/        # 初始数据└── test/    ├── unit/                # 单元测试    └── integration/         # 集成测试

11.2 技术债与演进路线图

做什么：记录当前架构中的技术债务和未来的改进计划。

关键思考：

• • 哪些是“故意为之”的技术债？（为了快速上线而做的妥协）
• • 哪些是需要持续偿还的债务？
• • 演进路线图的时间规划是什么？

示例：

已知技术债：| 债务类型 | 描述 | 影响 | 计划偿还版本 ||---------|-----|-----|------------|| 单体数据库 | 所有服务共享一个MySQL | 扩展性受限 | V2.0 || 缺乏多活 | 单数据中心部署 | 可用性风险 | V3.0 || 监控不完善 | 缺少业务指标大盘 | 运维效率低 | V1.5 |演进路线图：- V1.0（当前）：单体数据库 + 微服务拆分完成- V1.5（3个月后）：完善可观测性 + 业务指标大盘- V2.0（6个月后）：按业务域拆分数据库 + 分库分表- V3.0（12个月后）：异地多活 + 单元化架构

11.3 架构评估清单

做什么：提供架构评审时的自检清单，确保文档完整性和设计质量。

关键思考：

• • 架构文档是否覆盖了所有必要章节？
• • 关键架构决策是否都有记录？
• • 质量属性目标是否可量化、可验证？

示例：

架构文档完整性检查：□ 文档概述与目标（1节）□ 架构背景与约束（2节）□ 核心架构决策记录（3节）——ADR至少包含3个核心决策□ 业务架构（4节）□ 应用架构（5节）□ 数据架构（6节）□ 技术架构（7节）□ 部署架构（8节）□ 安全架构（9节）□ 质量属性（10节）设计质量检查：□ 关键业务流程是否绘制了序列图？□ 数据库ER图是否完整？□ 部署拓扑图是否清晰？□ 质量属性场景是否可量化评估？□ 安全架构是否覆盖等保2.0三级要求？风险检查：□ 是否存在单点故障？□ 分布式事务是否有妥善处理方案？□ 是否考虑了流量峰值时的限流/熔断？□ 敏感数据是否已标识并加密？□ 依赖的第三方服务是否有降级方案？

第12节 架构师工具箱

12.1 文档编写工具

建议：在敏捷开发中，采用轻量级与实用主义的文档编写方式，在迭代过程中逐步完善架构文档，避免“大型预先设计”模式[reference:11]。

12.2 架构绘图工具