flutter-best-practices: Скилл для Flutter лучших практик

```markdown --- name: flutter-best-practices description: Flutter 开发最佳实践指南，涵盖架构、依赖管理、UI 开发、平台配置。当用户提到"最佳实践"、"架构"、"Riverpod"、"GoRouter"、"Dio"、"主题"、"响应式"、"无障碍"时使用此 skill。 --- # Flutter Best Practices Обеспечьте соответствие Flutter кода архитектурным соглашениям проекта и лучшим практикам. ## 1. Среда и инструменты | Параметр | Требование | |--------|------| | Канал Flutter | stable | | Dart SDK | `>=3.7.0 <4.0.0` | | Интернационализация | `flutter gen-l10n` (выполнять после изменения arb) | | Очистка сборки | `flutter clean && rm -rf build/` | ## 2. Управление зависимостями ### Выбор основных зависимостей | Функция | Рекомендуемая библиотека | Назначение | |------|--------|------| | Управление состоянием | `flutter_riverpod` 3.x | Provider + StateNotifier | | Маршрутизация | `go_router` 17.x | Декларативная навигация | | Сеть | `dio` 5.x | HTTP клиент + перехватчики | | Легкое хранилище | `shared_preferences` | Нечувствительные флаги | | Безопасное хранилище | `flutter_secure_storage` | Кредиенты/секреты | | Структурированное кэширование | `hive` + `hive_flutter` | Оффлайн данные | ### Принципы управления зависимостями ```bash # Проверка устаревших зависимостей flutter pub outdated # Консервативное обновление (patch уровень) flutter pub upgrade --major-versions # Использовать с осторожностью ``` - Используйте caret ограничения (`^x.y.z`) для получения исправлений patch. - Переменные окружения передаются через `--dart-define`, а не жестко закодированы. ## 3. Архитектурные соглашения ### Структура каталогов ``` lib/ ├── app/ # Корневой модуль │ ├── di.dart # Основной Provider сервисов │ └── router.dart # Конфигурация GoRouter ├── core/ # Инфраструктура (не импортируется в features) │ ├── config/ # Конфигурация окружения │ ├── error/ # Failure + Result<T> │ ├── network/ # Dio + перехватчики │ ├── storage/ # Обертка для хранения │ ├── theme/ # Определение темы │ └── widgets/ # Общие компоненты └── features/<name>/ # Модуль функциональности ├── presentation/ # UI + Provider ├── domain/ # Сущности + интерфейсы (чистый Dart) └── data/ # Источники данных + реализации ``` ### Правила уровней - `core/` **запрещено** импортировать `features/`. - `domain/` **запрещено** импортировать `package:flutter`. - Коммуникация между Feature осуществляется через `core/services/` или общие интерфейсы. ### Dependency Injection (Внедрение зависимостей) ```dart // app/di.dart - Основные сервисы final dioClientProvider = Provider<DioClient>((ref) => DioClient()); // features/xxx/presentation/providers/ - Provider для функциональности final xxxControllerProvider = StateNotifierProvider<XxxController, XxxState>(...); ``` ### Конфигурация маршрутизации ```dart // features/xxx/presentation/routes.dart class XxxRoutes { static const xxx = '/xxx'; } List<GoRoute> buildXxxRoutes() => [ GoRoute(path: XxxRoutes.xxx, builder: (_, __) => const XxxPage()), ]; // app/router.dart final routerProvider = Provider<GoRouter>((ref) => GoRouter( routes: [...buildXxxRoutes(), ...buildYyyRoutes()], )); ``` ### Обработка ошибок ```dart // Используйте Result<T> вместо try-catch Future<Result<User>> getUser(String id) async { try { final response = await dio.get('/users/$id'); return Success(User.fromJson(response.data)); } on DioException catch (e) { return Err(NetworkFailure(e.message)); } } // UI уровень обработки result.when( success: (user) => showUser(user), failure: (failure) => showError(failure.message), ); ``` ## 4. Лучшие практики UI ### Дизайн виджетов | Принцип | Описание | |------|------| | Маленькие и компонуемые | Разделение на Page + листовые компоненты | | Без состояния (Stateless) | Состояние помещается в Riverpod, а не в StatefulWidget | | Константные конструкторы (const) | Уменьшение количества ненужных rebuild | | Ссылка на тему | `Theme.of(context)` вместо жесткого кодирования | ### Спецификации стиля ```dart // ✅ Правильно: получение из темы final color = Theme.of(context).colorScheme.primary; final textStyle = Theme.of(context).textTheme.titleLarge; // ❌ Неправильно: жесткое кодирование final color = Color(0xFF2196F3); final textStyle = TextStyle(fontSize: 22); ``` ### Адаптивный макет ```dart // Используйте LayoutBuilder для адаптации к разным экранам LayoutBuilder( builder: (context, constraints) { if (constraints.maxWidth > 600) { return TabletLayout(); } return MobileLayout(); }, ); ``` ### Доступность (Accessibility) | Требование | Реализация | |------|------| | Область нажатия | ≥48 логических пикселей | | Семантика иконок | Добавление тегов `Semantics` | | Масштабирование шрифта | Учитывать `MediaQuery.textScaleFactor` | ## 5. Конфигурация платформы ### Android ```xml <!-- AndroidManifest.xml - требуется flutter_secure_storage --> <uses-permission android:name="android.permission.USE_BIOMETRIC" /> ``` - Версия Java: 17 (конфигурация CI) - Gradle lint: `./gradlew lint` ### iOS ```bash # Локальная разработка cd ios && pod install && open Runner.xcworkspace # Проблемы CocoaPods pod repo update ``` ## 6. Чек-лист рабочего процесса ```bash # Процесс разработки flutter pub get # ... Реализация функциональности ... dart format --set-exit-if-changed . flutter analyze --fatal-infos flutter gen-l10n # Если есть изменения в интернационализации flutter test --coverage ``` ## 7. Справочная документация | Библиотека | Документация | |---|------| | Flutter SDK | https://docs.flutter.dev | | flutter_riverpod | https://riverpod.dev/docs/getting_started | | go_router | https://pub.dev/documentation/go_router/latest/ | | dio | https://pub.dev/documentation/dio/latest/ | | hive | https://docs.hivedb.dev/#/ | | flutter_secure_storage | https://pub.dev/documentation/flutter_secure_storage/latest/ | ## Сценарии использования 1. **Создание новой функциональности**: Следовать структуре presentation/domain/data. 2. **Добавление зависимости**: Предпочтительно использовать выбранные библиотеки. 3. **Разработка UI**: Без состояния + const + ссылка на тему. 4. **Обработка ошибок**: Использовать Result<T> + Failure. 5. **Адаптация платформы**: Проверить конфигурацию Manifest/Podfile. ```