penkovsky_sa/cherrypick
1
0
Fork 0
mirror of https://github.com/pese-git/cherrypick.git synced 2026-01-23 21:13:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: add important warnings about toInstance limitations and singleton behavior with params

Browse Source 
- Add detailed warning about toInstance usage restrictions in module builders
- Explain singleton behavior with parameterized providers
- Clarify singleton() usage with toInstance() calls
- Update both English and Russian documentation versions
This commit is contained in:
Sergey Penkovsky
2025-09-08 14:07:48 +03:00
parent 7f5f5c4064
commit ce2e770cbe
3 changed files with 168 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

100
website/i18n/ru/docusaurus-plugin-content-docs/current/core-concepts/binding.md
View File

@@ -12,30 +12,96 @@ sidebar_position: 1
* Именованные экземпляры для получения по строковому ключу
* Необязательное управление жизненным циклом синглтона
## Пример
#### Пример
```dart
// Прямое создание экземпляра
Binding<String>().toInstance("Hello world");
void builder(Scope scope) {
// Прямое предоставление экземпляра
bind<String>().toInstance("Hello world");
// Асинхронное создание экземпляра
Binding<String>().toInstanceAsync(Future.value("Hello world"));
// Асинхронное предоставление экземпляра
bind<String>().toInstanceAsync(Future.value("Hello world"));
// Ленивое создание экземпляра через фабрику (sync)
Binding<String>().toProvide(() => "Hello world");
// Ленивое создание синхронного экземпляра через фабрику
bind<String>().toProvide(() => "Hello world");
// Ленивое создание экземпляра через фабрику (async)
Binding<String>().toProvideAsync(() async => "Hello async world");
// Ленивое создание асинхронного экземпляра через фабрику
bind<String>().toProvideAsync(() async => "Hello async world");
// Экземпляр с параметрами (sync)
Binding<String>().toProvideWithParams((params) => "Hello $params");
// Предоставление экземпляра с динамическими параметрами (синхронно)
bind<String>().toProvideWithParams((params) => "Hello $params");
// Экземпляр с параметрами (async)
Binding<String>().toProvideAsyncWithParams((params) async => "Hello $params");
// Предоставление экземпляра с динамическими параметрами (асинхронно)
bind<String>().toProvideAsyncWithParams((params) async => "Hello $params");
// Именованный экземпляр для получения по имени
Binding<String>().toProvide(() => "Hello world").withName("my_string");
// Именованный экземпляр для получения по имени
bind<String>().toProvide(() => "Hello world").withName("my_string");
// Синглтон (один экземпляр внутри скоупа)
Binding<String>().toProvide(() => "Hello world").singleton();
// Пометить как синглтон (только один экземпляр в пределах скоупа)
bind<String>().toProvide(() => "Hello world").singleton();
}
```
> ⚠️ **Важное примечание об использовании `toInstance` в `builder` модуля:**
>
> Если вы регистрируете цепочку зависимостей через `toInstance` внутри `builder` модуля, **не вызывайте** `scope.resolve<T>()` для типов, которые также регистрируются в том же builder — в момент их регистрации.
>
> CherryPick инициализирует все привязки в builder последовательно. Зависимости, зарегистрированные ранее, еще не доступны для `resolve` в рамках того же выполнения builder. Попытка разрешить только что зарегистрированные типы приведет к ошибке (`Can't resolve dependency ...`).
>
> **Как делать правильно:**
> Вручную создайте полную цепочку зависимостей перед вызовом `toInstance`:
>
> ```dart
> void builder(Scope scope) {
> final a = A();
> final b = B(a);
> final c = C(b);
> bind<A>().toInstance(a);
> bind<B>().toInstance(b);
> bind<C>().toInstance(c);
> }
> ```
>
> **Неправильно:**
> ```dart
> void builder(Scope scope) {
> bind<A>().toInstance(A());
> // Ошибка! В этот момент A еще не зарегистрирован.
> bind<B>().toInstance(B(scope.resolve<A>()));
> }
> ```
>
> **Неправильно:**
> ```dart
> void builder(Scope scope) {
> bind<A>().toProvide(() => A());
> // Ошибка! В этот момент A еще не зарегистрирован.
> bind<B>().toInstance(B(scope.resolve<A>()));
> }
> ```
>
> **Примечание:** Это ограничение применяется **только** к `toInstance`. С `toProvide`/`toProvideAsync` и подобными провайдерами вы можете безопасно использовать `scope.resolve<T>()` внутри builder.
> ⚠️ **Особое примечание относительно `.singleton()` с `toProvideWithParams()` / `toProvideAsyncWithParams()`:**
>
> Если вы объявляете привязку с помощью `.toProvideWithParams(...)` (или его асинхронного варианта) и затем добавляете `.singleton()`, только **самый первый** вызов `resolve<T>(params: ...)` использует свои параметры; каждый последующий вызов (независимо от параметров) вернет тот же (кешированный) экземпляр.
>
> **Пример:**
> ```dart
> bind<Service>().toProvideWithParams((params) => Service(params)).singleton();
> final a = scope.resolve<Service>(params: 1); // создает Service(1)
> final b = scope.resolve<Service>(params: 2); // возвращает Service(1)
> print(identical(a, b)); // true
> ```
>
> Используйте этот паттерн только когда хотите получить "главный" синглтон. Если вы ожидаете новый экземпляр для каждого набора параметров, **не используйте** `.singleton()` с параметризованными провайдерами.
> ℹ️ **Примечание о `.singleton()` и `.toInstance()`:**
>
> Вызов `.singleton()` после `.toInstance()` **не** меняет поведение привязки: объект, переданный с `toInstance()`, уже является единым, постоянным экземпляром, который всегда будет возвращаться при каждом resolve.
>
> Не обязательно использовать `.singleton()` с существующим объектом — этот вызов не имеет эффекта.
>
> `.singleton()` имеет смысл только с провайдерами (такими как `toProvide`/`toProvideAsync`), чтобы гарантировать создание только одного экземпляра фабрикой.