autumn-data

autumn-data - это библиотека для простого подключения и работы с базами данных в ОСенних проектах (autumn framework), используя ORM-библиотеку nixel2007/entity и библиотеку наследования nixel2007/extends. autumn-data расширяет возможности entity, приправляя их осенней магией.

Установка

Для установки библиотеки используйте команду:

opm install autumn-data

Описание

Библиотека autumn-data добавляет следующие возможности над стандартной функциональностью entity:

Интеграция с autumn - полная интеграция с контекстом приложения ОСени
Автоматическая инициализация менеджера сущностей из конфигурации приложения - сама регистрирует все сущности и настраивает источники данных
Регистрация менеджера и хранилищ сущностей как желудей - позволяет легко внедрять хранилища сущностей как зависимости
Расширение Хранилища сущностей - добавляет аннотации для создания собственных хранилищ сущностей, наследующих базовые методы от entity
Автогенерация запросов - автоматическое создание запросов к базе данных на основе имен добавленных методов
Пул соединений - соединения берутся из пула источника данных, размер пула задается в настройках источника
Наблюдатели источника данных - желуди с прозвищем НаблюдательИсточникаДанных регистрируются на всех источниках данных

Быстрый старт

1. Определение сущности

Классы/Пользователь.os

bsl

&Идентификатор
&Колонка(Тип = "Целое")
Перем Идентификатор Экспорт;

&Колонка(Тип = "Строка", Длина = 100)
Перем Имя Экспорт;

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

2. Настройка источника данных

Создайте файл autumn-properties.json в корне вашего проекта и добавьте секцию для источников данных:

autumn-properties.json

json

{
    "data": {
        "ИсточникиДанных": {
            "ТипКоннектора": "КоннекторSQLite",
            "СтрокаСоединения": "Data Source=database.db"
        }
    }
}

ОСень автоматически подхватит настройки из этого файла при запуске приложения.

3. Базовое использование

main.os

bsl

#Использовать autumn
#Использовать autumn-data
#Использовать "."

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

// Желудь "ХранилищеСущностейПользователи" автоматически регистрируется
// при запуске приложения на основании типа &Сущности "Пользователь"
Хранилище = Поделка.НайтиЖелудь("ХранилищеСущностейПользователь");
Пользователь = Хранилище.ПолучитьОдно(123);

TIP

Не останавливайтесь на базовом использовании! Библиотека autumn-data предоставляет расширенные возможности для работы с базами данных, включая расширение функциональности хранилищ сущностей и автоматическую генерацию методов запросов. Подробнее в следующих разделах документации.

Основные концепции

Сущности

Сущности - это классы, которые представляют таблицы в базе данных. Они помечаются аннотацией &Сущность.

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

Хранилища - это классы-репозитории, которые предоставляют методы для работы с сущностями. Хранилища сущностей бывают двух видов:

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

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

Методы запросов

Методы, помеченные аннотацией &МетодЗапроса, автоматически получают реализацию на основе своего имени. Поддерживаются различные паттерны имен методов для создания запросов.

Дальнейшее изучение

Руководство пользователя

Настройка источников данных - конфигурация подключений к базам данных
Методы запросов - автоматическая генерация реализаций методов обращения к базе данных

Справочник API

Полный API справочник
МетодЗапроса - описание аннотации для автоматической генерации методов запросов
ХранилищеСущностей - создание расширенных репозиториев для сущностей
ЗаготовкаОсеньДата - основной конфигуратор библиотеки
НапильникХранилищеСущностей - процессор автогенерации методов

Лицензия

Этот проект лицензируется под лицензией MIT. Подробности см. в файле LICENSE.md.

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

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

Основные понятия

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

Источник данных определяет подключение к конкретной базе данных. Каждый источник данных имеет:

Имя - уникальный идентификатор источника
Тип коннектора - класс коннектора для подключения к БД
Строку соединения - параметры подключения к БД
Параметры коннектора - дополнительные параметры
Размер пула - предел одновременных соединений с БД, по умолчанию 10

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

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

Конфигурация одного источника данных

Как json

autumn-properties.json

json

{
    "data": {
        "ИсточникиДанных": {
            "Основной": {
                "ТипКоннектора": "КоннекторSqlite",
                "СтрокаСоединения": "Data Source=database.db"
            }
        }
    }
}

При такой конфигурации создается источник данных "Основной", и все хранилища будут использовать его по умолчанию. Дополнительно хранилища и менеджер сущностей будут доступны без указания имени источника данных.

Как массив с одним элементом

bsl

Детальки = Новый Соответствие();

СекцияData = Новый Соответствие();
Детальки.Вставить("data", СекцияData);

ИсточникиДанных = Новый Соответствие();
СекцияData.Вставить("ИсточникиДанных", ИсточникиДанных);

ИсточникиДанных.Вставить("ТипКоннектора", "КоннекторSQLite");
ИсточникиДанных.Вставить("СтрокаСоединения", "Data Source=database.db");

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

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

Как соответствие

bsl

Детальки = Новый Соответствие();

СекцияData = Новый Соответствие();
Детальки.Вставить("data", СекцияData);

ИсточникиДанных = Новый Соответствие();
СекцияData.Вставить("ИсточникиДанных", ИсточникиДанных);

ИсточникиДанных.Вставить("Имя", "МойИсточник");
ИсточникиДанных.Вставить("ТипКоннектора", "КоннекторInMemory");

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

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

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

Конфигурация множественных источников данных

Как json

autumn-properties.json

json

{
    "data": {
        "ИсточникиДанных": [
            "Основной": {
                "ТипКоннектора": "КоннекторSQLite",
                "СтрокаСоединения": "Data Source=main.db"
            },
            "Дополнительный": {
                "ТипКоннектора": "КоннекторPostgreSQL",
                "СтрокаСоединения": "Host=localhost;Database=testdb;Username=user;Password=pass"
            }
        ]
    }
}

Как массив с несколькими элементами

bsl

Детальки = Новый Соответствие();

СекцияData = Новый Соответствие();
Детальки.Вставить("data", СекцияData);

ИсточникиДанных = Новый Массив();
СекцияData.Вставить("ИсточникиДанных", ИсточникиДанных);

ИсточникДанных = Новый Соответствие();	
ИсточникДанных.Вставить("Имя", "Основной");
ИсточникДанных.Вставить("ТипКоннектора", "КоннекторInMemory");

ИсточникиДанных.Добавить(ИсточникДанных);

ИсточникДанных = Новый Соответствие();
ИсточникДанных.Вставить("Имя", "Дополнительный");
ИсточникДанных.Вставить("ТипКоннектора", "КоннекторSQLite");
ИсточникДанных.Вставить("СтрокаСоединения", "FullUri=file::memory:?cache=shared");

ИсточникиДанных.Добавить(ИсточникДанных);

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

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

При задании нескольких источников данных кодом доступен только вариант с массивом.

Размер пула соединений

Параметр РазмерПула задает предел одновременных соединений с БД. Если не задан, пул вмещает 10 соединений. Ноль отключает переиспользование соединений: каждое обращение к БД открывает свое соединение и закрывает его по завершении.

autumn-properties.jsonmain.os

json

{
    "data": {
        "ИсточникиДанных": {
            "Основной": {
                "ТипКоннектора": "КоннекторPostgreSQL",
                "СтрокаСоединения": "Host=localhost;Database=testdb",
                "РазмерПула": 20
            }
        }
    }
}

bsl

ИсточникиДанных.Вставить("ТипКоннектора", "КоннекторPostgreSQL");
ИсточникиДанных.Вставить("СтрокаСоединения", "Host=localhost;Database=testdb");
ИсточникиДанных.Вставить("РазмерПула", 20);

Размер доступен и из желудя источника: ИсточникДанных.РазмерПула().

Наблюдатели источника данных

Источник данных entity сообщает наблюдателям обо всем, что с ним происходит: операциях менеджера сущностей, запросах к СУБД, соединениях и транзакциях, см. наблюдателей источника данных в entity. autumn-data регистрирует наблюдателей сама: каждый желудь с прозвищем НаблюдательИсточникаДанных регистрируется на всех источниках данных до создания менеджеров сущностей, поэтому наблюдатель видит и создание таблиц.

bsl

&Желудь
&Прозвище("НаблюдательИсточникаДанных")
&Реализует("НаблюдательИсточникаДанных")
Процедура ПриСозданииОбъекта()
КонецПроцедуры

Процедура ПередСобытием(Событие) Экспорт
КонецПроцедуры

Процедура ПослеСобытия(Событие) Экспорт
    Если Событие.Вид() = ВидыСобытийИсточникаДанных.Запрос() И Событие.Длительность() > 100 Тогда
        Сообщить(СтрШаблон("Медленный %1 к %2: %3 мс", Событие.Операция(), Событие.ИмяТаблицы(), Событие.Длительность()));
    КонецЕсли;
КонецПроцедуры

Завязь с таким прозвищем вправе вернуть Неопределено - так наблюдение выключается настройкой. Без желудей с прозвищем источники остаются без наблюдателей.

Доступ к коннектору

Коннектор принадлежит соединению, а не прикладному коду. Менеджер и хранилища выполняют алгоритм на занятом соединении: ВыполнитьСКоннектором(Алгоритм, Контекст) и ВычислитьСКоннектором(Алгоритм, Контекст), где алгоритм - лямбда с параметром Коннектор.

bsl

Хранилище = Поделка.НайтиЖелудь("ХранилищеСущностейОсновнойФизическоеЛицо");
Строки = Хранилище.ВычислитьСКоннектором("Коннектор -> Коннектор.ВыполнитьЗапрос(Текст)", Новый Структура("Текст", "SELECT * FROM ФизическиеЛица"));

Указание источника данных для сущности

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

bsl

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

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

Указание источника данных для хранилища сущностей

Аналогично для хранилищ сущностей:

bsl

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

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

Получение хранилищ из контейнера

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

bsl

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

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

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

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

Библиотека поддерживает все коннекторы из библиотеки entity:

КоннекторSQLite
КоннекторPostgreSQL
КоннекторJSON
КоннекторInMemory (для тестирования)
И другие коннекторы, поддерживаемые entity

Параметры коннектора

Некоторые коннекторы могут требовать дополнительные параметры, которые передаются через массив ПараметрыКоннектора:

autumn-properties.jsonmain.os

json

{
    "data": {
        "ИсточникиДанных": {
            "Дополнительный": {
                "ТипКоннектора": "КоннекторPostgreSQL",
                "СтрокаСоединения": "Host=localhost;Database=testdb",
                "ПараметрыКоннектора": [      
                    "дополнительный_параметр"
                ]                             
            }
        }
    }
}

bsl

Детальки = Новый Соответствие();

СекцияData = Новый Соответствие();
Детальки.Вставить("data", СекцияData);

ИсточникиДанных = Новый Соответствие();
СекцияData.Вставить("ИсточникиДанных", ИсточникиДанных);

ИсточникиДанных.Вставить("ТипКоннектора", "КоннекторSQLite");
ИсточникиДанных.Вставить("СтрокаСоединения", "Data Source=database.db");

ПараметрыКоннектора = Новый Массив();
ПараметрыКоннектора.Добавить("дополнительный_параметр");
ИсточникиДанных.Вставить("ПараметрыКоннектора", ПараметрыКоннектора);

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

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

Методы запросов

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

Принцип работы

Метод, помеченный аннотацией &МетодЗапроса, должен:

Следовать определенным соглашениям об именовании
Иметь соответствующие параметры

Например:

bsl

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

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

bsl

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

Структура имени метода

Имя метода состоит из следующих частей:

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

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

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

Ограничения

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

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

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

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

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

Примеры методов

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

bsl

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

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

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

bsl

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

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

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

Множественные условия

bsl

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

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

Сортировка

bsl

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

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

Ограничения

bsl

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

// Пользователи с пропуском первых N записей
&МетодЗапроса
Функция ПолучитьСоСмещением(Смещение) Экспорт
    Возврат Неопределено;
КонецФункции

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

Комплексные запросы

bsl

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

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

Параметры метода должны соответствовать порядку их появления в имени метода:

Сначала идут параметры ограничений (Первые, СоСмещением)
Затем параметры условий отбора в порядке их следования в имени
Параметры сортировки не требуются, так как поля сортировки указываются в имени

Например, для метода:

bsl

ПолучитьПервыеСоСмещениемПоИмениРавноИВозрастБольшеУпорядочитьПоДатаСозданияУбыв(Количество, Смещение, Имя, Возраст)

Порядок параметров:

Количество - для ограничения Первые
Смещение - для ограничения СоСмещением
Имя - для условия ПоИмениРавно
Возраст - для условия ИВозрастБольше

Ограничения

Не все комбинации условий и ограничений могут быть поддержаны
Для сложных запросов рекомендуется использовать прямые вызовы ХранилищеСущностей-родителя с объектом ОпцииПоиска

autumn-data ​

Установка ​

Описание ​

Быстрый старт ​

1. Определение сущности ​

2. Настройка источника данных ​

3. Базовое использование ​

Основные концепции ​

Сущности ​

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

Методы запросов ​

Дальнейшее изучение ​

Руководство пользователя ​

Справочник API ​

Лицензия ​

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

Основные понятия ​

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

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

Конфигурация одного источника данных ​

Как json ​

Как массив с одним элементом ​

Как соответствие ​

Конфигурация множественных источников данных ​

Как json ​

Как массив с несколькими элементами ​

Размер пула соединений ​

Наблюдатели источника данных ​

Доступ к коннектору ​

Указание источника данных для сущности ​

Указание источника данных для хранилища сущностей ​

Получение хранилищ из контейнера ​

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

Параметры коннектора ​

Методы запросов ​

Принцип работы ​

Структура имени метода ​

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

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

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

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

Примеры методов ​

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

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

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

Сортировка ​

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

Комплексные запросы ​

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

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

autumn-data

Установка

Описание

Быстрый старт

1. Определение сущности

2. Настройка источника данных

3. Базовое использование

Основные концепции

Сущности

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

Методы запросов

Дальнейшее изучение

Руководство пользователя

Справочник API

Лицензия

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

Основные понятия

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

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

Конфигурация одного источника данных

Как json

Как массив с одним элементом

Как соответствие

Конфигурация множественных источников данных

Как json

Как массив с несколькими элементами

Размер пула соединений

Наблюдатели источника данных

Доступ к коннектору

Указание источника данных для сущности

Указание источника данных для хранилища сущностей

Получение хранилищ из контейнера

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

Параметры коннектора

Методы запросов

Принцип работы

Структура имени метода

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

Ограничения

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

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

Примеры методов

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

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

Множественные условия

Сортировка

Ограничения

Комплексные запросы

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

Ограничения