Линтинг
cherrypick_lint — это плагин
анализатора, который подсвечивает неверное
использование API CherryPick в IDE и в dart analyze — без build_runner. На этой странице показано, что ловит каждое
правило (пример «плохо → хорошо»), и как подключить и настроить плагин.
Установка
Заголовок раздела «Установка»Плагин не является зависимостью проекта — analysis server резолвит его сам.
Достаточно назвать его в top-level секции plugins файла analysis_options.yaml:
plugins: cherrypick_lint: ^4.0.0Требуется Dart >=3.10 (Flutter >=3.38).
Пакет опубликован на pub.dev. Чтобы попробовать ещё не выпущенное изменение, укажите плагину путь к локальной копии репозитория:
plugins: cherrypick_lint: path: /absolute/path/to/cherrypick/cherrypick_lintСекция plugins принимает только три формы: версионный констрейнт, констрейнт
вместе с адресом hosted-сервера и путь.
После этого перезапустите Dart Analysis Server (в VS Code: Dart: Restart Analysis Server) —
плагины анализатора подхватываются только при старте. Дальше правила видны и в IDE, и в
dart analyze / flutter analyze, так что отдельного шага в CI не нужно.
С какими версиями cherrypick работает
Заголовок раздела «С какими версиями cherrypick работает»Плагин не зависит от cherrypick — он только читает ваш код, поэтому включить его можно на любой
версии. Различается другое: верно ли утверждение каждого правила для того API, который у вас
реально есть. Это проверено запуском плагина на файле, нарушающем все правила, и выполнением
каждого заявленного рантайм-поведения на cherrypick 2.2.0, 3.0.0, 3.0.2 и 4.0.0-dev.6.
cherrypick |
Какие правила применимы |
|---|---|
| 4.x | Все 15. |
| 3.x (проверено: 3.0.0, 3.0.2) | 14 из 15. Кроме avoid_extends_silent_observer: fast-path, о котором оно предупреждает, есть только в 4.x. Там правило стоит отключить. |
| 2.x и старше | Не поддерживается. closeScope и closeSubScope — синхронные void, а Scope.dispose() не существует, поэтому await-правила ругаются на вызовы, которым нечего ждать, а их quick fix даёт ошибку use_of_void_result. avoid_resolve_in_to_instance и avoid_singleton_on_provide_with_params описывают поведение, которого в 2.x нет. |
Берите ту же мажорную версию cherrypick_annotations и cherrypick_generator.
await-rules
Заголовок раздела «await-rules»Пропущенный await на закрытии скоупа означает, что ресурсы могут быть ещё не освобождены к
следующей строке кода. Оборачивание вызова в unawaited(...) считается осознанным
fire-and-forget и не вызывает срабатывание этих правил.
avoid_unawaited_close_sub_scope
Заголовок раздела «avoid_unawaited_close_sub_scope»// ❌ avoid_unawaited_close_sub_scopescope.closeSubScope('feature');
// ✅await scope.closeSubScope('feature');avoid_unawaited_close_scope
Заголовок раздела «avoid_unawaited_close_scope»// ❌ avoid_unawaited_close_scopeCherryPick.closeScope(scopeName: 'feature');
// ✅await CherryPick.closeScope(scopeName: 'feature');avoid_unawaited_scope_dispose
Заголовок раздела «avoid_unawaited_scope_dispose»// ❌ avoid_unawaited_scope_disposescope.dispose();
// ✅await scope.dispose();annotation-rules
Заголовок раздела «annotation-rules»Те же классы ошибок, на которых AnnotationValidator генератора бросает исключение во время
сборки — только теперь они видны в IDE ещё до запуска генератора.
module_requires_part_directive
Заголовок раздела «module_requires_part_directive»moduleBuilder — это PartBuilder, и part-директива задаёт файл, в который
пишется сгенерированный класс. Без неё сборка проходит успешно и не создаёт
ничего, предупредив лишь в логе build_runner.
// ❌ module_requires_part_directive — кодогенерация ничего не пишет@module()abstract class AppModule extends Module { @provide() Api api() => Api();}
// ✅part 'app_module.module.cherrypick.g.dart';
@module()abstract class AppModule extends Module { @provide() Api api() => Api();}module_must_extend_module
Заголовок раздела «module_must_extend_module»Генерируемый part — это final class $AppModule extends AppModule, тело
builder() в нём состоит из вызовов bind<T>(). Оба члена объявлены в
Module, поэтому без наследования генератор выдаёт part, который не
компилируется.
// ❌ module_must_extend_module — сгенерированный part не скомпилируется@module()abstract class AppModule { @provide() Api api() => Api();}
// ✅@module()abstract class AppModule extends Module { @provide() Api api() => Api();}module_must_be_abstract
Заголовок раздела «module_must_be_abstract»Сам генератор модификатор не проверяет, но конкретный @module-класс тупиковый
в любом случае: Module.builder абстрактный, поэтому без переопределения класс
отвергает Dart, а с переопределением генератор отвергает builder как метод
без @provide и @instance.
// ❌ module_must_be_abstract@module()class AppModule extends Module { @provide() Api api() => Api();}
// ✅@module()abstract class AppModule extends Module { @provide() Api api() => Api();}module_method_missing_binding
Заголовок раздела «module_method_missing_binding»Кодогенерация валидирует каждый неабстрактный метод класса, включая приватные и
static. Исключение — только геттеры и сеттеры: они не входят в
ClassElement.methods.
@module()abstract class AppModule extends Module { // ❌ module_method_missing_binding — нет @provide/@instance Api api() => Api();
// ❌ module_method_missing_binding — приватные тоже валидируются String _token() => 'secret';
// ✅ @provide() Api api() => Api();}inject_field_must_be_late_final
Заголовок раздела «inject_field_must_be_late_final»class ProfileScreen with _$ProfileScreen { // ❌ inject_field_must_be_late_final @inject() UserManager manager;
// ✅ @inject() late final UserManager manager;}named_value_must_not_be_empty
Заголовок раздела «named_value_must_not_be_empty»// ❌ named_value_must_not_be_empty@named('')ApiClient mockApi() => MockApiClient();
// ✅@named('mock')ApiClient mockApi() => MockApiClient();params_requires_provide
Заголовок раздела «params_requires_provide»@module()abstract class FeatureModule { // ❌ params_requires_provide @params() UserManager createManager(Map<String, dynamic> args) => ...;
// ✅ @provide() @params() UserManager createManager(Map<String, dynamic> args) => ...;}runtime-trap-rules
Заголовок раздела «runtime-trap-rules»Ловушки, которые проявляются только в рантайме — cherrypick_generator их не видит, потому что
это не неверное использование аннотаций.
avoid_extends_silent_observer
Заголовок раздела «avoid_extends_silent_observer»В cherrypick 4.x Scope содержит fast-path if (_observer is SilentCherryPickObserver), поэтому
наследник через extends молча не получает ни одного из 14 колбэков наблюдателя.
// ❌ avoid_extends_silent_observerclass MyObserver extends SilentCherryPickObserver {}
// ✅class MyObserver implements CherryPickObserver { // ... реализовать все 14 методов}avoid_redundant_singleton_on_instance (info)
Заголовок раздела «avoid_redundant_singleton_on_instance (info)»Согласно doc-комментарию Binding.singleton(), вызов после .toInstance()/.toInstanceAsync()
не имеет эффекта — переданное значение уже единственный константный экземпляр. .singleton()
осмыслен только после провайдера.
// ℹ️ avoid_redundant_singleton_on_instancebind<Api>().toInstance(ApiMock()).singleton();
// ✅bind<Api>().toInstance(ApiMock());// либо, если действительно нужно ленивое создание единственного экземпляра:bind<Api>().toProvide(() => ApiMock()).singleton();avoid_singleton_on_provide_with_params (info, без quick fix)
Заголовок раздела «avoid_singleton_on_provide_with_params (info, без quick fix)».singleton() после .toProvideWithParams()/.toProvideAsyncWithParams() превращает биндинг в
«master singleton»: параметры учитываются только при самом первом resolve<T>(params: ...), все
последующие resolve возвращают тот же закэшированный экземпляр независимо от params. Иногда это
именно то, что нужно, поэтому у правила нет quick fix — только напоминание проверить намерение.
// ℹ️ avoid_singleton_on_provide_with_paramsbind<Service>().toProvideWithParams((params) => Service(params)).singleton();
// нормально, если нужен новый экземпляр на каждый набор params — просто уберите .singleton()bind<Service>().toProvideWithParams((params) => Service(params));avoid_resolve_in_to_instance (warning, без quick fix)
Заголовок раздела «avoid_resolve_in_to_instance (warning, без quick fix)».toInstance(...)-биндинги внутри Module.builder применяются последовательно, поэтому вызов
scope.resolve<T>() (или resolveAsync/tryResolve/tryResolveAsync) для построения значения
может бросить Can't resolve dependency ..., если T регистрируется позже в том же builder’е.
Отложите резолв через .toProvide(() => ...) — он выполнится лениво, когда все соседние биндинги
уже зарегистрированы.
// ❌ avoid_resolve_in_to_instancebind<int>().toInstance(scope.resolve<String>().length);
// ✅bind<int>().toProvide(() => scope.resolve<String>().length);avoid_precomputed_value_in_provide (warning, без quick fix)
Заголовок раздела «avoid_precomputed_value_in_provide (warning, без quick fix)»Замыкание провайдера существует для того, чтобы выполняться заново при каждом resolve<T>() —
значение должно строиться внутри него. Если замыкание просто возвращает переменную, построенную
ранее в том же методе, значение на самом деле создаётся один раз, в момент Module.builder(), и
каждый resolve<T>() молча возвращает тот же экземпляр — непреднамеренный псевдо-singleton в обход
явного .singleton(). На .toInstance(...) это не влияет: он всегда конструирует значение сразу
независимо от того, откуда оно взялось, поэтому предвычисление для него безопасно.
// ❌ avoid_precomputed_value_in_providefinal api = ApiMock();bind<Api>().toProvide(() => api);
// ✅bind<Api>().toProvide(() => ApiMock());Отключение правила
Заголовок раздела «Отключение правила»plugins: cherrypick_lint: version: ^4.0.0 diagnostics: avoid_extends_silent_observer: falseОтдельную строку или файл можно исключить комментарием в форме <плагин>/<правило>:
// ignore: cherrypick_lint/avoid_unawaited_scope_disposescope.dispose();- README cherrypick_lint — полная таблица правил, совместимость, контрибьютинг
- Аннотации
- Пакеты и ресурсы