SQaLice
Содержание
Описание и назначение
Пакет SQaLice предназначен для гибкой обработки запросов к БД на PostgreSQL в проектах с применением go-swagger. SQaLice позволяет запрашивать конкретный набор полей из установленного target, фильтровать, сортировать и ограничивать получаемый набор строк.
Подготовка к использованию компилятора
В функцию-компилятор Compile в качестве аргумента передается modelsMap, содержащая информацию о полях моделей проекта, используемых для обработки целевого SQL кода.
Рекомендуется формировать данную map динамически, например в init модуля при запуске проекта, что обеспечит консистентность сгенерированных посредством go-swagger
моделей и данных, передаваемых в компилятор через map. Для этого можно использовать функцию FormDinamicModel. Также в этом случае в swagger-модели не должно быть вложенных моделей, иначе произойдут некорректное считывание тегов полей и ошибки формирования полей.
Формат запроса
В случае обращения к компилятору SQaLice все параметры целевого запроса должны содержаться в аргументе params. В target передается целевая таблица или view, к которой осуществляется запрос и которая используется при указании динамической модели.
Структура запроса
Аргумент params при парсинге запроса внутри Compile разделяется на 3 блока - fields, conditions, restrictions.
Пример адресной строки запроса, содержащей все 3 блока
http://url/.../query=ID,title,updatedAt?ID==10||ID==8?ID,desc,2,0
В случае отсутствия необходимости в указании одного из этих блоков, приведенное форматирование должно сохраняться.
Пример адресной строки запроса без блока conditions
http://url/.../query=ID,title,updatedAt??ID,desc,2,0
Запрос без указания условий в 3 блоках одновременно не рекомендуется, так как может привести к неожиданным ошибкам.
Типы математических операторов
SQaLice поддерживает следующие математические операторы:
Оператор |
SQaLice |
PG |
РАВНО |
== |
= |
НЕ РАВНО |
!= |
!= |
МЕНЬШЕ |
< |
< |
МЕНЬШЕ ИЛИ РАВНО |
<= |
<= |
БОЛЬШЕ |
> |
> |
БОЛЬШЕ ИЛИ РАВНО |
>= |
>= |
Пример адресной строки, содержащей математический оператор
http://url/.../query=ID,name?ID!=10?,,2,0
Типы логических операторов
SQaLice поддерживает следующие логические операторы:
Оператор |
SQaLice |
PG |
И |
* |
AND |
ИЛИ |
Двойная прямая черта |
OR |
Пример адресной строки запроса, содержащей оба оператора
http://url/.../query=?(ID==8*title==Тест)||ID==10?
Блок fields
Для получения всех полей из целевой SQL нужно передавать данный блок пустым.
Пример адресной строки запроса с пустым блоком fields
http://url/.../query=?ID==10||ID==8?ID,desc,2,0
Для получения конкретных полей, в поле fields необходимо передавать название поля в формате json с запятыми в качестве
разделителя и без пробелов.
ID,title,createdAt?
Пример адресной строки запроса для получения ID
http://url/.../query=ID?ID>=1?ID,desc,10,0
При передаче некорректного названия поля, SQaLice вернет ошибку:
"[SQaLice] Passed unexpected field name in select"
Блок conditions
В данном блоке возможно указание условий получения записей. Допускается передача пустого блока conditions, в таком случае происходит выборка без дополнительных условий.
Пример запроса без блока conditions
http://url/.../query=ID,title,createdAt??ID,asc,10,0
Условия должны разделяться допустимыми математическими операторами и не содержать пробелов.
Пример использования простой условной конструкции
?title==Тест?
Разделение нескольких условий осуществляется с помощью допустимых логических операторов, так же без пробелов. Кроме того могут быть использованы условные блоки в круглых скобках. Количество таких блоков не ограничено.
Пример использования сложной условной конструкции
(ID>8*ID<10)||title==Тест
ВАЖНО! При использовании сочетания условных блоков в скобках и без, блок без скобок должен указываться последним, как на приведенном выше примере. В противном случае запрос будет некорректным.
Для оператора == возможно указание нескольких значений через запятую, без пробелов. В таком случае происходит отбор значения по переданному массиву.
Пример условной конструкции с выбором по массиву
?ID==7,8,10?
При передаче условной конструкции с неверным логическим оператором, SQaLice вернет ошибку:
"[SQaLice] Unsupported operator in condition"
При передаче условной конструкции с неверным названием поля, SQaLice вернет ошибку:
"[SQaLice] Passed unexpected field name in condition"
Блок restrictions
В данном блоке возможно указание ограничений конечной выборки. Допускается передача пустого блока ограничений, в таком случае SQaLice не накладывает дополнительных условий на выборку.
Пример запроса без блока ограничений
http://url/.../query=ID,title,createdAt?ID>1?
При заполнении ограничений в блоке restrictions необходимо соблюдать порядок параметров блока, разделять их запятыми и не использовать пробелы
Порядок указания ограничений
Параметр |
Допустимые значения |
Поле сортировки |
Поле, переданное в fieldsMap |
Порядок сортировки |
asc, desc |
Лимит |
Целое число >= 0 |
Оффсет |
Целое число >= 0 |
Пример запроса со всеми параметрами ограничений
http://url/.../query=ID,title,createdAt?ID>1?ID,asc,10,0
Пример запроса с частью параметров (лимит, оффсет)
http://url/.../query=ID,title,createdAt?ID>1?,,10,0
При передаче некорректного названия поля сортировки, SQaLice вернет ошибку:
"[SQaLice] Unexpected selection order field"
При передаче некорректного порядка сортировки, SQaLice вернет ошибку:
"[SQaLice] Unexpected selection order"
При передаче некорректного лимита, SQaLice вернет ошибку:
"[SQaLice] Unexpected selection limit"
При передаче некорректного оффсета, SQaLice вернет ошибку:
"[SQaLice] Unexpected selection offset"
TO-DO
TO-DO |
Статус |
Покрытие тестами |
Выполнено |
Обработка сложных условий (вложенность, дополнительные операторы) |
Не выполнено |
Снятие ограничений порядка условий |
Не выполнено |