signals-lint

signals_lint 工具与规则

此技能涵盖在 signals.dart 生态系统中使用静态代码分析、自定义编译器警告诊断和自动快速修复。

---

🚀 激活与设置

确保项目中已启用插件，以开启 IDE 实时诊断和修复：

# pubspec.yaml
dev_dependencies:
  custom_lint: ^0.8.1
  signals_lint: ^7.0.0

# analysis_options.yaml
analyzer:
  plugins:
    - custom_lint

---

🛡️ Lint 规则参考

1. signals_avoid_create_in_build_method

标记在 Flutter build 方法中创建信号或计算变量的情况。

• 问题：在构建过程中创建状态，会导致每次重建时状态都重置。
• 解决方案：将其移到类字段中，或在状态生命周期钩子中初始化。

---

2. signals_avoid_deprecated_watch_extension

标记使用已弃用的 BuildContext.watch() 和 BuildContext.unwatch() 扩展的情况。

• 问题：Watch 扩展可能导致较大的有状态组件生命周期开销。
• 解决方案：使用局部的 SignalBuilder，或继承 SignalWidget/SignalStatefulWidget。

---

3. signals_avoid_deprecated_signals_mixin

标记在 StatefulWidget 状态中使用已弃用的 with SignalsMixin 混入的情况。

• 问题：会不必要地继承有状态组件跟踪钩子。
• 解决方案：改为继承 SignalStatefulWidget。

---

4. signals_prefer_named_builder

要求在 SignalBuilder 和 Watch 元素中使用命名的 builder: 回调，而不是位置参数。

• 原因：确保 API 参数规范统一且易于阅读。

---

5. signals_prefer_unified_options

标记直接传入的创建器配置参数（例如 autoDispose: true）。

• 解决方案：将配置属性放入统一的选项类中（例如 options: SignalOptions(autoDispose: true)）。

---

💡 IDE 自动代码辅助（快速修复）

在 IDE 中将光标放在相关类名或组件实例化处，即可通过快速修复菜单（Cmd+. 或 Alt+Enter）查看以下自动辅助：

1. WrapWithSignalBuilder：将任意组件表达式包装在 SignalBuilder(builder: (context) => ...) 中。
2. ConvertStatelessToSignalWidget：即时将标准 StatelessWidget 重构为 SignalWidget。
3. ConvertStatefulToSignalStatefulWidget：将标准 StatefulWidget 重构为 SignalStatefulWidget。
4. MigrateSignalsMixinToSignalStatefulWidget：移除旧版 SignalsMixin，并将类结构转换为 SignalStatefulWidget。
5. MigrateWatchToSignalBuilder：将旧版 Watch(...) 实例转换为简洁的 SignalBuilder 组件。