我们刚刚发布了将架构文档变为代码库一等公民的功能。认识 archyl.yaml — 一个声明式 DSL，描述你完整的 C4 模型，存储在 Git 中，经过代码审查，通过 CI/CD 自动同步。

Architecture as Code：在 YAML 文件中定义你的完整 C4 模型

架构图有一个保质期问题。你在设计会议后画好它们，一周内看起来很棒，然后代码在演进而图表在腐烂。六个月后，新员工盯着一张 Container 图，上面显示着在 Q2 就已合并的三个服务，却没有提到 Q3 新建的两个。

从 Archyl 的第一天起，我们就一直在解决这个问题。AI 发现功能帮助保持信息更新。可视化编辑器让更新变得轻松。但有一类团队——那些将基础设施即代码、策略即代码、一切即代码的团队——想要更根本的东西。

他们想让架构存在于 Git 中，紧挨着它所描述的代码。今天，我们正式发布了这个功能。

什么是 `archyl.yaml`？

这是一个声明式描述完整架构的单一 YAML 文件。将它放在仓库根目录，它就成为 Archyl 中 C4 模型的唯一真实来源。

最小化的文件看起来是这样的：

version: "1.0"

project:
  name: "My Platform"
  description: "Microservices architecture"

systems:
  - name: Platform
    type: software_system
    containers:
      - name: API Gateway
        type: api
        technologies: [Go, gRPC]
      - name: User Database
        type: database
        technologies: [PostgreSQL]

relationships:
  - from: API Gateway
    to: User Database
    label: "Reads user data"
    type: reads_from

就是这样。Archyl 读取这个文件，构建完整的 C4 模型，渲染图表，并保持一切同步。无需点击界面，无需手动同步，不会再出现"忘了更新图表"的情况。

一切都在一个文件中

DSL 不是简化的子集——它覆盖了 Archyl 能建模的全部范围：

C4 全部四个层级。 系统包含容器，容器包含组件，组件包含代码元素。YAML 的嵌套直接反映层次结构。

点号标记的关系。 使用可读的引用连接任意两个元素，如 Payment Service.API Gateway → Payment Service.Database。没有 UUID，没有晦涩的标识符。支持 grep，支持 diff，人类可读。

技术栈、环境和发布版本。 定义技术目录，声明部署环境（预发布、生产），跟踪发布——全部在同一个文件中。

ADR 和文档。 内联你的架构决策记录，或指向仓库中的文件夹。项目文档同理。

API 契约和事件通道。 声明你的 OpenAPI 规范、gRPC 定义、Kafka 主题，并将它们链接到暴露或消费它们的组件。

可视化叠加层。 使用命名的叠加层对图表中的元素进行分组，控制颜色和层级。

Monorepo 支持。 使用 include 将架构拆分到多个文件中——每个服务、团队或限界上下文一个——Archyl 自动合并。

为什么选择 YAML？

我们考虑过构建自定义 DSL 语法（像 Structurizr 的 DSL 或 Terraform 的 HCL）。出于实用原因选择了 YAML：

零学习成本。 每个开发者都已经了解 YAML。无需学习新语法，无需安装解析器，无需编辑器插件。
免费的 IDE 支持。 我们在 /api/v1/dsl/schema 发布了 JSON Schema。将你的 IDE 指向它，无需 Archyl 特定工具即可获得自动补全、验证和内联文档。
diff 友好。 YAML diff 在 Pull Request 中干净且可读。审查者立即可以看到"啊，他们在 Payment Service 中添加了一个新容器并连接到了 Redis"。
工具生态系统。 Linter、格式化工具、模板引擎（Helm、Kustomize），全都原生支持 YAML。

Git 原生工作流

这才是真正的力量所在。因为 archyl.yaml 存在于你的仓库中，架构变更遵循与代码变更相同的工作流：

Branch。 创建功能分支，编辑 YAML。
Review。 打开 Pull Request。你的团队同时审查架构变更和代码变更。
Merge。 审批通过后，合并到 main。
Sync。 Archyl 检测到变更并自动更新图表。

不再有"图表说的是 X 但代码做的是 Y"。不再有绕过审查的架构变更。不再有没人知道已更新的文档。

CI/CD 集成

我们构建了与 CI/CD 管道的一流集成。对于 GitHub，我们提供官方 GitHub Action，处理一切——读取文件、调用 API、报告变更内容。

GitHub Actions（官方 Action）：

name: Sync Architecture
on:
  push:
    branches: [main]
    paths: ['archyl.yaml']
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: archyl-com/actions/sync@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          project-id: 'your-project-uuid'

就这样。三行配置，每次推送时架构保持同步。Action 支持自定义文件路径（用于 monorepo）、自托管 Archyl 实例，并公开 summary、systems-created 和 relationships-created 等输出供后续步骤使用。

GitLab CI：

sync-architecture:
  stage: deploy
  script:
    - |
      curl -X POST \
        https://api.archyl.com/api/v1/projects/$ARCHYL_PROJECT_ID/dsl/ingest \
        -H "X-API-Key: $ARCHYL_API_KEY" \
        -H "Content-Type: application/json" \
        -d "{\"content\": \"$(cat archyl.yaml | jq -Rs .)\"}"
  only:
    changes:
      - archyl.yaml

/ingest 端点接受 API 密钥认证，因此 CI 中不需要 OAuth 流程。它导入完整模型，创建或更新每个元素，并返回详细的变更摘要。

你也可以直接从 Archyl 界面同步。如果你的项目有连接的 Git 仓库，在 Architecture as Code 设置中点击"立即同步"，Archyl 就会直接从你的仓库获取文件。

双向：导出和导入

工作流不是单向的。已经在 Archyl 的可视化编辑器中建模了项目？导出它：

Export 从当前模型生成完整的 archyl.yaml。每个系统、容器、组件、关系、叠加层、ADR、API 契约、事件通道、发布版本——全部序列化为干净的 YAML。
Import 解析 archyl.yaml 并创建或更新项目中的所有元素。它是幂等的：导入同一文件两次不会创建重复项。元素按名称匹配并进行 upsert。
Import as Project 从 YAML 文件创建全新项目。放置一个 archyl.yaml，一键获得完整填充的项目。

这意味着你可以从界面开始，导出为 YAML，提交到 Git，切换到代码优先工作流——或者反过来。两种方式都没有锁定。

智能引用解析

DSL 最棘手的部分之一是解析关系、叠加层、事件和 API 契约中的元素引用。我们构建了一个自然处理这些的解析器：

短名称在无歧义时有效：API Gateway 在只有一个元素拥有该名称时直接解析。
点号标记消除歧义：Payment Service.API Gateway vs Analytics.API Gateway。
任意深度都支持：System.Container.Component.CodeElement 用于深层嵌套的引用。

解析器在每个可能的路径深度索引每个元素，因此你总是使用最短的无歧义引用。导出使用相同的逻辑反向运行——生成最可读的引用。

无副作用的验证

不确定你的 YAML 是否有效？/validate 端点（以及导入模态框中的"验证"按钮）在不接触数据库的情况下解析和检查你的文件：

Schema 版本检查
必填字段验证
重复名称检测
类型枚举验证（容器类型、关系类型等）
交叉引用解析

错误返回精确路径（systems[2].containers[1].name）和清晰消息。将其集成到 pre-commit 钩子或 CI 检查中，在到达 main 之前捕获问题。

实战模式

Monorepo

# Root archyl.yaml
version: "1.0"
project:
  name: "Our Platform"
include:
  - services/payments/archyl.yaml
  - services/users/archyl.yaml
  - services/notifications/archyl.yaml

每个服务维护自己的 archyl.yaml，定义其容器和组件。根文件合并它们，跨服务关系在根级别定义。技术和环境自动去重。

引导器

开始一个新项目？在写代码之前创建 archyl.yaml。定义你计划构建的系统和容器。使用 Archyl 的"Import as Project"即时生成架构。随着你的开发，YAML 与代码一起演进。

审计追踪

因为 YAML 在 Git 中，你免费获得完整历史。git log archyl.yaml 显示每一次架构变更、谁做的、什么时候、以及讨论它的 PR。试试用图表工具做到这一点。

文档生成器

将你的架构导出为 YAML，然后通过任何模板引擎生成 Markdown 文档、Confluence 页面或内部 Wiki。结构化格式使自动化变得简单。

下一步

这是 DSL 格式的 1.0 版本。我们正在开发的下一步：

漂移检测。 将仓库中的 YAML 与实时模型进行比较并高亮差异——在界面中添加但文件中没有的元素，或反之。

PR 预览评论。 当 PR 修改 archyl.yaml 时，机器人会评论架构中发生了什么变化的可视化 diff。

Schema 演进。 随着我们向 Archyl 添加新功能，DSL 将不断增长。我们将保持向后兼容性并提供迁移工具。

立即体验

Architecture as Code 今天在所有 Archyl 计划中可用。如果你已有项目：

前往项目中的 Architecture as Code 页面
点击 Export 生成你的 archyl.yaml
提交到你的仓库
将官方 GitHub Action添加到你的工作流中即可

如果从零开始，创建一个 archyl.yaml，使用 Import as Project，你将在几秒钟内获得完整渲染的 C4 架构。

你的架构值得与代码同样的严谨。对它进行版本控制、审查、自动化。

初识 C4？从我们的 C4 模型入门开始。想让 AI 生成初始架构？参见 AI 驱动的架构发现。已经在使用 AI 助手？通过我们的 MCP 服务器连接它们。

Architecture as Code：在 YAML 文件中定义你的完整 C4 模型 - Archyl Blog