Autumn Docs

Оформление

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

Аннотации ​

Классы ​

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

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

Синтаксис ​

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

Описание ​

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

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

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

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

Где:

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

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

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

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

Ограничения ​

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

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

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

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

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

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

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

Примеры ​

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

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

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

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

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

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

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

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

Для метода:

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

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

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

Требования ​

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

Ограничения ​

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

См. также ​

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

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

Синтаксис ​

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

Параметры ​

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

Тип: Строка

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

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

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

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

Описание ​

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

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

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

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

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

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

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

Примеры ​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Например:

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

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

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

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

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

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

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

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

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

См. также ​

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

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

Назначение ​

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

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

Аннотации ​

bsl
&Заготовка

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

Конструктор ​

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

Параметры ​

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

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

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

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

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

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

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

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

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

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

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

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

  • Имя - уникальное имя источника данных (обязательно для множественных источников)
  • СтрокаСоединения - строка подключения к базе данных (по умолчанию пустая строка)
  • ПараметрыКоннектора - массив дополнительных параметров для коннектора (по умолчанию пустой массив)

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Прозвища ​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Параметры:

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

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

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

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

См. также ​

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

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

Назначение ​

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

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

Аннотации ​

bsl
&Напильник

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

Конструктор ​

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

Параметры ​

Поделка ​

Тип: Поделка

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

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

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

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

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

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

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

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

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

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

Параметры:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Для метода:

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

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

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

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

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

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

Ограничения ​

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

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

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

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

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

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

Сортировка ​

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

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

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

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

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

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

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

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

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

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

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

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

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

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

См. также ​