通用软件架构设计路线

适用于 SaaS、平台产品、AI Agent 和企业系统：从为什么做、系统是什么、怎么实现，到如何运行、演进和验证。

定位: 这是一张架构设计方法页，不是新的物理目录。它把业务领域、工程实现、数据系统、集成、安全、平台运行和治理页面串成一条从零设计系统的路线。

一句话: 架构设计不是先画技术组件图，而是先确认目标和约束，再定义边界、模型、数据、协作、可靠性、运行和演进验证。

一、20 步压缩成 8 个评审模块

8 个模块	包含的 20 步	评审时最该问
1. 业务目标与约束	业务目标与成功指标；需求分层与约束分析。	为什么要做？成功怎么衡量？哪些约束会改变架构选择？
2. 系统边界与核心对象	系统上下文与边界；核心对象与业务边界梳理。	系统负责什么、不负责什么？核心对象、责任边界和数据归属是否清楚？
3. 模块与服务设计	模块划分与职责设计。	先模块化还是服务化？职责、依赖和团队承接能力是否对齐？
4. 数据与状态架构	数据架构设计；状态模型与生命周期。	数据谁拥有？状态谁推进？历史、口径和生命周期如何解释？
5. 接口与集成架构	接口设计；事件驱动与消息流；外部系统集成。	系统之间通过什么协作？同步、异步、第三方失败如何处理？
6. 安全、可靠性与一致性	身份、权限与安全模型；一致性与事务策略；故障处理与恢复机制。	谁能访问什么？哪些必须强一致？失败后怎样恢复业务状态？
7. 运维、可观测与发布	可观测性体系；运维与部署架构；成本与容量规划；发布策略。	系统能否被看见、发布、扩容、控成本和稳定运行？
8. 演进治理与场景验证	数据迁移策略；架构治理机制；端到端场景推演。	未来怎样迁移、复查和偿债？真实业务链路是否闭环？

二、完整 8 层 20 步

第一层：为什么做（Business Architecture）

步骤	回答什么	产出什么	对应图谱
1. 业务目标与成功指标	为什么建设这个系统？解决什么问题？成功如何衡量？	业务目标、KPI、核心用户、核心场景。	业务领域入口、架构决策
2. 需求分层与约束分析	功能需求、非功能需求和外部约束分别是什么？	功能清单、质量属性、预算、团队、上线时间、合规约束。	架构决策、测试与质量工程

第二层：系统是什么（System Architecture）

步骤	回答什么	产出什么	对应图谱
3. 系统上下文与边界	系统负责什么？不负责什么？外部用户、支付、AI 模型、第三方系统如何连接？	Context Diagram、系统边界、外部依赖和责任边界。	后端工程、服务目录与系统地图
4. 核心对象与业务边界梳理	核心对象、对象关系、业务规则和数据归属是什么？是否需要 DDD 术语由复杂度决定。	核心对象清单、对象关系、责任边界、业务边界和数据归属。	业务数据库设计、领域驱动设计

第三层：系统怎么实现（Solution Architecture）

步骤	回答什么	产出什么	对应图谱
5. 模块划分与职责设计	模块化单体还是微服务？Gateway、User、Agent、Workflow、Knowledge、Storage、Audit 如何分工？	模块图、服务图、依赖关系、发布边界。	如何设计系统、从单体到微服务
6. 数据架构设计	数据放哪里？谁拥有数据？PostgreSQL、Redis、S3、VectorDB 怎么分工？	数据存储选型、数据主权、同步方式、访问边界。	数据系统与数据库、核心数据谁说了算
7. 状态模型与生命周期	Task、Order、Agent Run、Draft 等对象如何从创建到完成、归档或失败？	状态机、生命周期、终态、中间态、异常态和修复路径。	业务状态机、数据库演进

第四层：系统如何协作（Integration Architecture）

步骤	回答什么	产出什么	对应图谱
8. 接口设计	外部接口和内部接口用 REST、GraphQL、gRPC 还是其他方式？	API 风格、请求响应模型、错误码、幂等键、版本策略。	API 与系统集成、数据契约
9. 事件驱动与消息流	UserCreated、TaskStarted、ToolExecuted 等事件如何流动？Kafka、RabbitMQ、NATS 是否必要？	事件清单、消息流向、消费者、重试、死信和回放策略。	消息队列与事件驱动、设计事件驱动系统
10. 外部系统集成	支付、身份、邮件、短信、LLM Provider、第三方 API 如何接入？	超时、限流、降级、签名、回调、对账和责任边界。	API 与系统集成、银行直连案例

第五层：系统如何稳定运行（Reliability Architecture）

步骤	回答什么	产出什么	对应图谱
11. 身份、权限与安全模型	OIDC、OAuth2、JWT、RBAC、ABAC、租户隔离如何设计？	认证模型、授权模型、租户边界、审计策略。	认证与 IAM、网络安全
12. 一致性与事务策略	哪些场景强一致，哪些最终一致？Saga、Outbox、Event Sourcing 是否需要？	事务边界、一致性策略、Outbox、补偿和对账规则。	失败处理与业务一致性、业务事务与幂等
13. 故障处理与恢复机制	Retry、Timeout、Circuit Breaker、Compensation、DLQ 如何组合？	失败分类、重试策略、降级策略、死信处理、人工接管。	失败处理与业务一致性、可靠性治理

第六层：系统如何被管理（Operational Architecture）

步骤	回答什么	产出什么	对应图谱
14. 可观测性体系	Logs、Metrics、Traces 如何覆盖用户请求、Agent、LLM、Tool 和外部系统？	日志规范、指标口径、Trace 链路、告警和排障入口。	可观测性与 SRE
15. 运维与部署架构	Docker、Kubernetes、CI/CD、开发/测试/预发/生产环境如何组织？	环境拓扑、部署流水线、发布门禁、回滚策略。	云原生、发布工程
16. 成本与容量规划	QPS、并发、存储、Token、GPU、第三方 API 成本如何估算？	容量模型、成本模型、扩容计划、限额和预算告警。	容量治理、FinOps 与成本工程

第七层：系统如何持续演进（Evolution Architecture）

步骤	回答什么	产出什么	对应图谱
17. 发布策略	蓝绿发布、金丝雀发布、Feature Flag 怎样支撑低风险上线？	发布策略、灰度规则、开关生命周期、回滚标准。	发布工程
18. 数据迁移策略	Schema Migration、Backfill、双写、在线迁移如何避免升级事故？	迁移计划、回填策略、双轨对账、退场清单。	迁移工程、数据库迁移与在线演进
19. 架构治理机制	ADR、代码规范、API 规范、架构评审如何确保长期可维护？	ADR、治理规则、例外管理、复查节奏、架构债清单。	架构决策、架构偿债

第八层：验证架构是否成立（Architecture Validation）

步骤	回答什么	产出什么	对应图谱
20. 端到端场景推演	真实用户请求如何穿过 Gateway、Agent、Workflow、LLM、Tool、Result 和 Response？	数据流、控制流、权限流、异常流和验收证据。	端到端业务系统案例、报销业务案例

三、架构文档最小目录

如果只写一份架构设计文档，建议用这 8 章

1. 业务目标与约束；2. 系统边界与核心对象；3. 模块与服务设计；4. 数据与状态架构；5. 接口与集成架构；6. 安全、可靠性与一致性；7. 运维、可观测与发布；8. 演进治理与场景验证。

四、常见误区

误区	为什么危险	修正方式
一上来画组件图	组件图不能解释为什么这么做，也不能证明是否满足目标和约束。	先写业务目标、成功指标、核心场景和非功能约束。
把架构设计等同于拆微服务	微服务只是实现形态之一，过早拆分会放大协作、数据和运维成本。	先模块化，再判断是否需要服务化。
只设计成功路径	真实系统最容易坏在超时、重复、回调丢失、部分成功和人工修复。	把异常流、补偿、对账、回放和人工接管纳入架构评审。
不讨论成本和容量	SaaS、AI Agent 和平台产品的成本曲线会直接决定可持续性。	提前估算 QPS、存储、Token、GPU、第三方 API 和运维成本。
没有端到端推演	单点设计都合理，但数据流、权限流和异常流可能无法闭环。	用真实业务场景跑一遍主链路和失败链路。

五、回到现有图谱

技术入口

回到软件工程与系统入口，按四大方向和 8 步架构路线继续阅读。

架构决策与评审

把目标、约束、质量属性、备选方案、风险和复查点沉淀成 ADR。

API 与系统集成

边界确定后，继续设计接口、事件、回调、版本和第三方集成治理。

失败处理与业务一致性

跨系统出错后，设计发现差异、补正状态、可控回放和审计证据。

总结: 一套通用软件架构设计路线，应该从业务目标和约束开始，以系统边界、核心对象、数据状态、接口集成、安全可靠、运维成本、发布迁移和端到端验证收束。技术选型只是其中一段，不是起点。