Stop your Flutter architecture from drifting: layer rules and cycle checks in your IDE and CI with arch_guard

说明与用途

arch_guard 能检测 Flutter 项目中的架构违规，包括错误的导入、禁止的包和循环依赖，并与 IDE、测试和 CI 集成。

问题

Flutter projects often drift from their intended architecture, with widgets importing repository implementations directly and services importing each other, leading to broken architecture diagrams and hidden violations that the analyzer and tests do not catch.

结果

After adopting arch_guard, architecture violations are caught early in the IDE, tests, and CI. Baselines allow teams to focus on new violations, and the tool provides interactive graphs and quick fixes, reducing architecture drift.

工作流

• Add arch_guard as a dev dependency: dart pub add --dev arch_guard
• Initialize configuration: dart run arch_guard init (detects layout and writes arch_guard.yaml)
• Run checks: dart run arch_guard (reports violations)
• Configure IDE plugin: add arch_guard_lint to analysis_options.yaml
• Add architecture test: import package:arch_guard/testing.dart and call expectArchitecture() in tests
• Set up CI workflow to run arch_guard on pull requests
• Use --update-baseline to record current violations and allow only new ones to fail CI

证据

Every Flutter project I've worked on started with a clean folder structure: domain, data, presentation, maybe a features/ folder. And on every one, six months later, a widget was importing a repository implementation directly, and two services imported each other.

来源

arch_guard runs Tarjan's algorithm over the import graph and reports every group of files that import each other, with fan-in/fan-out, instability and the "hub" files.

来源

If you'd rather keep architecture rules next to the code, they also run in dart test / flutter test: ... It fails exactly when the CLI would, with a readable list of problems.

来源