Architecture Spec：架构设计的机器可读化

TL;DR

本文核心观点：

架构即规格 — Architecture Spec 将架构设计从静态图改为结构化、机器可读的 YAML/JSON 规格说明，精确无二义，可用于 AI 代码生成和自动化验证

AI 理解与生成 — AI 可从 Architecture Spec 生成代码脚手架、部署配置、监控配置，并自动检测架构漂移，保持实现与规格的持续对齐

Git 版本控制 — 规格说明与代码一同进入版本控制，架构变更通过 Git 管理，代码审查即架构审查

C4 + 结构化 — C4 Model 四层模型（System Context / Container / Component / Code）结合结构化数据格式，形成完整的架构规范体系

「2024年，一位架构师画了一张完美的架构图——微服务拆分、消息队列、缓存策略，应有尽有。三个月后，新加入的工程师发现代码里的架构和图上的架构’好像不太一样’。不是图错了，而是图是’给人看的’，不是’给机器执行的’。在AI时代，架构设计需要从画图进化为可验证、可生成、可追溯的规格说明。」

Architecture Spec 工作流

传统架构文档的困境

经典架构交付物

传统软件架构设计通常产生以下交付物：

架构图：PowerPoint、Visio、draw.io 绘制的框线图
架构文档：Word 或 Confluence 中的文字说明
技术选型表：对比各种技术栈的选择理由
决策记录：ADR（Architecture Decision Records）

困境 1：图与代码的鸿沟

场景：架构师设计了一套微服务架构

问题：架构图是”期望”，代码是”现实”，两者渐行渐远。

💡 Key Insight

架构文档与实现代码之间的 drift 是不可避免的——问题的关键不是”如何阻止 drift”，而是”如何让 drift 被及时发现”。

困境 2：二义性陷阱

架构图中的框和线代表什么？

人类可以通过上下文理解，但 AI 无法确定。

💡 Key Insight

人类能通过上下文填补图的语义，但 AI 没有这种直觉——它需要精确的结构化定义。

困境 3：难以验证

问题：

人工审查成本高
容易遗漏
无法持续验证

💡 Key Insight

架构图是视觉化的，不是结构化的——没有机器可解析的格式，就无法实现自动化验证。

困境 4：变更不同步

结果：文档成为”历史的遗迹”。

困境 5：AI 无法理解

当 AI 尝试根据架构图生成代码时：

架构图是视觉化的，不是结构化的。

💡 Key Insight

可精确无二义，可自动化验证，可生成代码和文档，Git 友好版本控制——这四个特性是传统架构图永远无法实现的。

什么是 Architecture Spec

定义

Architecture Spec（架构规范）：以结构化、机器可读的形式描述软件系统的架构设计，包括系统组件、组件间关系、通信协议、数据流、约束条件，可直接用于代码生成、架构验证和自动化文档。

Architecture Spec vs 传统架构图

维度	传统架构图	Architecture Spec
格式	图片/PPT	YAML/JSON/DSL
读者	人类	人类 + AI/机器
精确性	二义性高	精确无二义
可验证	人工审查	自动化验证
可生成	不能	可生成代码/文档
版本控制	困难	Git 友好

核心组成

Architecture Spec 的核心由五个要素构成，形成一套完整的架构规范体系。组件（Components） 是系统的基本构建块，每个组件对应一个具有明确职责的代码单元，例如订单服务、支付网关或库存管理器。关系（Relationships） 描述组件之间的连接方式，包括同步调用、异步消息、事件流等通信模式。通信协议（Communication Protocols） 定义组件交互的规则——是 REST over HTTP、gRPC、消息队列还是 GraphQL，每种协议都承载着不同的语义约束。数据流（Data Flows） 追踪信息在系统中的流转路径，从用户请求入口到持久化存储的全链路。约束条件（Constraints） 则是非功能性需求：SLA 要求、安全策略、可扩展性目标、部署拓扑。这些要素共同构成一份完整的架构规格说明，结构化、机器可读，可直接驱动代码生成工具工作。

C4 Model + 结构化数据

C4 Model 简介

C4 Model 是 Simon Brown 提出的软件架构可视化方法，包含四个层次：

C4 Model 四层模型

传统 C4 的局限

C4 通常用图表表示，但图表：

是静态的图片
难以版本控制
无法自动验证
AI 难以解析

结构化 C4 Spec

将 C4 Model 的四个层次表达为结构化数据格式（例如 YAML），每个层次都有明确的职责定义和边界描述。Level 1: System Context 定义系统与外部参与者之间的关系——谁在使用系统，系统依赖哪些外部服务，边界清晰可见。Level 2: Container 描述每个应用程序或数据存储的技术选择和职责分工——是 Spring Boot 应用、Node.js 服务还是 PostgreSQL 数据库，每个容器都有明确的接口和部署方式。Level 3: Component 拆解到容器内部的功能模块——订单组件、支付组件、通知组件，每个组件有独立的类结构和依赖关系。Level 4: Code Structure 最终展开为具体的代码实现：类名、方法签名、包组织。这些层次环环相扣，从最高层的业务边界到最底层的代码细节，都可以用同一套结构化语言描述，AI 可以完整理解并据此生成代码。

API 契约即架构

API 契约的重要性

API 是微服务架构中最关键的契约：

定义了服务边界
定义了数据交换格式
定义了错误处理方式
定义了版本策略

OpenAPI 作为架构载体

OpenAPI Specification（原 Swagger）是描述 REST API 的标准格式。

API 契约的架构约束

OpenAPI 规范在定义 API 接口的同时，实际上也在声明架构约束。服务边界由每个 endpoint 的路径和 method 决定——一个 /orders 资源和一个 /payments 资源分别属于不同的服务域，这是架构拆分的最直接体现。数据交换格式通过 schema 定义，字段类型和约束规则（required、enum、pattern）决定了上下游的数据契约，任何不符合 schema 的 payload 都在架构层面被拒绝。错误处理方式通过标准 HTTP 状态码和 RFC 7807 Problem Details 格式统一了错误语义，使故障可预期、可编程处理。版本策略（path versioning vs header versioning）则决定了 API 的演化路径和向后兼容性承诺。Architecture Spec 将这些 API 层面的约束统一纳入，作为整个系统架构约束的一部分。

AI 驱动的架构生成与验证

AI 如何理解 Architecture Spec

AI 对 Architecture Spec 的解析能力来自结构化数据的无二义性。当架构以 YAML 或 JSON 格式定义时，AI 能准确理解每个组件的名称、职责、边界和依赖关系——而不像图片那样需要靠视觉猜测。

从需求生成架构建议：给定一段业务需求描述，AI 可以推断出涉及的实体、行为和交互模式，然后参照 Architecture Spec 的组件定义模式，给出组件拆分建议、职责分配和接口契约草案。这一过程本质上是”需求 → 架构”的正向生成。

从架构生成代码脚手架：这是最直接的价值释放点。Architecture Spec 提供了组件清单、接口定义和数据流描述，AI 可以据此生成各组件的代码框架——服务类、接口定义、数据传输对象（DTO）、配置类。生成的代码天然与架构对齐，因为源头就是结构化的规格说明。

架构验证：AI 可以将实现代码与 Architecture Spec 进行比对，检查组件是否按定义的方式调用了依赖、接口签名是否匹配、数据流是否按预期流转。这就是架构漂移检测的核心——当代码的实际行为偏离规格时，AI 能自动发现并告警。相比人工审查，这种验证可以持续运行，每次 commit 触发，覆盖率 100%。

架构漂移检测

架构漂移（Architecture Drift）是指代码的实际结构逐渐偏离最初设计的架构约束，而没有人意识到这个偏离正在发生。在传统模式下，这是因为架构文档是静态的、滞后的——画完图的那一刻就开始过时了。人工审查成本高、容易遗漏、无法持续，所以漂移往往在系统运行数月后才被发现，此时改造成本已经很高。

Architecture Spec 让自动化检测成为可能。每次代码提交时，系统可以运行架构验证工具，将代码的结构（类名、包结构、方法签名、调用关系）与 Architecture Spec 中的定义进行比对。这类工具的代表是 ArchUnit（Java 生态），它允许你用 Java 代码编写架构约束规则，例如”OrderService 类的 update 方法不得直接调用 DatabaseRepository”，然后在 CI 中自动执行这些规则。检测到漂移时，CI 失败并告警，架构约束得到强制执行。

这种机制的强大之处在于持续性和全覆盖——每次 commit、每个分支、每个 PR 都经过验证，而不是靠架构师人工 review 代码时偶尔发现。架构约束从”期望”变成了”可执行的事实”。

实战：微服务系统的架构规范

场景：订单管理系统