架构文档方法的比较与小型系统试用
比较 C4、arc42、ADR、4+1 与多视图审读的适用边界，保留静态文档站案头和技术试用的条件、输入、结果与未验证范围。
核查于
研究问题与结论范围
本文回答：C4、arc42、ADR 和多视图方法分别解决哪些架构表达问题，怎样按系统规模与读者任务组合；文内图源与共享模型怎样选择；一个静态文档站的案头和技术试用能够支持到哪一步。
研究支持的选择是：用 C4 检查软件职责及抽象层级，用 arc42 检查关注点遗漏，用 ADR 保存重要取舍，以运行场景和映射核对多视图联系。工具随关系复用与维护需要选择。这是基于方法资料和小型案例的条件化综合判断，真实读者理解、复杂系统充分性和长期维护成本仍需对应证据。
本研究的资料核查与试用完成于 2026-10-04。2026-10-05 整理时将成熟方法讲解与五幅案例图迁入专题架构文档：连接系统职责、运行场景与实现，本页保留比较、取舍、实验和局限。下文明确标注历史执行；此次整理没有重新运行原有单元测试、fixture 构建或外部交付验证。前台核查日期继续表示该研究基线。
方法与来源怎样选择
原研究从视图选择、对象与关系、实现证据、变更维护和充分性五组问题出发，读取 C4 官方定义，arc42 模板与 FAQ，ADR 原作者文章，并补充 4+1 原作者论文和 SEI 多视图资料。W3C 用于核查复杂图的文字替代，图工具官方资料用于辨认模型、构建、解析和渲染各自的能力。
2026-10-04 同时读取了当时仓库的 AGENTS、research skill、内容生产和格式约定，以及尚无生效规范的写作入口。它们用于确定成果位置、主 Agent 责任、草稿与授权边界；这个状态属于历史上下文。当前正式要求由 apps/site/docs/standards/ 维护，本页不继续维护一套候选执行条款。
2026-10-05 整理时重新打开了实际使用的 C4、arc42、ADR、4+1、SEI 审读、工具和 W3C 资料，并读取静态导出、source、搜索、导出检查与部署工作流入口。SEI 2005 年报告的旧 PDF 入口本次返回错误；关于该报告的使用保留为 2026-10-04 已取得资料的历史依据，不表示本次重新取得了原文。
本研究没有执行系统综述、工具性能试验、目标读者实验或长期维护评测。方法维护者的指南适合确认定义与规定，实践建议和经验报告能够提供采用线索。它们不能单独证明中文目标读者的学习效果，也不能确定一个新项目的成本收益。
已有方案的取用与调整
| 材料 | 能支持的选择 | 保留的限制与取舍 |
|---|---|---|
| 内容生产规范基础调研 | 问题、证据、连续解释、独立完整及分项质量判断 | 本研究补充系统对象、边界、视图对应和语义变化；不另造同义研究或质量流程 |
| 2026-10-03 架构候选方案 | 区分软件结构与部署，保留可编辑源，连接图文、实现和检查 | LikeC4 优先、完整模型、首批固定视图及独立 evidence 目录只是候选，案例没有证明其必要性 |
| 2026-10-04 项目讲解候选方案 | 从已有基础进入机制，解释条件与过程，保持名称对应 | 用在需要讲解陌生机制的范围；固定章节顺序、每章完整推导和练习不作为本研究采用条件 |
两份方案对业务链路、开发交付的阅读顺序不同。这与读者任务相符：故障接手可能从部署与诊断开始，功能开发可能从场景与实现开始。研究据此保留共同入口和任务入口，未选择统一阅读顺序。原归档只读，作为历史方案来源，不调整其内容。1
成熟方法解决什么问题
方法比较
| 方法 | 资料确认的主要能力 | 合适的研究对象 | 本次采用与不足 |
|---|---|---|---|
| C4 | 系统、容器、组件和代码的静态抽象，动态及部署补充图 | 软件责任、运行边界、外部联系与从整体进入局部 | 使用抽象及关系语义；层级按价值选择。发布操作、重要理由及实际证据仍需别的说明 |
| arc42 | 目标、约束、上下文、方案、结构、运行、部署、横切概念、决策、质量和风险等关注点 | 文档是否遗漏重要条件、场景和原因 | 用作覆盖检查，按本次任务组织阅读。没有填满模板或全部栏目要求 |
| ADR | 一次架构重要决定的上下文、选择、状态和后果 | 未来维护者需要判断为何如此，以及条件改变后是否重估 | 对重要取舍按需保存；接受状态不确认实现和效果，当前系统仍需当前说明 |
| 4+1 | 逻辑、进程、开发组织、物理部署与场景的联系 | 混淆源码、进程、部署位置或业务步骤的说明 | 借鉴关注点分离和场景核对；不照搬原文中的年代性工具与层数建议 |
| SEI Views and Beyond 与架构文档审读 | 按使用者关注点选择视图，处理视图内信息、跨视图对应与整体信息 | 多视图能否覆盖任务，对象和模型之间能否对应 | 借鉴映射、覆盖及更小视图集合的检查；未执行完整程序或全面架构评价 |
C4 官方将四个静态层级作为可选择的抽象，明确按价值使用；动态与部署用于另外的关注点。其建议多数团队通常从上下文与容器开始，不能由此推出所有项目必须画相同数量的图。2
arc42 FAQ B-1 提醒文档带来持续维护负担，内容应由使用者需要决定。模板第 5 节同时将 building block view 视为其架构文档的必需部分，并允许职责表及相关局部展开。两处共同支持“结构职责应可理解、细节按价值裁剪”的选择。本研究采用这个结果要求，没有把模板原话改写成该方法不含必需内容。3
Nygard 的 ADR 原文描述架构重要决定及历史替代，末尾提供有限项目经验。它支持保存理由及后果的做法；该经验没有构成中文初学者或多年维护的效果对照。4+1 原文则直接讨论单图混合对象和关系的风险，并允许裁剪。其 development view 是源码模块组织，process view 是并发与同步，和 CI/CD 工作步骤各有含义。45
SEI 2009 审读方法按用途和参与者提出问题，其中关注跨模型对应、关注点覆盖和是否有更小的视图集合。它给出文档审读框架，没有自动完成对系统性能、安全或可靠性的架构评价。本文对这些概念作选择性应用，不声明符合 ANSI-IEEE 1471、ISO/IEC/IEEE 42010 或其他标准。67
哪些选择尚缺比较证据
方法资料支持组合各自有用的部分，但没有直接比较上述组合与单一方法在中文项目接手任务中的效果。本研究因此不排名“最佳框架”。若任务以结构总览为主，C4 已有价值；若要覆盖运维、约束和质量风险，arc42 的关注点检查更直接；重要理由长期存在时，ADR 补充当前说明。不同对象可以同时满足几个关注点，按方法分开写整套文档会增加重复。
图工具与共享模型的取舍
工具比较限定为表达和维护能力。本研究没有安装 LikeC4 或 Structurizr，也没有构建共享模型、导出比较、布局性能测试或维护工时测量。
| 方式 | 资料或案例支持的能力 | 成本与尚未确认的部分 |
|---|---|---|
| 文内 Mermaid | 本站已接入图源接口；历史五个图源通过本地解析；图文可以相邻维护 | 多图对象和关系仍需人工核对；解析不证明 SVG 布局、交互、可访问性或理解效果 |
| Structurizr DSL | 官方定义文本架构模型，并以 C4 为基础 | 模型与真实系统的对应、团队维护成本和本项目导出结果未试用 |
| LikeC4 | 官方 CLI 支持静态站构建、多种生成与导出；validate 说明语法与手动布局漂移检查 | 生成和校验不确认实现一致性；本项目模型语义、部署实例和导出损失未试用 |
| 可编辑图源加导出物 | 可将源用于其他载体、精确布局和传播 | 应在源维护含义；不同格式的信息损失与实际阅读效果需要相应核查 |
本案采用文内 Mermaid，因为本站接口已存在，对象与场景较少，源码职责可用表定位。引入共享模型的潜在收益是集中复用身份和关系，代价是新增模型、构建及实现映射维护。这个取舍有任务和接口依据，尚无长期成本数据。8
Mermaid 官方明确 parse 可以在不渲染时校验定义，历史试验调用本地 12.0.0。旧研究打开官方页时显示 12.1.0，结果归属实际安装版本。LikeC4 当前 CLI 文档描述 validate 检查语法与布局漂移，该范围没有承担图与源码一致的保证。9
小型案例怎样检验方法选择
输入与事实基线
2026-10-04 的案例限定为 apps/site/ 中“版本管理的正文经过构建和授权交付，读者阅读并搜索”的链路。提交基线为 3c75cac9d5017a313862905d7e67744c462a4a69 加当时工作树，Node 24.12.0、pnpm 10.24.0；包声明 Next.js 16.3.8、Fumadocs Core 16.15.18、Fumadocs MDX 15.4.6、Mermaid 12.0.0。提交本身没有保存后来全部工作树内容，旧实验只按所写输入和版本归属，不能由该提交单独重建整套环境。
| 核查对象 | 历史读取入口 | 对比较的作用 |
|---|---|---|
| 构建、公开范围与派生资源 | package.json、next.config.ts、source.config.ts、src/lib/source.ts、content-filter.ts、content-index.ts、src/app/(docs)/[...slug]/page.tsx | 认定静态导出、source 构造前过滤及统一派生；避免把构建模块当线上服务 |
| 搜索运行关系 | src/app/api/search/route.ts、src/components/layout/search-dialog.tsx、provider.tsx；安装包 fumadocs-core@16.15.18/dist/search/client/orama-static.js | 定位默认 /api/search 下载、按 from 缓存 Promise、本地搜索和 zbsearch 导入 |
| 配置中的环境与交付 | wrangler.jsonc、CI/预览/部署/回滚工作流、scripts/record-deployment.mjs | 连接软件与目标托管位置，发现预览与 CI 独立、恢复与验证条件不同 |
| 实验输入与断言 | tests/fixtures/、tests/build-fixture-site.ts、tests/check-static-export.mjs 及相关单元测试 | 辨认隔离样例、静态产物、替换 fetch 与检查范围 |
表内路径相对 apps/site/，工作流在根 .github/workflows/。Cloudflare 只是配置中的目标平台，研究没有查询账户、线上版本、域名或工作流执行。
表达组合的案头比较
| 候选组合 | 案头对照结果 | 作出的选择及限制 |
|---|---|---|
| 仅一张应用组成图 | 能识别客户端和资源服务，无法充分解释构建过滤、索引首次下载和交付失败 | 需要运行、环境和交付信息；结果来自关注点核对，未做真实读者对照 |
| 画齐 C4 层级并完整填写 arc42 | 组件和代码级图容易重复简单源码职责；多项模板内容可集中说明 | 采用选择性组合；没有测量全模板与裁剪方案的维护成本 |
| 目的角色文字、组成、部署、搜索场景、交付流程及实现与诊断表 | 能为声明问题提供明确表达位置；定位表补局部，环境说明补阶段差异 | 用作小型试用，不推广为所有项目的首批视图配额 |
历史代码核对发现三项具有方法价值的差异：使用 Next.js 的项目可以静态交付，不由框架名称推定线上 Node 服务；orama-static 的模块历史名与实际 zbsearch 导入不同；配置含恢复动作和版本记录，仍缺恢复后冒烟及期望旧版本断言。原来的 apps/site/docs/site.md 搜索引擎命名也与安装源码不同，当时记录了过时线索，未把它作为全站检出率结果。
独立 Agent 曾先仅凭原草稿解释组成、部署、搜索、开发、交付和变化影响，再只读核对源码。原稿根据其意见修正路径、术语、检查影响和恢复边界。该活动提供案头缺陷线索；审读者未复跑测试，身份与任务均不足以代表真实目标读者的效果试验。
构造变更检验维护影响
历史试用构造将索引地址从 /api/search 移至 /search-index.json 的目标方案，仍在浏览器查询，继续使用同一公开 source。未创建新路由、修改客户端或部署；新地址没有实现或访问证据。原研究制作了目标时序片段，再对照其与其他表达的对应。
| 历史案头动作 | 支持的判断 | 不能由此确认什么 |
|---|---|---|
| 核对组成与部署，保留原图 | 软件职责、位置及 HTTPS 联系未改变，该两图含义仍成立 | 真正实施后全部环境没有变化 |
修改目标搜索片段，关联生成入口与客户端 from | 改变的是地址契约，两端需要一致 | 新文件已经生成或能被请求 |
| 核对静态及草稿、冒烟检查中写定的旧地址 | 输出检查、浏览器请求和诊断路径也受影响；只改业务端点可能触发失败处置 | 未执行浏览器或外部检查，未测部署恢复 |
| 把旧技术结果限定于旧端点 | 原结果没有自动覆盖目标行为 | 新行为通过或影响分析完整 |
涉及地址的历史核查入口为 tests/check-static-export.mjs、tests/e2e/drafts.spec.ts、tests/e2e/smoke.spec.ts：静态检查读取 out/api/search，草稿和冒烟请求 /api/search。这次目标没有提供长期重要取舍，所以没有新增 ADR。教学图与过程分析已归专题，研究仅保留比较所需要的试验动作和结果。
试用检查结果
以下均为 2026-10-04 原研究记录的实际执行。它们确认各自对象；此次内容重组没有将旧结果当作新正文、新端点或新环境的检查通过。
| 历史检查 | 输入、实际动作与结果 | 覆盖边界 |
|---|---|---|
| 实现与关系核对 | 读取上述源码、配置和工作流，追踪过滤、生成、搜索及部署依赖 | 支持当时实现路径和配置逻辑，未查询线上 |
| 单元测试 | pnpm exec vitest run tests/unit/content-filter.test.ts tests/unit/content-index.test.ts tests/unit/link-resource-checks.test.ts，3 文件、42 项通过 | 过滤、引用与资源检查对应断言；没有目标新端点 |
| 静态 fixture 构建 | 执行 pnpm test:export，以 tests/fixtures/ 隔离内容构建，生产内链和静态产物检查通过 | 并未公开本调研或其他草稿；结果限于隔离样例，没有构建完整真实内容集或执行浏览器运行 |
| fixture 搜索 | 读取导出的 api/search 文件，在 Node 中替换 fetch 返回，再调用实际 staticClient；日志中 10 个查询均命中目标页 | 查询结果按前 3 个 URL 判断；脚本要求至少 9/10 命中，且“微调”“量化”命中。10/10 是该次观察，门槛为脚本断言；不代表真实网络或通用召回率 |
| 五个图源解析 | Node 提取原稿全部 5 个 Mermaid 图源，以 jsdom 提供 DOM，调用本地 Mermaid 12.0.0 的 mermaid.parse，全部通过 | 图源现在位于专题；只调用 parse，未 render。解析结果只支持原输入语法，图语义另经源码及案头核对 |
| 原稿 MDX 与格式 | node --import ./scripts/register-mdx.mjs 直接导入原草稿，编译通过；本页 ESLint、根 pnpm format:check 和 pnpm lint:names 通过 | 根 Prettier 当时忽略 MDX，正文格式由 MDX ESLint 检查；执行记录归属历史稿，重写正文另行检查 |
| 原稿相对链接与锚点 | 复用 next-validate-link 及本站解析配置，直接核对草稿，0 错误 | 没有以生产过滤跳过草稿；未探测外链；不能沿用为新链接检查结果 |
搜索输入分别为“注意力机制”“微调”“量化”“KV cache”“LoRA”“RAG”“大模型微调”“检索增强生成”“Next.js 静态导出”“中文 搜索”，对应 attention、adaptation、retrieval 三类 fixture 目标页。命中指每个查询前三条结果包含脚本所指定 URL，未测全部中文表述、排名稳定性或真实用户意图。静态检查还检查草稿和私有标记未泄露、引用解析、标签、OG 及 Markdown 产物，其断言服务于 fixture 的接口范围。
历史构建出现 Webpack 动态导入依赖分析的缓存警告，随后构建和断言成功。该警告限定缓存失效分析的信息，不改变实际退出结果，也没有提供浏览器运行证据。
| 未执行范围 | 为什么影响采用 |
|---|---|
| 浏览器图渲染、导航、交互及辅助技术 | Mermaid 解析与 MDX 编译不能确认 SVG 布局、客户端行为和可访问性 |
| LikeC4、Structurizr 等共享模型构建 | 没有模型复用与导出结果，无法判断引入成本或实际收益 |
| 真实目标读者试读 | Agent 案头审阅不确认中文接手者能理解、定位或维护 |
| 发布、线上部署和回滚 | 工作流存在仅为配置证据，本地 fixture 不能确认外部执行或恢复 |
| 复杂异步、事务、权限和数据恢复案例 | 当前静态系统未覆盖这些状态及失败条件 |
| 长期维护对照 | 目标变更在文档侧完成，未测真实实施更新工时或多次演进 |
采用判断与未解决问题
现有资料与案例足以支持按任务选择视图、区分软件与位置及阶段、核对关系、用场景建立对应、保留重要理由和随语义变化修订的条件化方法。案例还支持把语法、构建、实现、运行和读者证据分开报告。正式条款已经在仓库规范体系中维护，方法教学归专题；本研究继续承担比较依据和适用边界。
以下缺口会改变更强的选择：
| 未解决问题 | 影响的结论 | 下一类证据 |
|---|---|---|
| 中文目标读者能否完成解释与维护任务？ | 阅读入口、术语、图密度和省略尺度的效果 | 使用具体任务和材料版本试读，观察解释、定位和遗漏 |
| 共享模型能否降低总维护成本？ | 工具复杂度与跨视图一致性的取舍 | 在确有复用的同一项目中比较代表变更的更新与核查成本 |
| 复杂状态和失败下是否仍充分？ | 多环境、事务、重试、权限和迁移系统的采用 | 对应真实成功、失败与恢复场景及契约核查 |
| 图在本站是否实际易读可访问？ | Mermaid 载体的布局、导航和辅助技术适用性 | 获授权后的实际渲染与阅读验证 |
| 主要来源与证据如何长期可取？ | 变更同步和历史结果复核 | 在采用项目明确维护责任、证据版本与保留用途 |
因此本研究不确定统一工具链、固定阅读顺序或长期维护收益，不把案头发现和样例通过推广为一般效果保证。
资料与定位
外部资料初次核查于 2026-10-04，2026-10-05 复核范围见方法说明。以下定义与方法边界来自所列来源，案例组合和采用判断为本研究综合。
Footnotes
-
内容生产规范基础调研。两份历史方案为仓库根相对路径
archive/architecture-documentation-plan-2026-10-03.md与archive/foundations-to-project-documentation-2026-10-04.md；2026-10-04 核查来自当时cb8c工作树，当前归档保持原位。这里只保留出处及取舍，比较结论在本页完成。 ↩ -
C4，Diagrams、Container、Deployment diagram 与 Notation，静态层级、运行边界、实例与环境、关系表达。 ↩
-
arc42，FAQ B-1、5. Building Block View、6. Runtime View，裁剪、结构及代表性运行场景。维护依据为 FAQ H-3，文字替代依据为 W3C WAI Complex Images。 ↩
-
Michael Nygard，2011，Documenting Architecture Decisions，Decision、Status、Consequences 与有限 Experience Report。原研究另参考 MADR About MADR 的可选 Confirmation 语义，没有照搬字段。 ↩
-
Philippe Kruchten，1995，Architectural Blueprints—The “4+1” View Model of Software Architecture，PDF 第 1–2 页总论，第 4–7 页进程与开发组织，第 10–13 页对应及裁剪。 ↩
-
SEI，2005，Comparing the SEI’s Views and Beyond Approach for Documenting Software Architectures with ANSI-IEEE 1471-2000，原研究读取 §2.2、§2.4、§2.5，视图分类、选择与映射。本次旧入口未能再次取得，不作当前标准符合性依据。 ↩
-
SEI，2009，A Structured Approach for Reviewing Architecture Documentation，§2.1.2、§2.2 的用途与参与者，§4.2 问题 11–13 的对应、覆盖与更小视图集合。 ↩
-
Structurizr，DSL；LikeC4，CLI，Build static website、导出与生成、Validate。工具能力来自官方说明，本文没有安装或运行证据。 ↩
-
Mermaid，Usage — Syntax validation without rendering。历史运行的实际版本为 12.0.0。 ↩
最后更新于