mirror of
https://github.com/pese-git/cherrypick.git
synced 2026-01-24 05:25:19 +00:00
feat(i18n): add initial Russian localization for documentation and site config
- Added full Russian translations for all main documentation sections () into . - Sections translated include: key features, installation, getting started, all core concepts, advanced features, API reference, FAQ, links, additional modules, contributing, and license. - Updated to ensure language switching is available and Russian locale is active. - Each Russian file preserves the structure and formatting of the original Markdown, with machine-aided draft translation for immediate use. - Lays the groundwork for UI language switching (en/ru) and enables further manual translation refinement and review.
This commit is contained in:
Sergey Penkovsky
@@ -0,0 +1,71 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
---
|
||||
|
||||
# Обнаружение циклических зависимостей
|
||||
|
||||
CherryPick может обнаруживать циклические зависимости в вашей DI-конфигурации, помогая избежать бесконечных циклов и сложных для отладки ошибок.
|
||||
|
||||
## Как использовать:
|
||||
|
||||
### 1. Включите обнаружение во время разработки
|
||||
|
||||
**Локально (в рамках одного скоупа):**
|
||||
```dart
|
||||
final scope = CherryPick.openSafeRootScope(); // Локальное обнаружение включено по умолчанию
|
||||
// или для существующего скоупа:
|
||||
scope.enableCycleDetection();
|
||||
```
|
||||
|
||||
**Глобально (между скоупами):**
|
||||
```dart
|
||||
CherryPick.enableGlobalCrossScopeCycleDetection();
|
||||
final rootScope = CherryPick.openGlobalSafeRootScope();
|
||||
```
|
||||
|
||||
### 2. Пример ошибки
|
||||
|
||||
Если вы объявите взаимозависимые сервисы:
|
||||
```dart
|
||||
class A { A(B b); }
|
||||
class B { B(A a); }
|
||||
|
||||
scope.installModules([
|
||||
Module((bind) {
|
||||
bind<A>().to((s) => A(s.resolve<B>()));
|
||||
bind<B>().to((s) => B(s.resolve<A>()));
|
||||
}),
|
||||
]);
|
||||
|
||||
scope.resolve<A>(); // выбросит CircularDependencyException
|
||||
```
|
||||
|
||||
### 3. Общая рекомендация
|
||||
|
||||
- **Включайте обнаружение** всегда в debug и тестовой среде для максимальной безопасности.
|
||||
- **Отключайте обнаружение** в production после завершения тестирования, ради производительности.
|
||||
|
||||
```dart
|
||||
import 'package:flutter/foundation.dart';
|
||||
|
||||
void main() {
|
||||
if (kDebugMode) {
|
||||
CherryPick.enableGlobalCycleDetection();
|
||||
CherryPick.enableGlobalCrossScopeCycleDetection();
|
||||
}
|
||||
runApp(MyApp());
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Отладка и обработка ошибок
|
||||
|
||||
При обнаружении будет выброшено исключение `CircularDependencyException` с цепочкой зависимостей:
|
||||
```dart
|
||||
try {
|
||||
scope.resolve<MyService>();
|
||||
} on CircularDependencyException catch (e) {
|
||||
print('Цепочка зависимостей: ${e.dependencyChain}');
|
||||
}
|
||||
```
|
||||
|
||||
**Подробнее:** смотрите [cycle_detection.ru.md](doc/cycle_detection.ru.md)
|
||||
@@ -0,0 +1,45 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
---
|
||||
|
||||
# Иерархические подскоупы
|
||||
|
||||
CherryPick поддерживает иерархическую структуру скоупов, что позволяет строить сложные и модульные графы зависимостей для профессиональных архитектур приложений. Каждый подскоуп наследует зависимости родителя и позволяет переопределять их локально.
|
||||
|
||||
## Основные моменты
|
||||
|
||||
- **Подскоупы** — дочерние скоупы, открываемые от любого существующего (в том числе root).
|
||||
- Зависимости подскоупа перекрывают родительские при разрешении.
|
||||
- Если зависимость не найдена в подскоупе, CherryPick ищет её выше по иерархии.
|
||||
- Подскоупы могут иметь собственные модули, "жизненный цикл", Disposable-объекты.
|
||||
- Можно делать вложенность любой глубины для фич, компонентов и т.д.
|
||||
|
||||
## Пример
|
||||
|
||||
```dart
|
||||
final rootScope = CherryPick.openRootScope();
|
||||
rootScope.installModules([AppModule()]);
|
||||
|
||||
// Открыть подскоуп для функции/страницы
|
||||
final userFeatureScope = rootScope.openSubScope('userFeature');
|
||||
userFeatureScope.installModules([UserFeatureModule()]);
|
||||
|
||||
// В userFeatureScope сперва ищет в своей области
|
||||
final userService = userFeatureScope.resolve<UserService>();
|
||||
|
||||
// Если не нашлось — идёт в rootScope
|
||||
final sharedService = userFeatureScope.resolve<SharedService>();
|
||||
|
||||
// Подскоупы можно вкладывать друг в друга сколь угодно глубоко
|
||||
final dialogScope = userFeatureScope.openSubScope('dialog');
|
||||
dialogScope.installModules([DialogModule()]);
|
||||
final dialogManager = dialogScope.resolve<DialogManager>();
|
||||
```
|
||||
|
||||
## Применение
|
||||
|
||||
- Модульная изоляция частей/экранов с собственными зависимостями
|
||||
- Переопределение сервисов для конкретных сценариев/навигации
|
||||
- Управление жизнью и освобождением ресурсов по группам
|
||||
|
||||
**Совет:** Всегда закрывайте подскоупы, когда они больше не нужны, чтобы освободить ресурсы.
|
||||
@@ -0,0 +1,62 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
---
|
||||
|
||||
# Логирование
|
||||
|
||||
CherryPick позволяет логировать все события и ошибки DI с помощью расширяемого observer-механизма.
|
||||
|
||||
## Кастомные Observer'ы
|
||||
|
||||
Вы можете передавать свою реализацию `CherryPickObserver` в root- или любой подскоуп.
|
||||
Это позволяет централизовать и настраивать логирование, направлять логи в консоль, файл, сторонние сервисы или системы как [Talker](https://pub.dev/packages/talker).
|
||||
|
||||
### Пример: вывод всех событий в консоль
|
||||
|
||||
```dart
|
||||
import 'package:cherrypick/cherrypick.dart';
|
||||
|
||||
void main() {
|
||||
// Встроенный PrintCherryPickObserver для консоли
|
||||
final observer = PrintCherryPickObserver();
|
||||
final scope = CherryPick.openRootScope(observer: observer);
|
||||
// Все события и ошибки DI будут выведены!
|
||||
}
|
||||
```
|
||||
|
||||
### Пример: расширенное логирование через Talker
|
||||
|
||||
Для более гибкого логирования или UI-оверлеев можно использовать observer наподобие [talker_cherrypick_logger](../talker_cherrypick_logger):
|
||||
|
||||
```dart
|
||||
import 'package:cherrypick/cherrypick.dart';
|
||||
import 'package:talker/talker.dart';
|
||||
import 'package:talker_cherrypick_logger/talker_cherrypick_logger.dart';
|
||||
|
||||
void main() {
|
||||
final talker = Talker();
|
||||
final observer = TalkerCherryPickObserver(talker);
|
||||
CherryPick.openRootScope(observer: observer);
|
||||
// Все события попадают в Talker!
|
||||
}
|
||||
```
|
||||
|
||||
## Поведение по умолчанию
|
||||
- По умолчанию логирование "тихое" (SilentCherryPickObserver) для production — нет вывода без observer'а.
|
||||
- Можно назначить observer для любого скоупа.
|
||||
|
||||
## Возможности Observer'а
|
||||
|
||||
- Регистрация зависимостей
|
||||
- Получение/создание/удаление экземпляров
|
||||
- Установка/удаление модулей
|
||||
- Открытие/закрытие скоупов
|
||||
- Кэш-хиты/мимо
|
||||
- Обнаружение циклов
|
||||
- Диагностика, предупреждения, ошибки
|
||||
|
||||
## Когда применять
|
||||
|
||||
- Подробное логирование в dev/test окружениях
|
||||
- Передача логов в основную систему/аналитику
|
||||
- Отладка и профилирование DI
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
---
|
||||
|
||||
# Улучшения производительности
|
||||
|
||||
> **Примечание по производительности:**
|
||||
> **Начиная с версии 3.0.0**, CherryPick использует Map-индексатор для поиска зависимостей. Это означает, что вызовы `resolve<T>()` и связанные методы работают за O(1) независимо от количества модулей/биндингов в скоупе. Ранее библиотека просматривала все модули/биндинги, что могло замедлять DI в крупных проектах.
|
||||
>
|
||||
> Эта оптимизация полностью внутренняя: интерфейс библиотеки и пользовательский код не изменились, но производительность заметно выросла на больших графах зависимостей.
|
||||
Reference in New Issue
Block a user