企业官网建设流程全解析

本文以 architecture-decision-record 开源仓库中的一份完整 ADR 示例——CSS 框架选型决策记录 为主线，逐节剖析"问题、决策、状态、假设、约束、立场、论证、影响、关联"这套成熟决策模板的写法，并结合仓库内的模板定义、示例索引与多语言镜像机制，说明如何把一份真实的框架选型决策写成可追溯、可复用、可评审的架构决策记录。读完本文，你将掌握 Tyree–Akerman 风格 ADR 的完整骨架，理解"无 jQuery 依赖"为何会成为现代前端选型的关键约束，并能把同一套方法迁移到自己的技术选型场景中。

一、这份 ADR 说了什么：问题、决策与状态

这份 ADR 位于仓库的 locales/en-us/examples/css-framework/README.md（另有内容完全一致的 index.md，供网站构建使用），其正文遵循标准的 ADR 三段式开头：

Issue（问题）——为什么要做这个决策：

• 希望在所有主流浏览器和屏幕尺寸上获得快速、可靠的用户体验；
• 希望在设计与布局、UI/UX 等方面快速迭代；
• 希望应用具备响应式能力，尤其是手机等小屏、4K 宽屏等大屏，以及可旋转显示器这类动态屏幕。

Decision（决策）——选型结论一句话：Decided on Bulma.（决定采用 Bulma）。

Status（状态）——Decided on Bulma. Open to new CSS framework choices as they arrive.（已决定采用 Bulma，同时对将来出现的新 CSS 框架持开放态度）。

这一"结论先行"的写法非常典型：任何读者（包括后续加入团队的新人）只需扫一眼 Summary 就能拿到决策结果与时效状态，而细节则沉淀在后面的 Details 中。仓库主 README（README.md）对 ADR 的定义也印证了这一点：架构决策记录（ADR）是"记录一项重要架构决策及其上下文与后果的文档"，其中 AD（architecture decision）是"解决重大需求的一种软件设计选择"。

二、骨架来源：Jeff Tyree 与 Art Akerman 的决策记录模板

这份 CSS 框架 ADR 的章节结构并非随意编排，而是对应仓库中收录的 Jeff Tyree 与 Art Akerman 决策记录模板。该模板源自 Capital One 的 Jeff Tyree 与 Art Akerman 发表的《Architecture Decisions: Demystifying Architecture》一文，属于比 Michael Nygard 的四段式（Status/Context/Decision/Consequences，见 Michael Nygard 模板）更精细的"决策描述"体系。

对照模板逐项看，CSS 框架 ADR 用到了其中的这些字段：

模板原文还提示了 Positions 段的关键价值：它"能避免最终评审时被问到'你考虑过……吗'，从而避免公信力受损"，同时"明确陈述他人的意见有助于把方案的拥护者拉进你的决策"。这份 ADR 正是这样做的——它不仅记录了胜出的 Bulma，还如实记录了败选的 Semantic UI 及其失败原因。

三、假设（Assumptions）：为什么"现代 Web 应用"要与 jQuery 划清界限

ADR 的假设段交代了决策环境的时代背景：团队要创建"现代、快速、可靠、响应式"的 Web 应用，而典型现代 Web 应用正在减少乃至消除 jQuery 的使用。理由被归纳为三点：

1. 原生能力替代：现代 JavaScript 已逐步纳入许多 jQuery 曾提供的功能，jQuery 的必要性下降，且存在更好、更快、更小的模块提供特定实现；
2. 编程范式冲突：jQuery 的总体做法是直接操作 DOM，而直接 DOM 操作对 React、Vue、Svelte 这类现代 JavaScript 框架而言是一种反模式；
3. 加载健壮性：jQuery 若被加载两次会自我干扰（$被覆盖、插件重复绑定等问题）。

这一假设随后直接转化为硬约束，可见 ADR 中"假设"并非空洞的背景介绍，而是后续约束与论证的逻辑前提。仓库中的其他示例也体现了同样的"假设驱动决策"写法，例如 环境变量配置 ADR 以"12 factor app / 15 factor app"实践为假设，推导出.env文件方案。

四、约束（Constraints）：框架依赖与组件丰富度的两难

ADR 的 Constraints 段把选型空间压缩成两个可操作的判断维度：

• 维度一：是否拖入 jQuery。如果选择使用 jQuery 的 CSS 框架，团队就被迫引入 jQuery。文档点名示例：Semantic UI 使用 jQuery，而 Tachyons 不使用。
• 维度二：组件丰富度。如果选择极简框架，就会放弃现在或不久后可能需要的框架组件。文档点名示例：Semantic UI 提供图片轮播（image carousel），而 Tachyons 不提供。

这两条约束共同刻画了选型目标的"甜点区"：既要组件够用，又不能背负 jQuery 依赖。这与仓库内容规范（spec/content.md）强调的"不编造事实、不引入源文档没有的版本与链接"一脉相承——约束必须写真实存在的权衡，而非想象中的优劣。

五、立场（Positions）：从无框架、短名单筛选到双方案深评

Positions 是这份 ADR 信息密度最高的部分，完整记录了考察过的每一类方案：

5.1 无框架方案

团队首先考虑了完全不使用框架。文档评价"这看起来仍然可行，特别是因为 CSS grid 提供了我们项目所需的大部分功能"。注意这里特意承认了该方案的合理性——好的 ADR 不把落选方案写成"明显错误"，而是如实记录其可行面，这正是 Tyree–Akerman 模板要求的"避免评审时被质疑"。

5.2 快速短名单筛选

团队用快速短名单（quick shortlist triage）过了一遍主流框架：Bootstrap、Bulma、Foundation、Materialize、Semantic UI、Tachyons等，最终挑出两个进入深入评审：

• Semantic UI——因为"最具语义化"（most-semantic approach）；
• Bulma——因为"最轻量，同时提供了我们现在想要的组件"。

5.3 Semantic UI 试点：静态页成功，SPA 失败

对 Semantic UI 的评审不是纸上谈兵，而是做了两种方式的试点：

• 使用典型的CDN 文件；
• 使用NPM 仓库。

试点结果是：在静态 HTML 页面中成功使用了 Semantic UI，但在限定的时间盒（timebox）内未能成功构建 JavaScript 单页应用（SPA），主要原因正是jQuery 加载问题。ADR 还记录了外部佐证：其他开发者多年来一直请求 Semantic UI 官方提供无 jQuery 版本，但开发者明确拒绝，理由是"无 jQuery 版本太难编写，例如 Semantic UI 项目有超过 22,000 个使用 jQuery 的接触点（touchpoints）"。这条"22,000 touchpoints"的引述让"技术不可行"从团队感受变成了有据可查的外部事实。

试点对应的典型标记结构如下（Semantic UI 的 tab 菜单写法）：

<div class="ui top attached tabular menu"> <a class="item">Alpha</a> <a class="item">Bravo</a> </div>

5.4 Bulma 评估：相似能力，更轻的现代实现

Bulma 与 Semantic UI 能力相近，但复杂组件数量较少；其关键差异在于用现代技术构建、不依赖 jQuery，且存在一些可选的第三方组件。对应的 Bulma 写法（tabs 组件）为：

<div class="tabs"> <ul> <li><a>Alpha</a></li> <li><a>Bravo</a></li> </ul> </div>

两段 HTML 对比直观呈现了"语义化类名 vs 轻量结构"的差异，也让后续的论证有了可落地的代码依据。

六、论证（Argument）：技术与领导力两个维度的警示旗

ADR 的 Argument 段给出了最终取舍的理由，且分为两个层次：

• 技术维度：Semantic UI 有大量 jQuery 接触点，与团队的现代前端技术栈（React、Vue、Svelte 等）存在范式冲突，试点已在 SPA 场景实际受挫；
• 领导力/项目治理维度：面对社区多年来的无 jQuery 诉求，Semantic UI 的回应是"断然否定"（hard no），而非尝试制定路线图（roadmap）、持续改进（continuous improvement）或募捐（donation fundraising）等折中路径。

文档用"caution flag"（警示旗）一词同时概括这两个维度——这提醒我们，ADR 的论证不必只谈技术指标，开源项目的维护方向与社区响应方式同样是选型时值得记录的决策输入。

仓库中的另一份 CSS 相关示例 Tailwind CSS ADR 展示了同样思路的不同写法：它用 "Decision Drivers"（易用、可定制、社区支持、节省时间）驱动决策，最终基于配置化定制与活跃社区选择 Tailwind CSS。两相对照，可以看出同一主题下不同模板的呈现差异。

七、影响与关联信息（Implications & Related）

ADR 的收尾部分把决策"织回"项目全景，指明后续动作与对齐目标：

• Related decisions（关联决策）：所选 CSS 框架可能影响可测试性——提示该决策并非孤岛，后续可能需要配套的测试策略决策。
• Related requirements（关联需求）：希望快速交付一个纯现代（purely-modern）应用；不想把时间花在使用旧依赖（尤其是 jQuery）的旧框架（尤其是 Semantic UI）上。
• Related artifacts（关联制品）：影响所有将使用该 CSS 的典型 HTML。
• Related principles（关联原则）：易于撤销（Easily reversible）与追求速度（Need for speed）——这正是 Tyree–Akerman 模板所强调的"决策须与企业既定原则保持一致，确保跨领域对齐"。
• Notes（备注）：模板中保留"此处填写任何备注"的占位，供决策社会化（socialization）过程中积累讨论议题。

其中"易于撤销"原则与仓库建议的 ADR 实践高度呼应：仓库在 撰写好 ADR 的建议 中提出 ADR 应包含充分 rationale（理由）、聚焦单一决策、标注时间戳、保持不可变（新信息通过追加或新建 ADR 承载）；而 团队协作建议 则给出务实补充——实践中"活文档"式追加更新往往比严格不可变更利于团队采纳。选一个"易于撤销"的框架，正是为了让这条决策在环境变化时能被低成本推翻并重写 ADR。

八、仓库佐证：这份示例在项目中的组织方式与复用价值

在 architecture-decision-record 仓库中，这份 CSS 框架 ADR 不是孤立文件，而是整套内容体系的一环，具有明确的组织与复用约定：

• 示例索引：仓库的 示例总览 将 CSS 框架列为"General（通用示例）"之首，与其他技术选型示例并列；
• 模板配套：它采用的正是上文分析的 Tyree–Akerman 模板，仓库共收录 11 套模板（Nygard、arc42、EdgeX、MADR、Planguage 等），可按决策复杂度选用；
• 多语言镜像：该示例被翻译为多种语言，例如简体中文版位于 locales/zh-cn/示例/css框架/README.md。依据内容规范 spec/content.md，en-001是内容的事实源头（source of truth），其余 locale 均为其翻译，且翻译时产品、工具、公司名保持拉丁字母不变，代码块与文件名不翻译，不得虚构源文档中不存在的事实、版本或链接；
• 案例对照：同目录下的 Tailwind CSS ADR、环境变量配置 ADR 等共同构成"同一问题、不同模板/不同结论"的参考样本集。

九、实战启示：如何把这份 ADR 迁移到自己的选型场景

把这份 CSS 框架 ADR 作为模板套用到你自己的技术选型时，可以提炼出五条可操作步骤：

1. 先写结论三件套：用 Issue 三句话讲清痛点（性能、迭代速度、响应式目标），用 Decision 一行给出结论，用 Status 标注时效与开放度；
2. 把"时代假设"写进 Assumptions：如同本文把"现代 Web 应用摆脱 jQuery"写为假设，你的 ADR 应显式记录技术趋势、团队技能与既有代码基等环境前提；
3. 用两条以上约束卡死候选集：仿照"是否引入旧依赖 + 组件丰富度"的组合，把选型空间压缩到可评审的范围；
4. 对入围方案做真实试点：参考本文"静态页成功、SPA 失败"的记录方式，用可复现的实验结果而非印象给每个 Position 打分，并附上最小代码示例；
5. 从技术与治理两个维度写 Argument，并补全 Related 信息：既记录技术指标，也记录社区维护态度；最后把决策与可测试性、交付速度、可撤销性等原则显式挂钩，让决策可追溯、可评审、可演进。

这份 ADR 之所以值得作为范本，正因为它示范了"轻量文档承载严肃选型"的完整姿势：结论明确、假设透明、方案有试点、论证有依据、影响有清单——这正是架构决策记录（ADR）在现代软件规划中真正的价值所在。