Публичный интерфейс библиотеки autumn-data

Аннотации

• МетодЗапроса
• ХранилищеСущностей

Классы

• ЗаготовкаОсеньДата
• НапильникХранилищеСущностей

---

МетодЗапроса

Аннотация, помечающая метод хранилища сущностей, для которого необходимо сгенерировать тело метода с выполнением запроса к базе данных на основании имени метода. Для работы аннотации класс должен быть помечен аннотацией &ХранилищеСущностей.

Синтаксис

&МетодЗапроса
Функция ИмяМетода(Параметры...) Экспорт
    Возврат Неопределено;
КонецФункции

Описание

Аннотация &МетодЗапроса позволяет автоматически генерировать реализацию методов запросов на основе их имен. Библиотека анализирует имя метода и создает соответствующий код для выполнения запроса к базе данных.

Правила именования методов

Имя метода должно следовать определенной структуре:

[Режим][Ограничения][Условия][Сортировка]

Где:

• Режим - Получить или ПолучитьОдно
• Ограничения - Первые, СоСмещением (опционально)
• Условия - По[Поле][ВидСравнения] (опционально)
• Сортировка - УпорядочитьПо[Поле][Направление] (опционально)

Поддерживаемые токены

Режимы поиска

• ПолучитьОдно - возвращает один объект
• Получить - возвращает коллекцию объектов

Ограничения

• Первые - ограничивает количество записей
• СоСмещением - пропускает записи с начала

Виды сравнения

• Равно (по умолчанию)
• НеРавно
• Больше
• БольшеИлиРавно
• Меньше
• МеньшеИлиРавно
• В - значение в списке
• НеВ - значение не в списке

Направления сортировки

• Возр (по умолчанию)
• Убыв

Логические операторы

• И - логическое И между условиями

Примеры

Простые запросы

// Найти по ID
&МетодЗапроса
Функция ПолучитьОдноПоИдентификаторРавно(Идентификатор) Экспорт
    Возврат Неопределено;
КонецФункции

Сложные условия

// Множественные условия
&МетодЗапроса
Функция ПолучитьПоИмяРавноИВозрастБольше(Имя, Возраст) Экспорт
    Возврат Неопределено;
КонецФункции

// С сортировкой
&МетодЗапроса
Функция ПолучитьПоАктивенРавноУпорядочитьПоДатаСозданияУбыв(Активен) Экспорт
    Возврат Неопределено;
КонецФункции

С ограничениями

// Пагинация
&МетодЗапроса
Функция ПолучитьПервыеСоСмещениемПоВозрастБольшеИлиРавноУпорядочитьПоИмениВозр(
    Первые, 
    Смещение, 
    Возраст
) Экспорт
    Возврат Неопределено;
КонецФункции

Генерируемый код

Для метода:

&МетодЗапроса
Функция ПолучитьПоИмяРавноИВозрастБольше(Имя, Возраст) Экспорт
    Возврат Неопределено;
КонецФункции

Будет сгенерирован код:

Функция ПолучитьПоИмениРавноИВозрастБольше(Имя, Возраст) Экспорт
    ОпцииПоиска = Новый ОпцииПоиска();
    ОпцииПоиска.Отбор("Имя", ВидСравнения.Равно, Имя);
    ОпцииПоиска.Отбор("Возраст", ВидСравнения.Больше, Возраст);
    Возврат ХранилищеСущностей.Получить(ОпцииПоиска);
КонецФункции

Требования

• Класс должен быть помечен аннотацией &ХранилищеСущностей
• Метод должен быть помечен аннотацией &МетодЗапроса
• Параметры метода должны соответствовать порядку их использования в имени метода

Ограничения

• Не все комбинации токенов поддерживаются
• Сложные запросы лучше реализовывать вручную с использованием ОпцииПоиска
• Регистр имен полей должен точно совпадать с определением в сущности

См. также

• ХранилищеСущностей
• Методы запросов

---

ХранилищеСущностей

Аннотация, помечающая класс как хранилище (репозиторий) сущностей, предоставляющий методы для работы с объектами определенного типа в базе данных. Необходима для использования в связке с аннотацией &МетодЗапроса.

Синтаксис

&ХранилищеСущностей(ИмяТипаСущности, ИсточникДанных = "")
Процедура ПриСозданииОбъекта()
КонецПроцедуры

Параметры

ИмяТипаСущности

Тип: Строка

Имя типа сущности, для которой создается хранилище.

ИсточникДанных

Тип: Строка (опционально)

Имя источника данных, который будет использоваться для данной сущности. Может быть не указан, если используется единственный источник данных.

Описание

Аннотация &ХранилищеСущностей превращает обычный класс в репозиторий для работы с сущностями определенного типа. Класс автоматически получает:

• Наследование от базового класса ХранилищеСущностей из библиотеки entity плюс расширение собственными методами
• Доступ к базовому хранилищу сущностей поле, помеченное аннотацией &Родитель
• Возможность определения "магических" методов с аннотацией &МетодЗапроса для автоматической генерации запросов к базе данных
• Интеграцию с контейнером зависимостей autumn в роли желудя

Структура класса

// В поле лежит ссылка на типизированное ХранилищеСущностей библиотеки entity
&Родитель
Перем ХранилищеСущностей;

// Методы, для которых будет сгенерирована реализация на основании имени метода
&МетодЗапроса
Функция ПолучитьПоИдентификаторРавно(Идентификатор) Экспорт
    Возврат Неопределено;
КонецФункции

// Собственные методы
Функция СоздатьСоЗначениямиПоУмолчанию(Имя) Экспорт
    НовыйОбъект = ХранилищеСущностей.СоздатьЭлемент();
    НовыйОбъект.Имя = Имя;
    НовыйОбъект.ДатаСоздания = ТекущаяДата();
    НовыйОбъект.Активен = Истина;
    
    Возврат НовыйОбъект;
КонецФункции

&ХранилищеСущностей("ТипСущности")
Процедура ПриСозданииОбъекта()
КонецПроцедуры

Примеры

Простое хранилище с методом поиска

&МетодЗапроса
Функция НайтиПоИмениРавно(Имя) Экспорт
    Возврат Неопределено;
КонецФункции

&ХранилищеСущностей("Пользователь")
Процедура ПриСозданииОбъекта()
КонецПроцедуры

Хранилище с указанием источника данных

&МетодЗапроса
Функция НайтиПоНомерРавно(Номер) Экспорт
    Возврат Неопределено;
КонецФункции

&ХранилищеСущностей("Документ", ИсточникДанных = "Архивный")
Процедура ПриСозданииОбъекта()
КонецПроцедуры

Хранилище собственной логикой

Классы/МоеХранилищеПользователей.os

&Родитель
Перем ХранилищеСущностей;

&МетодЗапроса
Функция НайтиПоEmailРавно(Email) Экспорт
    Возврат Неопределено;
КонецФункции

Функция СоздатьПользователяСАвтогенерацией(Имя, Email) Экспорт
    // Проверяем уникальность email
    СуществующийПользователь = НайтиПоEmailРавно(Email);
    Если СуществующийПользователь <> Неопределено Тогда
        ВызватьИсключение "Пользователь с таким email уже существует";
    КонецЕсли;
    
    // Создаем нового пользователя
    НовыйПользователь = ХранилищеСущностей.СоздатьЭлемент();
    НовыйПользователь.Имя = Имя;
    НовыйПользователь.Email = Email;
    НовыйПользователь.Идентификатор = Новый УникальныйИдентификатор();
    НовыйПользователь.ДатаСоздания = ТекущаяДата();
    НовыйПользователь.Активен = Истина;

    НовыйПользователь.Сохранить();
    
    Возврат НовыйПользователь;
КонецФункции

Функция ПолучитьСтатистикуПользователей() Экспорт
    ОбщееКоличество = ХранилищеСущностей.Получить().Количество();
    
    ОпцииАктивных = Новый ОпцииПоиска()
        .Отбор("Активен", ВидСравнения.Равно, Истина);
    КоличествоАктивных = ХранилищеСущностей.Получить(ОпцииАктивных).Количество();
    
    Статистика = Новый Структура();
    Статистика.Вставить("Общее", ОбщееКоличество);
    Статистика.Вставить("Активные", КоличествоАктивных);
    Статистика.Вставить("Неактивные", ОбщееКоличество - КоличествоАктивных);
    
    Возврат Статистика;
КонецФункции

&ХранилищеСущностей("Пользователь")
Процедура ПриСозданииОбъекта()
КонецПроцедуры

Регистрация в контейнере

Хранилища автоматически регистрируются в контейнере зависимостей под именами:

• Без указания источника данных: ХранилищеСущностей[ИмяТипаСущности]
• С указанием источника данных: ХранилищеСущности[ИсточникДанных][ИмяТипаСущности]

Например:

// Для &ХранилищеСущностей("Пользователь")
ХранилищеПользователей = Поделка.НайтиЖелудь("ХранилищеСущностейПользователь");

// Для &ХранилищеСущностей("Документ", ИсточникДанных = "Архивный")
ХранилищеДокументов = Поделка.НайтиЖелудь("ХранилищеСущностейАрхивныйДокумент");

Кроме собственного имени желудь получает прозвище ХранилищеСущностей — то же, что и у хранилищ, которые создаются для каждого типа сущности автоматически. По нему забираются все хранилища приложения сразу:

Хранилища = Поделка.НайтиЖелуди("ХранилищеСущностей");

Доступные методы базового хранилища

Все методы базового Хранилища сущностей из entity доступны для вызова из-вне:

• СоздатьЭлемент() - создание нового объекта с функциональностью Active record
• Сохранить(Сущность) - сохранение объекта в базе данных
• Получить(ОпцииПоиска) - получение коллекции объектов
• ПолучитьОдно(ОпцииПоиска) - получение одного объекта
• Удалить(Сущность) - удаление объекта
• НачатьТранзакцию() - открытие транзакции
• ЗафиксироватьТранзакцию() - фиксация транзакции
• ОтменитьТранзакцию() - откат транзакции
• ВыполнитьСКоннектором(Алгоритм, Контекст) и ВычислитьСКоннектором(Алгоритм, Контекст) - выполнение алгоритма на соединении, выданном источником данных
• ПолучитьОбъектМодели() - получение объекта модели для работы с данными
• Закрыть - закрытие хранилища (не рекомендуется к вызову напрямую)

ХранилищеСущностей = Поделка.НайтиЖелудь("МоеХранилищеПользователей");

// Доступны как базовые методы хранилища:
НовыйПользователь = ХранилищеСущностей.СоздатьЭлемент();
НовыйПользователь.Имя = "Иван";

ХранилищеСущностей.Сохранить(НовыйПользователь);

// Так и собственные
Пользватель = ХранилищеСущностей.СоздатьПользователяСАвтогенерацией("Иван", "test@example.com");

При необходимости, собственное &ХранилищеСущностей может получить доступ к базовому хранилищу сущностей от entity серез через поле, помеченное аннотацией &Родитель.

См. также

• МетодЗапроса
• ЗаготовкаОсеньДата
• Настройка источников данных

---

ЗаготовкаОсеньДата

Основной класс-конфигуратор библиотеки autumn-data, отвечающий за инициализацию источников данных, менеджеров сущностей и хранилищ в контейнере зависимостей autumn.

Назначение

Класс ЗаготовкаОсеньДата выполняет следующие функции:

1. Инициализирует источники данных на основе конфигурации
2. Создает менеджеры сущностей для каждого источника данных
3. Регистрирует хранилища сущностей в контейнере зависимостей
4. Настраивает связи между компонентами системы

Аннотации

&Заготовка

Класс помечен аннотацией &Заготовка, что означает его использование для конфигурации контейнера зависимостей в рамках autumn framework.

Конструктор

Процедура ПриСозданииОбъекта(&Деталька("data.ИсточникиДанных") НастройкиИсточниковДанных)

Параметры

НастройкиИсточниковДанных

Тип: Соответствие или Массив

Конфигурация источников данных. Может быть передана в двух форматах:

Как соответствие (один источник без имени):

Новый Соответствие()
    .Вставить("ТипКоннектора", "КоннекторSqlite")
    .Вставить("СтрокаСоединения", "Data Source=database.db")

Как массив (множественные источники):

Новый Массив()
    .Добавить(Новый Соответствие()
        .Вставить("Имя", "Основной")
        .Вставить("ТипКоннектора", "КоннекторSqlite")
        .Вставить("СтрокаСоединения", "Data Source=main.db")
    )
    .Добавить(Новый Соответствие()
        .Вставить("Имя", "Дополнительный")
        .Вставить("ТипКоннектора", "КоннекторPostgreSQL")
        .Вставить("СтрокаСоединения", "Host=localhost;Database=archive")
    )

Структура настроек источника данных

Каждый источник данных описывается соответствием со следующими ключами:

Обязательные параметры

• ТипКоннектора - строка с именем класса коннектора (например, "КоннекторSqlite")

Опциональные параметры

• Имя - уникальное имя источника данных (обязательно для множественных источников)
• СтрокаСоединения - строка подключения к базе данных (по умолчанию пустая строка)
• ПараметрыКоннектора - массив дополнительных параметров для коннектора (по умолчанию пустой массив)
• РазмерПула - предел одновременных соединений с БД (по умолчанию 10; 0 отключает переиспользование: каждое обращение открывает свое соединение и закрывает его по завершении)

Процесс инициализации

1. Инициализация источников данных

Метод ИнициализироватьИсточникиДанных() создает объекты источников данных на основе переданной конфигурации.

2. Определение типов сущностей

Система автоматически находит все пользовательские типы, содержащие методы с аннотацией &Сущность.

3. Регистрация компонентов

Для каждого источника данных регистрируются:

• ИсточникДанных - объект источника данных
• МенеджерСущностей - менеджер для работы с сущностями
• ХранилищеСущностей - хранилища для каждого типа сущности

4. Регистрация наблюдателей источника данных

Завязь менеджера получает все желуди с прозвищем НаблюдательИсточникаДанных (&Пластилин("НаблюдательИсточникаДанных", Тип = "Массив")) и регистрирует каждый на источнике данных методом ИсточникДанных.ДобавитьНаблюдателя до создания менеджера, поэтому наблюдатели видят и создание таблиц. Менеджер создается из источника: Новый МенеджерСущностей(ИсточникДанных).

Именование компонентов в контейнере

Источники данных

• С именем: "ИсточникДанных" + ИмяИсточника
• Без имени: "ИсточникДанных"

Менеджеры сущностей

• С именем: "МенеджерСущностей" + ИмяИсточника
• Без имени: "МенеджерСущностей"

Хранилища сущностей

• С именем источника: "ХранилищеСущностей" + ИмяИсточника + ИмяТипаСущности
• Без имени источника: "ХранилищеСущностей" + ИмяТипаСущности

Прозвища

Дополнительно регистрируются прозвища для удобного доступа:

• "ИсточникДанных" - для основного источника
• "МенеджерСущностей" - для основного менеджера
• "ХранилищеСущностей" - для основного хранилища
• "ХранилищеСущностей" + ИмяИсточника - для хранилищ конкретного источника

Примеры использования

Простая конфигурация

// В конфигурации приложения
СоветДругогоМастера = Новый СоветДругогоМастера()
    .Деталька("data.ИсточникиДанных", Новый Соответствие()
        .Вставить("ТипКоннектора", "КоннекторSqlite")
        .Вставить("СтрокаСоединения", "Data Source=app.db")
    );

Поделка = Новый Поделка(СоветДругогоМастера);
Поделка.ЗапуститьПриложение();

// Получение компонентов
ИсточникДанных = Поделка.НайтиЖелудь("ИсточникДанных");
МенеджерСущностей = Поделка.НайтиЖелудь("МенеджерСущностей");
ХранилищеПользователей = Поделка.НайтиЖелудь("ХранилищеСущностейПользователь");

Множественные источники данных

// В конфигурации приложения
СоветДругогоМастера = Новый СоветДругогоМастера()
    .Деталька("data.ИсточникиДанных", Новый Массив()
        .Добавить(Новый Соответствие()
            .Вставить("Имя", "Основной")
            .Вставить("ТипКоннектора", "КоннекторSqlite")
            .Вставить("СтрокаСоединения", "Data Source=main.db")
        )
        .Добавить(Новый Соответствие()
            .Вставить("Имя", "Архивный")
            .Вставить("ТипКоннектора", "КоннекторPostgreSQL")
            .Вставить("СтрокаСоединения", "Host=archive.local;Database=archive")
        )
    );

Поделка = Новый Поделка(СоветДругогоМастера);
Поделка.ЗапуститьПриложение();

// Получение компонентов для разных источников
ОсновнойИсточник = Поделка.НайтиЖелудь("ИсточникДанныхОсновной");
АрхивныйИсточник = Поделка.НайтиЖелудь("ИсточникДанныхАрхивный");

ОсновнойМенеджер = Поделка.НайтиЖелудь("МенеджерСущностейОсновной");
АрхивныйМенеджер = Поделка.НайтиЖелудь("МенеджерСущностейАрхивный");

ХранилищеПользователей = Поделка.НайтиЖелудь("ХранилищеСущностейОсновнойПользователь");
ХранилищеАрхивныхДокументов = Поделка.НайтиЖелудь("ХранилищеСущностейАрхивныйДокумент");

Внутренние методы

ИнициализироватьИсточникиДанных()

Создает массив объектов ИсточникДанных на основе переданной конфигурации.

Возвращает: Массив объектов ИсточникДанных

ПолучитьИли(Соответствие, Ключ, ЗначениеПоУмолчанию)

Вспомогательный метод для извлечения значения из соответствия с возможностью указания значения по умолчанию.

Параметры:

• Соответствие - источник данных
• Ключ - ключ для поиска
• ЗначениеПоУмолчанию - значение, возвращаемое если ключ не найден

Возвращает: Значение из соответствия или значение по умолчанию

ПриИнициализацииПоделки(Поделка)

Основной метод инициализации, вызываемый ОСенью, для конфигурации контейнера зависимостей.

См. также

• Настройка источников данных
• ХранилищеСущностей
• НапильникХранилищеСущностей

---

НапильникХранилищеСущностей

Пост-процессор (напильник) для автоматической генерации реализации методов запросов в классах хранилищ сущностей. Отвечает за анализ аннотаций и создание декораторов с соответствующими перехватчиками методов.

Назначение

НапильникХранилищеСущностей выполняет следующие функции:

1. Обрабатывает классы с аннотацией &ХранилищеСущностей
2. Анализирует методы с аннотацией &МетодЗапроса
3. Генерирует реализацию методов запросов на основе их имен
4. Создает наследников с делегированием к базовому хранилищу
5. Интегрирует сгенерированные классы с autumn framework

Аннотации

&Напильник

Класс помечен аннотацией &Напильник, что означает его использование как процессора в рамках autumn framework для обработки других классов.

Конструктор

Процедура ПриСозданииОбъекта(
    &Пластилин Поделка,
    &Пластилин КонтейнерАннотаций,
    &Пластилин ПостроительОпцийПоиска
)

Параметры

Поделка

Тип: Поделка

Контейнер зависимостей, используемый для получения определений аннотаций и поиска желудей.

КонтейнерАннотаций

Тип: КонтейнерАннотаций

Контейнер для работы с аннотациями библиотеки annotations, предоставляемый ОСенью.

ПостроительОпцийПоиска

Тип: ПостроительОпцийПоиска

Внутренний компонент для анализа имен методов и построения объектов ОпцииПоиска.

Основной метод

ОбработатьЖелудь(Желудь, ОпределениеЖелудя)

Основной метод обработки классов, помеченных аннотацией &ХранилищеСущностей.

Параметры:

• Желудь - исходный объект класса
• ОпределениеЖелудя - метаданные класса с информацией о методах и аннотациях

Возвращает: Обработанный объект (декоратор) или исходный объект, если обработка не требуется

Алгоритм обработки

1. Проверка аннотации

Метод проверяет наличие аннотации &ХранилищеСущностей в конструкторе класса:

АннотацияХранилищеСущностей = РаботаСАннотациями.НайтиАннотацию(Конструктор.Аннотации, "ХранилищеСущностей");

Если АннотацияХранилищеСущностей = Неопределено Тогда
    Возврат Желудь; // Класс не требует обработки
КонецЕсли;

2. Извлечение параметров аннотации

Из аннотации извлекаются:

• ИмяТипаСущности - тип сущности для работы
• ИсточникДанныхСущности - источник данных (опционально)

3. Получение базового хранилища

Напильник находит соответствующее базовое хранилище сущностей в контейнере:

ХранилищеСущностей = _Поделка.НайтиЖелудь("ХранилищеСущностей" + ИсточникДанныхСущности + ИмяТипаСущности);

4. Создание построителя наследника

Используется ПостроительНаследника из библиотеки extends для создания класса-наследника:

ПостроительНаследника = Новый ПостроительНаследника(
    Желудь,
    ХранилищеСущностей,
    ОпределениеЖелудя.Методы(),
    ОпределениеЖелудя.Завязь().ДанныеМетода()
);

5. Обработка методов запросов

Для каждого метода с аннотацией &МетодЗапроса:

1. Анализ имени метода - ПостроительОпцийПоиска разбирает имя метода и создает параметры поиска
2. Генерация кода - создается строка с кодом для выполнения запроса
3. Создание перехватчика - генерируется перехватчик с кодом реализации метода

6. Построение декоратора

Создается окончательный декоратор с всеми перехватчиками и возвращается вместо исходного объекта.

Пример генерации кода

Для метода:

&МетодЗапроса
Функция ПолучитьПервыеСоСмещениемПоИмяРавноИВозрастБольше(Количество, Смещение, Имя, Возраст) Экспорт
    Возврат Неопределено;
КонецФункции

Напильник сгенерирует следующий код:

ОпцииПоиска = Новый ОпцииПоиска();
ОпцииПоиска.Первые(Количество);
ОпцииПоиска.Смещение(Смещение);
ОпцииПоиска.Отбор("Имя", ВидСравнения.Равно, Имя);
ОпцииПоиска.Отбор("Возраст", ВидСравнения.Больше, Возраст);
Возврат ХранилищеСущностей.Получить(ОпцииПоиска);

Поддерживаемые конструкции

Режимы поиска

• Получить - генерирует вызов ХранилищеСущностей.Получить(ОпцииПоиска)
• ПолучитьОдно - генерирует вызов ХранилищеСущностей.ПолучитьОдно(ОпцииПоиска)

Ограничения

• Первые - генерирует вызов ОпцииПоиска.Первые(Параметр)
• СоСмещением - генерирует вызов ОпцииПоиска.Смещение(Параметр)

Условия отбора

Все виды сравнения преобразуются в соответствующие вызовы:

ОпцииПоиска.Отбор("ПутьКДанным", ВидСравнения.ВидСравнения, Параметр);

Поддерживаемые виды сравнения:

• Равно, НеРавно, Больше, БольшеИлиРавно, Меньше, МеньшеИлиРавно, В, НеВ

Сортировка

Сортировка преобразуется в вызовы:

ОпцииПоиска.СортироватьПо("ПутьКДанным", НаправлениеСортировки.Направление);

Поддерживаемые направления:

• НаправлениеСортировки.Возр (по умолчанию)
• НаправлениеСортировки.Убыв

Соответствие параметров

Напильник обеспечивает правильное соответствие параметров метода и их использования в сгенерированном коде:

1. Параметры ограничений (Первые, СоСмещением) используются в порядке их следования в имени метода
2. Параметры условий отбора используются в том же порядке, что и условия в имени метода
3. Индексы параметров вычисляются автоматически на основе позиции в массиве параметров метода

Внутренние зависимости

Класс использует следующие внутренние компоненты:

• ПостроительОпцийПоиска - для анализа имен методов
• ТокенайзерЗапросов - для разбора токенов в именах методов
• Компоненты библиотеки extends для создания наследников
• Компоненты autumn framework для работы с аннотациями

Обработка ошибок

Напильник выполняет валидацию:

• Проверяет корректность параметров аннотаций
• Валидирует структуру имен методов через ПостроительОпцийПоиска
• Обеспечивает соответствие количества параметров метода и ожидаемых параметров

При обнаружении ошибок генерируются соответствующие исключения с описанием проблемы.

См. также

• МетодЗапроса
• ХранилищеСущностей
• ЗаготовкаОсеньДата
• Методы запросов