React+TypeScript项目架构守护：ArchGuard实战指南-开发者社区

1. 项目概述：为什么我们需要一个“架构守护者”？

在React和TypeScript项目里摸爬滚打几年后，我越来越觉得，代码架构的腐化往往不是一夜之间发生的。它更像是一种“熵增”：今天某个ui组件图方便，直接引用了domain层的某个模型；明天某个features模块为了复用逻辑，又反向依赖了ui层的一个工具函数。起初只是几个黄色的波浪线警告，大家觉得“问题不大，先这样吧”。等过几个月再回头看，整个项目的依赖关系已经乱成一团意大利面，牵一发而动全身，没人敢轻易改动，新功能的开发成本直线上升。

这就是我最初接触并决定深入研究ArchGuard这类工具的原因。它不是一个庞大的、试图解决所有问题的静态分析框架，而是一个精准、快速、本地优先的架构守护CLI工具。它的核心目标非常明确：在React + TypeScript的技术栈下，通过明确的规则配置（比如architecture.yaml），强制检查并阻止那些违反预设分层架构的代码导入，把架构腐化扼杀在提交之前。

简单来说，ArchGuard就像是你项目里的一个“交通警察”。你事先画好道路规则（比如domain层是单行道，只出不进；ui层不能直接开进domain层），然后这个警察就24小时盯着你的代码，一旦有“车辆”（即代码导入）违规，立刻亮红灯，让你在本地开发或CI流程中就快速失败（Fail Fast）。这对于追求代码长期可维护性的团队来说，价值巨大。它特别适合那些已经有意采用清晰分层（如domain（领域模型）、features（功能模块）、ui（展示组件））但缺乏自动化手段来确保规则被遵守的团队。

2. 核心设计思路：在“灵活”与“约束”之间找到平衡点

ArchGuard的设计哲学非常值得玩味，它走的是一条“小而美”的路线，这与市面上许多大而全的架构分析工具形成了鲜明对比。理解这个设计思路，能帮你更好地判断它是否适合你的项目。

2.1 确定性规则 vs. 启发式推断

很多架构分析工具会尝试去“理解”你的代码意图，通过复杂的启发式算法推断模块边界、识别设计模式。这种方式听起来很智能，但往往伴随着高误报率、复杂的配置和缓慢的分析速度。ArchGuard反其道而行之，它采用确定性规则。你需要在一个名为architecture.yaml的配置文件里，白纸黑字地定义每一层（Layer）允许导入（allowedImports）哪些其他层。

比如，你规定ui层只能导入features和shared层。那么，任何从ui指向domain的import语句，无论出于什么原因，都会被ArchGuard无情地标记为违规。这种方式的优势极其明显：规则透明、结果确定、执行飞快。工具不需要去猜测你的架构，它只是你定义的规则的忠实执行者。当然，这也意味着你需要对自己的架构有清晰的认知，并且愿意将这种认知转化为明确的配置。

2.2 本地优先与渐进式采用

另一个关键设计是“本地优先”（Local-First）。ArchGuard的核心是一个CLI工具，你可以在开发者的本地机器上、在提交代码前的Git钩子（Pre-commit Hook）里、或者在持续集成（CI）流水线中运行它。这种设计确保了反馈环最短——开发者刚写出违规代码，几秒钟内就能得到提示并修正，而不是等到代码评审时再由同事指出，或者更糟，等到上线后才发现架构隐患。

考虑到现实情况，很多项目在引入架构检查工具时，已经积压了大量的历史“债务”（即已有的架构违规）。如果工具一上来就“一刀切”地阻止所有提交，项目可能直接就停滞了。ArchGuard非常贴心地提供了基线（Baseline）模式。你可以先运行一次检查，将所有当前存在的违规记录为一个“基线”文件（.archguard-baseline.json）。之后的检查可以基于这个基线，只报告新出现的违规，而对历史问题保持沉默。这允许团队以“增量修复”的方式，逐步清理历史债务，平滑地引入架构守护，而不会阻断正常的开发流程。

2.3 有限的、面向React的深度检查

除了最核心的层间导入检查，ArchGuard还内置了几条针对React项目的、具有明确业务价值的代码质量规则。这些规则不是语法检查（那是ESLint的活儿），而是代码结构检查：

noBusinessLogicInComponents: 禁止在React组件中包含循环等复杂业务逻辑。这敦促你将逻辑抽离到features或domain层的自定义Hook、Service或Store中，保持组件的纯粹性。
noDataFetchingInUI: 禁止在UI组件中直接进行数据获取（如调用fetch或axios）。这强制推行关注点分离，数据获取应在features层处理，然后通过props或context注入UI。
noCircularLayerDeps: 检测并禁止层与层之间的循环依赖。循环依赖是架构腐化和模块耦合的典型标志，必须被消除。

这些规则共同构成了一个轻量级但强有力的“架构卫生”检查组合拳。

3. 从零开始：安装、初始化与首次检查

理论说得再多，不如亲手跑一遍。下面我就带你完整走一遍ArchGuard的接入流程，其中会穿插很多我实际踩过的坑和总结的技巧。

3.1 安装方式的选择与避坑

官方提供了两种安装方式：从npm安装和从源码构建。对于绝大多数用户，直接使用npm安装是首选。

npm install --save-dev @archguard/cli

注意：安装后，尝试运行npx archguard --version来验证是否安装成功。如果遇到“命令未找到”的错误，很可能是因为@archguard这个npm作用域（scope）的包尚未公开，或者你的npm registry配置有问题。这时，你需要确认你安装的包来源是否正确。根据项目README，这个作用域目前可能还是私有的，所以更可靠的方式是后续的“从源码构建”。

更可靠的实践：从源码构建并链接由于项目较新，公开的npm包可能不稳定，我强烈建议采用从GitHub仓库克隆并本地构建的方式，这对于早期评估和内部推广尤其有用。

# 1. 克隆仓库 git clone <ArchGuard的仓库URL> cd ArchGuard # 2. 安装依赖并构建 npm install npm run build # 这会编译所有TypeScript包 # 3. 将CLI工具链接到全局 npm link

执行npm link后，archguard命令就会在你的系统全局可用。现在，你可以在任何其他本地项目目录中直接使用archguard命令了。这种方式让你始终使用最新的主分支代码，但需要注意，不同项目间如果ArchGuard版本差异过大，可能会有行为不一致的风险。

3.2 项目初始化：生成你的架构宪法

安装好CLI后，进入你想要引入架构守护的React+TypeScript项目根目录，运行初始化命令：

archguard init

这个命令会做以下几件重要的事情：

环境检查：它会快速扫描项目，确认这是一个React+TypeScript项目（主要检查package.json和tsconfig.json）。
创建核心配置：在项目根目录生成architecture.yaml文件。这是ArchGuard的“宪法”，所有规则都基于此文件。
生成指导文档：
- 生成AGENTS.md文件（如果不存在）。这个文件像是给新队员的“架构导览手册”，用自然语言解释了项目的分层规则。
- 在.archguard/目录下生成ARCHITECTURE_RULES.md。这是更详细的规则技术说明书，方便工具链（如IDE插件）引用。
安装Git钩子：如果项目根目录下没有已有的.git/hooks/pre-commit钩子，它会自动安装一个。这个钩子会在每次git commit前自动运行archguard check，确保提交的代码不违反架构规则。

初始化时的关键决策：预设（Preset）选择运行archguard init会使用默认的分层配置。但如果你所在团队采用的是类似“Feature-Sliced Design”这样的流行架构方法论，你可以直接使用其预设来初始化，这能省去大量手动配置的功夫。

archguard init --preset feature-sliced-react

这个预设会生成一套适配Feature-Sliced设计的architecture.yaml，通常包含app,processes,features,entities,shared等层次。你可以基于这个预设再微调，比从零开始写要高效得多。

3.3 运行第一次检查：直面你的技术债务

初始化完成后，激动人心（也可能令人心惊肉跳）的时刻到了：运行第一次架构检查。

archguard check

这时，你的终端可能会输出一片“违规”（Violation）信息。别慌，这非常正常，尤其是对于已有一定规模的项目。每条违规信息通常会包含：违规文件路径、违规的导入语句、违反了哪条规则，以及涉及的层。例如：

❌ Violation: Layer import violation File: src/ui/components/ProductList.tsx Import: import { Product } from ‘../../domain/models/product‘; Rule: ui layer cannot import from domain layer.

第一次运行，你的目标不是解决所有问题，而是评估问题的规模。如果违规成百上千，别想着一次性修复，那会是一场灾难。这时，就该请出我们之前提到的“救星”——基线模式。

4. 渐进式落地：基线模式与CI集成实战

对于存在历史债务的项目，强行要求立即通过所有检查是不现实的。ArchGuard的基线模式（Baseline Mode）是平滑落地的关键。

4.1 建立并利用基线文件

生成基线：首先，我们承认现状，将当前所有违规保存为基线。这不会修复任何问题，只是做一个“快照”。
```
archguard check --update-baseline
```
这个命令会执行检查，并将所有发现的违规信息写入.archguard-baseline.json文件。这个文件务必加入版本控制（.gitignore中不要忽略它），因为团队所有成员都需要基于同一份基线进行开发。
基于基线进行检查：在后续的开发中，无论是本地还是CI，我们都使用--baseline参数来运行检查。
```
archguard check --baseline
```
此时，ArchGuard会读取基线文件，并只报告那些不在基线中的新违规。对于基线中已存在的历史问题，它会保持沉默。这样，团队就可以专注于防止架构进一步腐化，而历史问题可以安排计划逐步重构修复。
更新基线：当你修复了某些历史违规后，需要更新基线文件，将这些已修复的问题从基线中移除，以免后续检查再次被忽略（实际上它们已经不存在了）。
```
# 先修复代码... # 然后更新基线 archguard check --update-baseline
```
一个重要的实践：建议将--update-baseline作为一项需要评审的、独立的开发任务，而不是随意执行。因为更新基线意味着你接受了当前代码库的状态作为新的标准。

4.2 集成到CI/CD流水线：守住最后一道门

本地钩子能防止开发者提交坏代码，但CI集成是确保合入主分支的代码绝对健康的最后一道防线。ArchGuard可以很容易地集成到GitHub Actions中。

基础集成示例：

name: ArchGuard Check on: [push, pull_request] jobs: archguard: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: lindseystead/ArchGuard@v1 # 使用官方提供的Action with: format: ‘json‘ # 输出格式，便于后续处理

高级集成：与GitHub代码扫描（Code Scanning）联动GitHub的代码扫描功能可以可视化地展示各种安全检查工具的结果。ArchGuard支持SARIF格式输出，可以无缝接入。

- uses: actions/checkout@v4 - id: archguard # 给步骤一个ID，便于后续引用结果 continue-on-error: true # 即使ArchGuard检查失败，也继续执行后续步骤（为了上传报告） uses: lindseystead/ArchGuard@v1 with: format: sarif output-file: reports/archguard.sarif # 输出SARIF报告文件 - if: ${{ always() }} # 无论上一步成功与否，都执行上传 uses: github/codeql-action/upload-sarif@v3 with: sarif_file: reports/archguard.sarif - if: ${{ steps.archguard.outcome == ‘failure‘ }} run: exit 1 # 如果ArchGuard检查失败，最终让整个CI作业失败

这样配置后，每次PR的代码扫描区域都会出现ArchGuard的检查结果，架构违规会和安全隐患一样被清晰标注出来，极大地提升了问题的可见度和修复的紧迫性。

5. 深度配置解析：定制你的架构规则

architecture.yaml是ArchGuard的大脑。理解其每一项配置，才能让它真正为你所用。

5.1 层（Layers）定义：构建你的依赖拓扑

层的定义是配置的核心。每个层需要两个关键属性：path（路径模式）和allowedImports（允许导入的层列表）。

layers: domain: path: ‘src/domain/**/*‘ # 使用glob模式匹配文件 allowedImports: [] # 领域层是核心，不允许导入任何其他层（除了node_modules） features: path: ‘src/features/**/*‘ allowedImports: [domain, shared] # 功能层可以依赖领域层和共享层 ui: path: ‘src/ui/**/*‘ allowedImports: [features, shared] # UI层只能依赖功能层和共享层 shared: path: ‘src/shared/**/*‘ allowedImports: [] # 共享层通常也是独立的，不依赖其他业务层

配置要点与陷阱：

路径匹配：path支持简单的glob模式。确保你的模式能唯一匹配到目标文件，避免重叠。如果两个层的模式匹配了同一个文件，ArchGuard可能会产生不可预知的行为。
循环依赖检查：noCircularLayerDeps规则会基于allowedImports自动计算层之间的依赖关系图，并检查是否存在循环。即使A层允许导入B，B层允许导入C，如果C层又允许导入A，就会构成循环依赖，被规则捕获。
“允许导入”列表是白名单：不在列表中的层，绝对不允许导入。[]空列表表示该层是“最底层”，不依赖任何其他内部层。

5.2 规则（Rules）详解：超越导入检查

除了层规则，ArchGuard还提供了一些代码结构规则。

rules: noBusinessLogicInComponents: true noDataFetchingInUI: true enforceFeatureBoundaries: true noCircularLayerDeps: true

noBusinessLogicInComponents: 这条规则会扫描React组件（函数组件或类组件），寻找for、while循环，复杂的if-else链，以及可能的数据转换逻辑。它的目的是推动逻辑与视图分离。触发违规并不意味着代码有错，而是一个强烈的信号：“这段逻辑可能应该被提取到Hook或Service中”。
noDataFetchingInUI: 这条规则会查找组件中直接使用的fetch、axios、useSWR、react-query的useQuery等数据获取模式的调用。它强制推行数据获取逻辑上移到features层，UI组件只负责接收数据和渲染。这对于保持组件的可测试性和可复用性至关重要。
enforceFeatureBoundaries: 这是一个实验性或预设相关的规则，在某些架构模式（如Feature-Sliced）中，用于强制特性（Feature）之间的隔离。需要查阅具体预设的文档来了解其确切行为。
noCircularLayerDeps: 如前所述，自动检查层定义之间的循环依赖。

5.3 路径别名（Path Alias）解析

现代TypeScript项目普遍使用tsconfig.json中的paths配置来定义路径别名，避免丑陋的../../../。ArchGuard能够解析这些常见的别名配置。

例如，如果你的tsconfig.json里有：

{ “compilerOptions”: { “baseUrl”: “./src“, “paths”: { “@/*”: [“*”], “@domain/*”: [“domain/*”] } } }

当ArchGuard在代码中看到import { Product } from ‘@domain/models/product‘;时，它会正确地将这个导入解析到src/domain/models/product.ts，然后根据其所在目录匹配到相应的层，再进行规则判断。这意味着你无需为ArchGuard做额外配置，它开箱即用地支持你的项目别名设置，这是一个非常贴心的设计。

6. 常见问题排查与实战技巧

在实际引入ArchGuard的过程中，你肯定会遇到各种问题。下面是我总结的一些典型场景和解决方案。

6.1 问题速查表

问题现象	可能原因	解决方案
运行`archguard check`无任何输出	1. 当前目录下没有匹配的`.ts/.tsx`文件。 2.`architecture.yaml`配置错误或不存在。 3. 所有代码都符合规则。	1. 确保在项目根目录运行，并使用`--verbose`标志查看过程。 2. 运行`archguard init`重新生成配置。 3. 恭喜你，代码很健康！
报告了错误的层违规	1.`layers.path`的glob模式匹配不准确，文件被归错了层。 2. 路径别名未被正确解析。	1. 仔细检查`architecture.yaml`中的`path`模式，确保能精确匹配目标文件。可以使用`archguard check --debug`查看文件被分配到了哪一层。 2. 确认`tsconfig.json`中的`paths`配置正确，且ArchGuard运行在包含该配置的目录下。
第三方库（node_modules）导入被误报	ArchGuard默认会分析所有导入，包括第三方库。	这是正常行为。ArchGuard的层规则只约束项目内部层之间的导入。从`ui`层导入`react`或`lodash`不会触发违规，因为这些模块不在你定义的任何`layer`中。违规只发生在从一个内部层导入另一个不被允许的内部层时。
基线模式不工作，依然报告所有旧问题	1.`.archguard-baseline.json`文件不存在或路径不对。 2. 基线文件内容格式错误。 3. 运行命令时未指定`--baseline`参数。	1. 确保在项目根目录运行，且基线文件存在。 2. 不要手动编辑基线文件，使用`--update-baseline`命令生成。 3. 确认CI脚本和本地钩子都正确添加了`--baseline`参数。
规则`noDataFetchingInUI`误报	组件中包含了类似数据获取函数名的变量或类型定义。	ArchGuard的检查是基于简单AST模式匹配的启发式方法，并非完整的语义分析。如果误报，可以考虑：1. 将数据获取逻辑抽象成一个Hook，并在组件中调用它（这是推荐做法）。2. 如果确有特殊原因，目前可能需要暂时关闭该条规则（将配置设为`false`），并等待工具未来提供更精细的配置或忽略注释。

6.2 实战技巧与心得

从小处着手，逐步推广：不要试图在拥有50万行代码的老项目上一次性启用所有规则。可以先在一个全新的、独立的模块或微前端应用中试点ArchGuard。让团队看到它在小范围内带来的清晰度和开发体验提升，再逐步推广到核心业务代码。初期甚至可以只开启noCircularLayerDeps这一条破坏性最小的规则。
将architecture.yaml视为活文档：这个配置文件本身就是对项目架构最权威、最机器可读的说明。鼓励团队在调整架构时，首先更新这个文件。可以把它放在项目文档的显眼位置，新成员 onboarding 时，要求他们先阅读这个文件。
与代码评审（Code Review）结合：ArchGuard自动化检查了硬性的架构规则，但一些更软性的设计问题（如“这个组件是否过于庞大”、“这个Hook的职责是否单一”）仍然需要人工评审。在PR模板中，可以增加一项检查：“本次改动是否引入了新的ArchGuard违规？是否更新了基线文件？” 将工具和人的智慧结合起来。
处理“合理”的例外情况：任何规则都有例外。也许某个ui组件确实需要直接引用一个domain的枚举类型。目前ArchGuard没有提供文件或行级别的忽略注释（如// archguard-ignore-next-line）。对于这种极少数情况，目前的变通方案是：要么调整架构，让这个枚举上移到shared层；要么暂时将这个文件从对应的layer.path中排除（通过更精确的glob模式），但这会削弱检查力度。期待未来版本能支持更灵活的忽略机制。
关注性能：对于大型项目，运行全量检查可能会花费几秒到十几秒。虽然这通常在可接受范围内，但建议将archguard check仅作为预提交钩子和CI流水线的一部分，而不是在每次文件保存时都运行（那会拖慢IDE）。确保你的.archguard-baseline.json文件不要过大，定期清理已修复的旧条目。

引入ArchGuard这样的工具，本质上是一场关于开发习惯和工程纪律的文化变革。它开始时可能会带来一些“不便”，因为它阻止了你快速但不规范的编码行为。但长期来看，它通过强制性的约束，为团队培养出良好的架构意识，最终换来的是可维护性、可扩展性极高的代码库，以及随之而来的研发效率和团队信心的提升。这其中的投入产出比，在项目进入维护期后，会体现得淋漓尽致。