itsmelaxman/flutter_guardian

# Flutter Guardian [](https://pub.dartlang.org/packages/flutter_guardian) [](https://github.com/itsmelaxman/flutter_guardian/blob/main/LICENSE) [](https://github.com/itsmelaxman/flutter_guardian) Flutter Guardian 是一款 CI 优先的 Flutter 应用发布审计工具。 它可以帮助你在应用发布前捕获常见的风险，包括安全隐患、架构违规、依赖问题、资源问题以及构建配置缺失。 你可以在开发阶段于本地使用它，或者在 CI 中运行它，以便在违反重要发布规则时使构建失败。 ## 它的功能 Flutter Guardian 会检查你项目中的： - 安全风险，例如 debug 日志、`.env` 的使用、硬编码的 secrets 以及缺失的发布安全防护。 - 架构问题，例如 feature 之间的相互引用以及无效的分层方向。 - 依赖问题，例如不安全或过弱的版本约束。 - 资源问题，例如缺失、重复或过大的资源。 - 构建就绪问题，例如过大的发布构件或不安全的 Android 设置。 - 针对 `.env`、YAML 和 JSON 输入的生成配置安全性。 Flutter Guardian 不是一个 UI 框架、runtime SDK，也不是 Flutter 分析器的替代品。它是一个在发布前运行的发布守护工具。 ## 安装 全局激活它： ``` dart pub global activate flutter_guardian ``` 或者将其作为开发依赖添加到你的应用中： ``` dev_dependencies: flutter_guardian: ^1.0.1 ``` 如果你是基于此仓库进行开发： ``` dart pub get dart run flutter_guardian audit ``` ## 快速开始 在你的 Flutter 应用根目录下运行审计： ``` flutter_guardian audit ``` 如果你将其作为开发依赖添加，请运行： ``` dart run flutter_guardian audit ``` Flutter Guardian 会生成报告并以对 CI 友好的状态码退出： - `0` 表示未发现 error 级别的违规。 - `1` 表示发现了至少一个 error 级别的违规。 ## 策略文件 在你的 Flutter 应用根目录下创建一个 `guardian.yaml` 文件来自定义规则。 ``` security: require_obfuscation: true block_dotenv: true block_debug_logs: true block_hardcoded_secrets: true architecture: forbid_feature_to_feature_imports: true enforce_layer_direction: true feature_directory: features layers: - domain - data - presentation build: max_apk_size_mb: 50 max_aab_size_mb: 100 require_signing: true block_cleartext_traffic: true assets: max_image_size_kb: 1024 dependencies: warn_on_hosted_unpinned: true ``` 如果缺少 `guardian.yaml`，Flutter Guardian 将使用保守的默认设置。 ## 报告 默认情况下，Flutter Guardian 会生成： - `guardian-report.json` 用于 CI、仪表盘和自动化流程。 - `guardian-report.html` 供人工审查审计结果。 你可以选择自定义的输出路径： ``` flutter_guardian audit \ --json build/reports/guardian-report.json \ --html build/reports/guardian-report.html ``` ## CI 示例 GitHub Actions： ``` name: guardian on: pull_request: push: branches: [main] jobs: guardian: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: dart-lang/setup-dart@v1 - run: dart pub get - run: dart run flutter_guardian audit ``` 同样的命令也可以用于 GitLab、Jenkins、Azure Pipelines、Bitrise、Codemagic 以及其他 CI 系统。 ## 配置生成 Flutter Guardian 可以从 `.env`、YAML 或 JSON 文件生成编译时的 Dart 配置。 ``` flutter_guardian generate \ --from .env \ --out lib/generated/app_env.dart \ --class AppEnv ``` 除非传入 `--force` 参数，否则不会覆盖现有的输出文件。 ``` flutter_guardian generate \ --from .env \ --out lib/generated/app_env.dart \ --class AppEnv \ --force ``` ## 包 Flutter Guardian 被拆分成了多个小包： - `flutter_guardian`：主包和公共可执行文件。 - `guardian_cli`：命令行界面。 - `guardian_core`：共享的策略、扫描器和报告契约。 - `guardian_security`：安全分析器。 - `guardian_architecture`：架构边界分析器。 - `guardian_dependencies`：依赖健康度分析器。 - `guardian_assets`：资源分析器。 - `guardian_generator`：Dart 配置生成器。 - `guardian_reports`：JSON 和 HTML 报告生成器。 大多数用户只需要主包 `flutter_guardian` 即可。 ## 常见问题 ### Flutter Guardian 是一个 linter 吗？ 不是。Flutter Guardian 是一款发布审计工具。它通过检查项目结构、资源、依赖、构建文件和策略配置中与发布相关的风险，来补充 Dart 分析器、Flutter lints 和自定义 lint 规则的功能。 ### 它会在我的应用内部运行吗？ 不会。Flutter Guardian 不会在应用 runtime 运行。它作为一个命令行工具在发布前运行，通常是在开发者的机器上或 CI 环境中。 ### 它会修改我的源代码吗？ `audit` 命令只会扫描你的项目并写入报告文件。`generate` 命令仅会将 Dart 配置文件写入你提供的输出路径。 ### 我可以在没有 `guardian.yaml` 文件的情况下使用它吗？ 可以。如果找不到策略文件，Flutter Guardian 会使用保守的默认设置。当你需要更严格或更具项目针对性的规则时，可以添加 `guardian.yaml`。 ### 它能让我的 CI pipeline 失败吗？ 能。当 Flutter Guardian 发现 error 级别的违规时，它会以状态码 `1` 退出。这使得在 CI 中拦截不安全发布变得非常容易。 ### 它能替代人工审查吗？ 不能。它会自动执行重复性的检查，但不能替代代码审查、安全审查、QA（质量保证）或发布审批。 ### 哪些应用应该使用它？ Flutter Guardian 适用于生产环境的 Flutter 应用、设有发布门槛的团队、采用基于 feature 的架构的应用，以及希望在发布前进行可重复 CI 检查的项目。 ### 我可以只使用其中一个模块吗？ 可以。该仓库是模块化的，但推荐的起点是 `flutter_guardian` 主包，因为它将常用的审计流程整合在了一起。 ## 示例与文档 - [示例](https://github.com/itsmelaxman/flutter_guardian/blob/main/example/flutter_guardian_example.dart) - [用户指南](https://github.com/itsmelaxman/flutter_guardian/blob/main/doc/USER_GUIDE.md) - [测试指南](https://github.com/itsmelaxman/flutter_guardian/blob/main/doc/TESTING.md) - [策略示例](https://github.com/itsmelaxman/flutter_guardian/blob/main/doc/policy.example.yaml) ## 许可证 Apache License 2.0。详见 [LICENSE](LICENSE)。

标签：Flutter, 文档结构分析, 架构治理, 错误基检测, 静态代码分析