penkovsky_sa/cherrypick
1
0
Fork 0
mirror of https://github.com/pese-git/cherrypick.git synced 2026-01-24 05:25:19 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add detailed Russian full tutorial

Browse Source 
- Added doc/full_tutorial_ru.md with comprehensive usage and explanation of CherryPick DI
This commit is contained in:
Sergey Penkovsky
2025-06-21 15:20:30 +03:00
parent b5f6fff8d1
commit 24bb47f741
1 changed files with 415 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

415
doc/full_tutorial_ru.md Normal file
View File

@@ -0,0 +1,415 @@
# Полный гайд по CherryPick DI для Dart и Flutter: внедрение зависимостей с аннотациями и автоматической генерацией кода
**CherryPick** — это мощный инструмент для инъекции зависимостей в проектах на Dart и Flutter. Он предлагает современный подход с поддержкой генерации кода, асинхронных провайдеров, именованных и параметризируемых биндингов, а также field injection с использованием аннотаций.
> Инструменты:
> - [`cherrypick`](https://pub.dev/packages/cherrypick) — runtime DI core
> - [`cherrypick_annotations`](https://pub.dev/packages/cherrypick_annotations) — аннотации для DI
> - [`cherrypick_generator`](https://pub.dev/packages/cherrypick_generator) — генерация DI-кода
>
---
## Преимущества CherryPick по сравнению с другими DI-фреймворками
- 📦 Простой декларативный API для регистрации и разрешения зависимостей.
- ⚡️ Полная поддержка синхронных _и_ асинхронных регистраций.
- 🧩 DI через аннотации с автогенерацией кода, включая field injection.
- 🏷️ Именованные зависимости (named bindings).
- 🏭 Параметризация биндингов для runtime-использования фабрик.
- 🌲 Гибкая система Scope'ов для изоляции и иерархии зависимостей.
- 🕹️ Опциональное разрешение (tryResolve).
- 🐞 Ясные compile-time ошибки при неправильной аннотации или неверном DI-описании.
---
## Как работает CherryPick: основные концепции
### Регистрация зависимостей: биндинги
```dart
bind<MyService>().toProvide(() => MyServiceImpl());
bind<MyRepository>().toProvideAsync(() async => await initRepo());
bind<UserService>().toProvideWithParams((id) => UserService(id));
// Singleton
bind<MyApi>().toProvide(() => MyApi()).singleton();
// Зарегистрировать уже существующий объект
final config = AppConfig.dev();
bind<AppConfig>().toInstance(config);
// Зарегистрировать уже существующий Future/асинхронное значение
final setupFuture = loadEnvironment();
bind<Environment>().toInstanceAsync(setupFuture);
```
- **toProvide** — обычная синхронная фабрика.
- **toProvideAsync** — асинхронная фабрика (например, если нужно дожидаться Future).
- **toProvideWithParams / toProvideAsyncWithParams** — фабрики с параметрами.
- **toInstance** — регистрирует уже созданный экземпляр класса как зависимость.
- **toInstanceAsync** — регистрирует уже запущенный Future, как асинхронную зависимость.
### Именованные биндинги (Named)
Можно регистрировать несколько реализаций одного интерфейса под разными именами:
```dart
bind<ApiClient>().toProvide(() => ApiClientProd()).withName('prod');
bind<ApiClient>().toProvide(() => ApiClientMock()).withName('mock');
// Получение по имени:
final api = scope.resolve<ApiClient>(named: 'mock');
```
### Жизненный цикл: singleton
- `.singleton()` — один инстанс на всё время жизни Scope.
- По умолчанию каждый resolve создаёт новый объект.
### Параметрические биндинги
Позволяют создавать зависимости с runtime-параметрами — например, сервис для пользователя с ID:
```dart
bind<UserService>().toProvideWithParams((userId) => UserService(userId));
// Получение
final userService = scope.resolveWithParams<UserService>(params: '123');
```
---
## Управление Scope'ами: иерархия зависимостей
Для большинства бизнес-кейсов достаточно одного Scope (root), но CherryPick поддерживает создание вложенных Scope:
```dart
final rootScope = CherryPick.openRootScope();
final profileScope = rootScope.openSubScope('profile')
..installModules([ProfileModule()]);
```
- **Под-скоуп** может переопределять зависимости родителя.
- При разрешении сначала проверяется свой Scope, потом иерархия вверх.
## Работа с именованием и иерархией подскоупов (subscopes) в CherryPick
CherryPick поддерживает вложенные области видимости (scopes), где каждый scope может быть как "корневым", так и дочерним. Для доступа и управления иерархией используется понятие **scope name** (имя области видимости), а также удобные методы для открытия и закрытия скопов по строковым идентификаторам.
### Открытие subScope по имени
CherryPick использует строки с разделителями для поиска и построения дерева областей видимости. Например:
```dart
final subScope = CherryPick.openScope(scopeName: 'profile.settings');
```
- Здесь `'profile.settings'` означает, что сначала откроется подскоуп `profile` у rootScope, затем — подскоуп `settings` у `profile`.
- Разделитель по умолчанию — точка (`.`). Его можно изменить, указав `separator` аргументом.
**Пример с другим разделителем:**
```dart
final subScope = CherryPick.openScope(
scopeName: 'project>>dev>>api',
separator: '>>',
);
```
### Иерархия и доступ
Каждый уровень иерархии соответствует отдельному scope.
Это удобно для ограничения и локализации зависимостей, например:
- `main.profile` — зависимости только для профиля пользователя
- `main.profile.details` — ещё более "узкая" область видимости
### Закрытие подскоупов
Чтобы закрыть конкретный subScope, используйте тот же путь:
```dart
CherryPick.closeScope(scopeName: 'profile.settings');
```
- Если закрываете верхний скоуп (`profile`), все дочерние тоже будут очищены.
### Кратко о методах
| Метод | Описание |
|--------------------------|--------------------------------------------------------|
| `openRootScope()` | Открыть/получить корневой scope |
| `closeRootScope()` | Закрыть root scope, удалить все зависимости |
| `openScope(scopeName)` | Открыть scope(ы) по имени с иерархией (`'a.b.c'`) |
| `closeScope(scopeName)` | Закрыть указанный scope или subscope |
---
**Рекомендации:**
Используйте осмысленные имена и "точечную" нотацию для структурирования зон видимости в крупных приложениях — это повысит читаемость и позволит удобно управлять зависимостями на любых уровнях.
---
**Пример:**
```dart
// Откроет scopes по иерархии: app -> module -> page
final scope = CherryPick.openScope(scopeName: 'app.module.page');
// Закроет 'module' и все вложенные subscopes
CherryPick.closeScope(scopeName: 'app.module');
```
---
Это позволит масштабировать DI-подход CherryPick в приложениях любой сложности!
---
## Безопасное разрешение зависимостей
Если не уверены, что нужная зависимость есть, используйте tryResolve/tryResolveAsync:
```dart
final service = scope.tryResolve<OptionalService>(); // вернет null, если нет
```
---
## Внедрение зависимостей через аннотации и автогенерацию
CherryPick поддерживает DI через аннотации, что позволяет полностью избавиться от ручного внедрения зависимостей.
### Структура аннотаций
| Аннотация | Для чего | Где применяют |
| ------------- | ------------------------- | -------------------------------- |
| `@module` | DI-модуль | Классы |
| `@singleton` | Singleton | Методы класса |
| `@instance` | Новый объект | Методы класса |
| `@provide` | Провайдер | Методы (с DI params) |
| `@named` | Именованный биндинг | Аргумент метода/Аттрибуты класса |
| `@params` | Передача параметров | Аргумент провайдера |
| `@injectable` | Поддержка field injection | Классы |
| `@inject` | Автовнедрение | Аттрибуты класса |
| `@scope` | Scope/realm | Аттрибуты класса |
### Пример DI-модуля
```dart
import 'package:cherrypick_annotations/cherrypick_annotations.dart';
@module()
abstract class AppModule extends Module {
@singleton()
@provide()
ApiClient apiClient() => ApiClient();
@provide()
UserService userService(ApiClient api) => UserService(api);
@singleton()
@provide()
@named('mock')
ApiClient mockApiClient() => ApiClientMock();
}
```
- Методы, отмеченные `@provide`, становятся фабриками DI.
- Можно добавлять другие аннотации для уточнения типа биндинга, имени.
Сгенерированный код будет выглядеть вот таким образом:
```dart
class $AppModule extends AppModule {
@override
void builder(Scope currentScope) {
bind<ApiClient>().toProvide(() => apiClient()).singelton();
bind<UserService>().toProvide(() => userService(currentScope.resolve<ApiClient>()));
bind<ApiClient>().toProvide(() => mockApiClient()).withName('mock').singelton();
}
}
```
### Пример инъекций зависимостей через field injection
```dart
@injectable()
class ProfileBloc with _$ProfileBloc {
@inject()
late final AuthService auth;
@inject()
@named('admin')
late final UserService adminUser;
ProfileBloc() {
_inject(this); // injectFields — сгенерированный метод
}
}
```
- Генератор создаёт mixin (`_$ProfileBloc`), который автоматически резолвит и подставляет зависимости в поля класса.
- Аннотация `@named` привязывает конкретную реализацию по имени.
Сгенерированный код будет выглядеть вот таким образом:
```dart
mixin $ProfileBloc {
@override
void _inject(ProfileBloc instance) {
instance.auth = CherryPick.openRootScope().resolve<AuthService>();
instance.adminUser = CherryPick.openRootScope().resolve<UserService>(named: 'admin');
}
}
```
### Как это подключается
```dart
void main() async {
final scope = CherryPick.openRootScope();
scope.installModules([
$AppModule(),
]);
// DI через field injection
final bloc = ProfileBloc();
runApp(MyApp(bloc: bloc));
}
```
---
## Асинхронные зависимости
Для асинхронных провайдеров используйте `toProvideAsync`, а получать их — через `resolveAsync`:
```dart
bind<RemoteConfig>().toProvideAsync(() async => await RemoteConfig.load());
// Использование:
final config = await scope.resolveAsync<RemoteConfig>();
```
---
## Проверка и диагностика
- При неправильных аннотациях или ошибках DI появляется понятное compile-time сообщение.
- Ошибки биндингов выявляются при генерации кода. Это минимизирует runtime-ошибки и ускоряет разработку.
---
## Использование CherryPick с Flutter: пакет cherrypick_flutter
### Что это такое
[`cherrypick_flutter`](https://pub.dev/packages/cherrypick_flutter) — это пакет интеграции CherryPick DI с Flutter. Он предоставляет удобный виджет-провайдер `CherryPickProvider`, который размещается в вашем дереве виджетов и даёт доступ к root scope DI (и подскоупам) прямо из контекста.
### Ключевые возможности
- **Глобальный доступ к DI Scope:**
Через `CherryPickProvider` вы легко получаете доступ к rootScope и подскоупам из любого места дерева Flutter.
- **Интеграция с контекстом:**
Используйте `CherryPickProvider.of(context)` для доступа к DI внутри ваших виджетов.
### Пример использования
```dart
import 'package:flutter/material.dart';
import 'package:cherrypick_flutter/cherrypick_flutter.dart';
void main() {
runApp(
CherryPickProvider(
child: MyApp(),
),
);
}
class MyApp extends StatelessWidget {
@override
Widget build(BuildContext context) {
final rootScope = CherryPickProvider.of(context).openRootScope();
return MaterialApp(
home: Scaffold(
body: Center(
child: Text(
rootScope.resolve<AppService>().getStatus(),
),
),
),
);
}
}
```
- В этом примере `CherryPickProvider` оборачивает приложение и предоставляет доступ к DI scope через контекст.
- Вы можете создавать подскоупы, если нужно, например, для экранов или модулей:
`final subScope = CherryPickProvider.of(context).openSubScope(scopeName: "profileFeature");`
---
## CherryPick подходит не только для Flutter!
Вы можете использовать CherryPick и в Dart CLI, серверных проектах и микросервисах. Все основные возможности доступны и без Flutter.
---
## Пример проекта на CherryPick: полный путь
1. Установите зависимости:
```yaml
dependencies:
cherrypick: ^1.0.0
cherrypick_annotations: ^1.0.0
dev_dependencies:
build_runner: ^2.0.0
cherrypick_generator: ^1.0.0
```
2. Описываете свои модули с помощью аннотаций.
3. Для автоматической генерации DI кода используйте:
```shell
dart run build_runner build --delete-conflicting-outputs
```
4. Наслаждайтесь современным DI без боли!
---
## Заключение
**CherryPick** — это современное DI-решение для Dart и Flutter, сочетающее лаконичный API и расширенные возможности аннотирования и генерации кода. Гибкость Scopes, параметрические провайдеры, именованные биндинги и field-injection делают его особенно мощным как для небольших, так и для масштабных проектов.
**Полный список аннотаций и их предназначение:**
| Аннотация | Для чего | Где применяют |
| ------------- | ------------------------- | -------------------------------- |
| `@module` | DI-модуль | Классы |
| `@singleton` | Singleton | Методы класса |
| `@instance` | Новый объект | Методы класса |
| `@provide` | Провайдер | Методы (с DI params) |
| `@named` | Именованный биндинг | Аргумент метода/Аттрибуты класса |
| `@params` | Передача параметров | Аргумент провайдера |
| `@injectable` | Поддержка field injection | Классы |
| `@inject` | Автовнедрение | Аттрибуты класса |
| `@scope` | Scope/realm | Аттрибуты класса |
---
## Полезные ссылки
- [cherrypick](https://pub.dev/packages/cherrypick)
- [cherrypick_annotations](https://pub.dev/packages/cherrypick_annotations)
- [cherrypick_generator](https://pub.dev/packages/cherrypick_generator)
- [Исходники на GitHub](https://github.com/xddev/cherrypick)
---
🎉 Готовы внедрять зависимости по-взрослому? CherryPick — для вас!