企业官网建设流程全解析

项目没黄，架构图先黄了。这句话我在不止一个团队里说过。

架构图生成这件事，听起来是文档工作里最没有争议的一项，实际上却是软件项目里最容易烂尾的资产之一。我见过太多项目组，立项时花两周憋出一张精美的软件架构图，评审会上一屋子人点头，半年后那张图就彻底和代码脱节。等代码重构了几轮，老图就成了新人眼里的“考古地图”。而文档质量差的根子，往往就藏在“图没人更新”这件事里——模块改了没人画，服务拆了没人画，外部依赖换了也没人画，最后整份技术文档的可信度跟着一起崩掉。

最近半年我一直在折腾用AI辅助画架构图的流程，踩了不少坑，最后沉淀出一套能稳定提高文档质量的方法。这篇文章不是工具评测，也不打算夸某个AI产品多聪明，而是把我真实跑过的路径、踩过的坑、总结出的规则完整梳理一遍。适合正在维护中大型系统、为过期文档头疼的开发者和技术负责人，也适合刚起步、想把架构文档习惯尽早建立起来的小团队。

1. 为什么架构图总是“活不过半年”

1.1 画图和改代码之间的成本严重不对称

人工维护一张架构图，成本高到大多数人根本懒得动。改一行代码可能只需要5分钟，但把这张代码的改动同步到架构图上，得先打开画图工具，找到对应模块，调整位置、连线、文字说明，可能还要重排一下布局。这一套下来20分钟起步，而且收益几乎看不见——图又不会因为被你更新了就自动弹出表扬窗口。

更关键的是，架构图是“设计意图”的产物，不是“代码现实”的产物。画图的人当初画的是设计时的理想状态，代码经过几轮迭代后早就偏离了那张图。可没有人会记得每次偏离具体发生在哪一天、是谁改的、改的时候怎么想的。于是大家默认不让图走在代码前面，图就永远落后于代码。

我自己的感受是：大部分团队需要的不一定是更漂亮的架构图，而是更不容易过时的架构图。把“更新架构图”从一件需要自觉的事，变成一件低成本的、顺手就能做的事，文档质量才能真正撑住。

1.2 AI辅助真正解决的是“一致性”，不是“画图能力”

AI在这里的定位不是取代架构师做设计决策，而是把“从信息到图”的转换成本压到极低。

传统流程里，架构图的信息来源分散在代码目录、部署配置、接口文档、会议纪要里。人要把这些零散信息先消化，再手动画成图。AI介入之后，信息整理和初步图形化的工作可以被自动完成，人只需要做评审和纠偏。生成一张粗糙的初稿可能只要10分钟，而过去从零开始画一张像样的图至少要半天。

这个成本结构的变化非常关键。当更新一张图的成本降到足够低，低到团队愿意为了文档一致性付一点点代价，那张图就不会轻易变成“历史遗迹”。AI辅助提升文档质量，本质上是改变了维护文档的经济模型。

1.3 文档质量差的核心不是写作水平，而是没人维护

我在梳理过很多项目的文档问题后发现，绝大多数的技术文档写得不差，差的是没人持续维护。尤其是架构图这种可视化资产，一旦过期，比没有更误导人——新人照着旧图找服务，找半天找不到，反而会质疑整个文档体系的可靠性。

引入AI辅助生成之后，文档维护的节奏可以从“季度性大扫除”变成“每次代码结构变化时顺手更新”。配合后面要讲的检查脚本，架构图和源码之间的偏差能被快速暴露。这才是真正提升文档质量的一整套打法，而不是单纯让AI生成一张好看的图。

2. 先定位：架构图给谁看、画到哪一层

2.1 用四层模型拆分信息层级

在动手让AI画图之前，得先搞清楚一件事：你要生成的架构图是给谁看的。

业内常用的方式是分层建模，从最宏观到最细节，常见的是四层：

这四层的信息密度差异很大，生成方式也完全不同。上下文层可以从需求文档和部署说明里抽；容器层主要从配置文件和模块目录里看；组件和代码层则离源码最近，直接从静态分析结果里拿最靠谱。

2.2 我的分层建议：至少画出上下文和容器两层

我自己的经验是，一个项目里最该维护的是上下文图和容器图。这两层的信息量足够支撑日常的技术讨论、新人入职、架构评审，又不会因为代码频繁变动而每天都需要改。

组件和代码层的图变化太快，如果强制要求“每次代码变动都更新组件图”，团队一定会反弹。我在实践里的做法是：组件图只在关键模块重构、新增模块时更新，代码层基本不画图，直接用静态分析工具在需要时生成临时视图。

这个取舍很重要。把维护频率和人力和图的层级匹配起来，大家才不会觉得架构图是个负担。

2.3 输入给AI的信息越像“图例”，输出越稳定

不管用哪种方式让AI辅助生成，投入的信息质量直接决定输出质量。

我前面折腾过最失败的一种方式：把一整篇需求文档丢给AI，让它直接画出系统架构图。结果出来的图大而空，没有边界、没有分组，模块名还是从需求描述里猜出来的，完全没法用。

后来我换了一种方式：先人工维护一个结构化的清单，比如模块名单、依赖关系、外部系统列表，再让AI基于这份清单去生成图表描述语言。输入的字段越接近“图例”，AI输出的稳定度越高。这份清单本质上就是架构图的“源数据”，图和源数据绑定之后，维护起来就轻松多了。

3. AI生成架构图的三种路线对比

3.1 路线一：从代码静态分析生成依赖图谱

这条路线的思路是：既然架构图反映的是代码结构，那就直接从源码里提取依赖关系，自动生成图谱。

具体做起来分几步：

• 用脚本扫描项目源码目录，按照模块路径做聚合
• 分析文件之间的import、调用、接口引用关系
• 把结果输出为图形描述代码

这个流程里，AI的角色更多是辅助分析和聚合。比如扫描出一堆扁平的文件依赖关系之后，AI可以根据包名前缀、业务语义，把文件聚类成业务模块，省去人工梳理的时间。

下面是一个简单示意，展示从源码目录扫描模块依赖的基本思路。严格的生产级实现应该用各语言的AST解析库，而不是正则，但核心流程是通的：

# 简单示例：统计仓库内各模块的 import 关系 # 生产环境建议使用各语言的 AST 解析器，而不是正则 import os import re from collections import defaultdict module_imports = defaultdict(set) pattern = re.compile(r'^import\s+([\w.]+)', re.MULTILINE) for root, dirs, files in os.walk("src"): for f in files: if f.endswith(".java"): path = os.path.join(root, f) with open(path, "r", encoding="utf-8") as fp: for m in pattern.findall(fp.read()): module_imports[root].add(m) # 后续可以交给 AI 做模块聚合和分组，再输出图表描述语言

这条路线最大的优点是客观——依赖信息来自真实代码，不会出现AI瞎编模块的情况。缺点也很明显：只有代码层面的依赖，没有业务语义。代码里A模块调了B模块的接口，但为什么调、这条链路在业务上算什么，AI并不知道。

所以我把这条路线的定位放在“自动检查图是否过期”上，而不是作为主要的绘图方式。

3.2 路线二：用对话让大模型直接输出图表描述代码

这是最直观的路线：把模块清单、调用关系、部署结构写成文字，交给大模型，让它直接输出图表描述代码。

比如你可以这么对AI说：

你是一名架构师。请根据以下模块清单和调用关系，生成图表描述代码。要求：按业务领域分组；只展示服务间调用，不展开内部实现；用箭头标注调用方向；输出后附带三条设计说明。

这种方式的优势是门槛低、速度快，不依赖代码库的完整性。适合在项目早期、代码还没成型时用来画目标架构图，也适合做临时草图。

但它的坑也很明显：AI在上下文较长或模块较多时，会漏掉某些调用关系，甚至“幻觉”出不存在的模块。我试过让AI画一个20个服务的系统，它把其中两个服务之间的调用关系直接丢了，而且补了一个压根不存在的消息队列组件。所以用这种方式生成的图，必须经过人工校准。

我的经验是：不要让AI一次性画“全量图”，而是分业务域逐个画。配合一个严格的输入模板，让AI只能基于给定清单输出，不要自由发挥到清单之外。

3.3 路线三：用结构化DSL写框架，让AI补全内容

这条路线是目前我最推荐的。核心思路是：先维护一份结构化的架构描述文件，里面有系统边界、人员、服务、依赖关系的定义，然后通过工具把这份描述渲染成图。AI在这里的角色是“描述文件生成器”和“自然语言翻译器”。

结构化描述的方式有很多种，比如使用某种文本化架构描述语言、使用标记语言配合自定义保存格式都行。关键点是：这份描述文件是纯文本，可以被纳入版本管理，每次变更都能diff。

下面是一份简化的架构描述示意，展示“系统、用户、数据库以及它们的关系”是怎么文本化定义的。实际项目里这份文件会保存在代码仓库中，成为架构文档的主数据源：

workspace { model { user = person "用户" web = softwareSystem "前端应用" api = softwareSystem "API服务" db = softwareSystem "数据库" msg = softwareSystem "消息队列" user -> web "访问" web -> api "调用" api -> db "读写" api -> msg "发送消息" } views { systemContext user, web, api, db, msg { include "*" autolayout lr } } }

这份描述文件本身就是“文档”，画图只是它的一个投影。AI能做什么呢？我在实际使用中的组合是：

• 用AI把零散的需求描述、接口文档，翻译成结构化的描述文件
• 用AI在已有描述文件基础上，补全遗漏的外部依赖
• 用AI把描述文件转成文档里的图形代码，保持文档展示层同步

3.4 三种路线怎么组合最顺手

三种路线各有适用场景，我的组合方式是：

顺着这个组合打下来，架构图从“一次性画图”变成了“持续维护的文档资产”。到了这一步，才算真正意义上用AI提高了文档质量。

4. 实操：四步把架构图做成“活文档”

4.1 第一步：先定义边界，拒绝“全系统大图”

很多人画架构图的第一反应是把所有东西都摆上去，结果图里40个节点、60条连线，谁看了都懵。AI辅助也一样，你让它画全系统，它就给你画一坨。

我的做法是：先定义边界。把系统内的项目列成一个清单，把系统外依赖列成另一个清单，两边的边界必须清晰。系统内项目用模块名作为标识，系统外依赖用“外部系统-用途”的方式命名。

举个例子，一个订单系统的边界定义可能长这样：

• 系统内：网关、用户服务、订单服务、库存服务、支付服务
• 系统外：短信平台、外部物流查询、支付渠道

边界清单定义好之后，再交给AI。明确告诉它“只能使用清单里的人名和系统名，不新增任何对象”，这一步能有效防止AI在图上画出不该出现的东西。

4.2 第二步：让AI批量产出初稿，再人工校准

有了边界清单和模块依赖关系，接下来就进入AI辅助生成的核心环节。我在实践中会准备一份“绘图提示词模板”，每次只替换项目名和模块清单，保持输出格式稳定。提示词模板可以这样：

1. 设定角色：你是一个资深的软件架构师，负责根据模块清单绘制系统架构图。
2. 给出输入：提供系统内模块清单、系统外依赖清单、关键链路说明。
3. 指定输出格式：按领域分组，节点名称使用中文，连线上标注交互动词，输出图形描述代码。
4. 附加约束：禁止新增清单之外的任何模块；禁止展开模块内部实现；如果发现依赖关系不明确，用注释标注疑问点。

AI输出初稿之后，不要直接合并进文档，先做人工校准。我一般会把初稿打印出来，对着最新的代码结构、部署配置和接口列表逐项核对。重点核对三件事：模块是否缺漏、依赖方向是否正确、外部系统是否完整。

校准完成后，让AI根据反馈重新修改。通常这个“草稿-评审-修改”的循环两三轮就能稳定下来。

4.3 第三步：把图源文件嵌进代码仓库和文档

架构图不能只存在于画图工具的工程文件里，必须作为文本保存在仓库中。当前主流的做法是，在Markdown文档里直接嵌入图表描述代码，让文档站点渲染成图，这样图的变更能被版本管理记录，代码评审的时候也能看到图的变化。

嵌入方式可以参考下面这种组织方式。注意给图表代码加注释标记，说明这是自动生成和维护的，避免有人手动画改了一版就失去同步：

## 服务关系 <!-- generated by ai-arch-doc: do not edit manually --> ```text flowchart LR A[前端] --> B[网关] B --> C[订单服务] B --> D[用户服务] C --> E[(订单数据库)] D --> F[(用户数据库)]

提示：这段图表代码由AI辅助生成。修改前请先更新架构描述文件，再重新生成，不要直接编辑这里。

这一步的意义在于：架构图不再是一张孤立图片，而是和文档、代码放在一起的活文件。别人在看代码时能顺带看到架构，架构师在改架构时也能借助代码仓库的diff追踪到文档变动。 ### 4.4 第四步：用检查脚本让图和代码持续同步 就算把图放进了代码仓库，还是有团队会忘记更新。所以第四步很关键，也是我认为整个流程里最有价值的一步：用脚本检查“图里描述的模块”和“源码里实际存在的模块”是否一致。 具体做法是写一个检查脚本，读取架构描述文件或图表描述代码里的模块名，再去源码目录扫描比对，如果发现差集要么是新增模块没画进图里，要么是已删除模块还在图上挂着，就报错提醒。 下面是我在项目里经常放的检查逻辑示意： ```python # 简易同步检查示意 # 从架构描述中提取模块名，与源码目录对比差异 # 完整实现应支持更多语言和打包结构 import os import sys arch_modules = set(parse_arch_file("docs/architecture.md")) code_modules = set(scan_source_dirs("src")) missing = code_modules - arch_modules stale = arch_modules - code_modules if missing: print("[FAIL] 新增模块未出现在架构图中:", missing) sys.exit(1) if stale: print("[WARN] 架构图中存在已删除模块:", stale) sys.exit(2)

别小看这个脚本，它把“更新架构图”从主观自觉变成了客观的CI检查项。图过期了，构建就报警。在这种约束下，团队里的成员才会真正把架构图当作一等公民对待。

5. 常见问题排查与避坑备忘

5.1 图太乱，AI不知道按什么分组

AI生成的图最常见的问题就是节点堆在一起，没有层次。原因往往是提示词里没有指定分组规则，或者输入的清单本身就是扁平的。

解决方法是：在输入里就带分组字段，比如每个模块标注所属业务域，然后提示词里明确说明“按业务域用分区块分组”。有了显式的分组标签，AI就不会靠猜去组织结构了。

我调试过一次很明显的案例：同样一份模块清单，不标注业务域时输出是一锅粥；标注业务域之后，AI自动分成了用户域、订单域、支付域三块，图的可读性立刻不一样。分组信息一定要喂给AI，别指望它替你发现。

5.2 图太大，超出可阅读范围

依赖关系自动生成的图很容易膨胀。一张组件图动辄两三百个节点，渲染的时候浏览器都卡。这在工具层面是性能问题，在沟通层面就是阅读灾难。

我的处理原则是“一层一图”：容器层只画服务、数据库、消息队列，组件层只画某个服务内部的模块，绝不混层。如果单张图还是太大，就按业务链路切成子图。比如订单服务、支付服务、库存服务画一张链路图，用户服务单画一张。

另外，还可以按“变更范围”来做裁剪，只看近30天有改动的模块之间的联系。这样图始终服务于当下的讨论，而不是试图描绘宇宙。

5.3 代码依赖不等于业务调用关系

从源码静态分析得到的依赖图有很强的误导性：代码里A模块import了B模块，但业务上并不一定真的是A调用B。比如两个模块都依赖同一个公共库，接口里耦合了但运行时没有直接调用。

AI在处理这种信息时，如果把“import关系”直接翻译成“调用关系”，生成的图在业务视角下就是错的。我在实践中会筛选静态分析结果：只看跨服务或跨库的调用，忽略同包内部的import；只保留带有接口、HTTP、消息等特征的关系，过滤工具类的纯代码依赖。

更稳妥的做法是结合运行链路追踪的数据来校准。在开放平台、网关等场景里，通过观察实际流量能更准确地画出一条条调用链路，比静态扫描可靠得多。

5.4 问题排查速查表

这个速查表是从我实际踩坑经历里提炼出来的，以后遇到同类问题可以直接对表排查。

6. 实践心得与后续扩展

6.1 为图加上更新日期与负责人

一个很小的但很有效的习惯：在架构图文件里加一行更新时间和负责人信息。

我测试过在生成代码里自动带上如下信息：

<!-- 最近更新: 2026-02-28 | 负责人: 架构组 -->

加上这行之后，明显的变化是：代码评审时，如果看到架构图的更新时间已经很久远，评审人就会停下来问“这图是不是过期了”。责任明确以后，图的更新率会有显著提升。原因很简单，人一旦知道自己会被点名，就会愿意花那几分钟。

6.2 AI输出永远是草稿，不是成品

这是我最想强调的一条经验。AI辅助生成架构图，哪怕初稿再漂亮，也绝对不能跳过人工评审。AI最大的问题是太“自信”，它生成一张逻辑完整但完全错误的图时，图看起来毫无违和感。

所以我的固定流程是：AI生成初稿后，一定打印出来，对着最新的代码结构、部署配置和接口文档逐项核对。很多时候这个过程要重复两三轮。表面上看比直接画图多了一步，实际总时长反而是以前的四分之一到五分之一，而且准确率更高。

一定要在团队里建立这个共识：AI负责初稿和整理，人负责判断和定稿。否则AI生成错误图，被文档误导的人会更多。

6.3 这块内容还能继续扩展的方向

这套方法的下一步扩展空间，我认为有两个方向很值得尝试。

一个方向是做“能力地图”：在架构图渲染时让每个模块节点能链接到对应的源码目录或接口文档，让架构图从静态图片升级成导航入口。新成员入职时，从图上点一下就进到具体代码，学习成本会低很多。

另一个方向是让检查脚本更智能。比如解析消息队列、数据库表级别的依赖，甚至结合运行监控数据自动更新真实调用频率，标注出“图上画了但实际没人调”的死链路。到这一步，架构图就不只是文档了，它还是架构治理的基础设施。

这两个方向我在最近的项目里已经在陆续尝试，后面有成熟的经验再单独写一篇细聊。

最后分享一个小技巧：无论用哪种方式辅助生成架构图，都坚持一个原则——架构图必须能从项目里的某个源文件重新生成，或者至少能通过脚本校验源码与图之间的差异。只要守住这条底线，架构图就不会彻底死掉。技巧本身不复杂，但能解决的是技术和组织中关于文档遗忘的通病。