Skip to content

README.ru.md

Latest commit

 

History

History
141 lines (101 loc) · 9.02 KB

README.ru.md

File metadata and controls

141 lines (101 loc) · 9.02 KB

English | Pусский

apisite/procapi

API для хранимых процедур БД

GoDoc codecov Build Status GoCard GitHub Release LoC GitHub code size in bytes GitHub license

Назначение

Пакет apisite/procapi является частью проекта apisite и предназначен для предоставления доступа к хранимым функциям БД (например, postgresql) следующим потребителям:

  • golang-шаблонам, для формирования страниц сайта с использованием данных из БД
  • внешним клиентам, для вызова функций БД из, например, javascript

Т.к. вся необходимая потребителям информация (включая список и сигнатуры функций БД) изначально размещена в БД, при ее изменении не требуется перекомпиляция golang-кода.

Задача пакета решается функцией вида:

func Call(method string, args map[string]interface{}) ([]map[string]interface{}, error) {}

для случая, когда методы API представляют собой функции Postgresql.

Дополнения

  1. Выбор map для аргументов обусловлен необходимостью различать
  • аргумент со значением (/name?arg=XX)
  • аргумент без значения (NULL) (/name?arg)
  • аргумент со значением по умолчанию (/name)
  1. Использование map в результате, для golang-потребителей, может быть сведено к структурам с помощью mapstructure
  2. Доступная в БД информация об аргументах функций используется для их валидации

Структура

Библиотека разделена на следующие части:

  • procapi - реализация функции Call
  • ginproc - интеграция функционала в gin

Особенности реализации

Тесты

Варианты запуска:

  1. TEST_DATABASE="{PG_DSN}" TZ="Europe/Berlin" go test ./...
  2. make cov - тесты с генерацией отчета о покрытии (см make help)

Postgresql

Т.к. для работы с БД могут потребоваться параметры соединения, они вынесены в файл настроек .env, для создания которого необходимо выполнить make config.

Варианты запуска Postgresql:

  1. Внешний, в настройках задаются параметры соединения, пользователь и БД должны существовать
  2. Внутренний (с помощью docker). Для запуска необходимо в отдельной консоли выполнить make test-docker-run

В любом из этих случаев, при выполнении тестов будут созданы и наполнены данными 3 схемы БД, которые после выполнения тестов будут удалены (по завершении тестов выполняется ROLLBACK).

Необходимый для тестов SQL-код подключается в каталог тестовых данных (testdata) посредством git submodule. Т.о., если проект не был склонирован с ключем --recursive, для подгрузки SQL необходимо выполнить

git submodule init
git submodule update

Используемый для тестов SQL-код разработан в рамках проекта pgmig и включает пакеты:

  • pgmig - сервисные функции
  • rpc - поддержка RPC
  • rpc_testing - тестовые функции для procapi

См. также: .drone.yml - пример запуска тестов

Сигнатуры методов

  • реестр доступных функций (и их сигнатуры) хранится в БД, там же хранятся описания функций, аргументов, результатов и примеры вызова (в перспективе - с поддержкой i18n)
  • в реестре также задается соответствие между именем функции в API и в БД
  • доступ к реестру производится через вызовы специальных функций БД (их схема и имена задаются в настройках)

procapi

Для получения информации из реестра используются функции с зашитыми в код сигнатурами (их имена могут быть изменены в настройках), вызов имеет вид SELECT * FROM %c(code):

  • --db.index $name (default:"index") - список доступных функций, структура ответа - Method
  • --db.indef $name (default:"func_args") - описание аргументов функции, структура ответа - InDef
  • --db.outdef $name (default:"func_result") - описание результата функции, структура ответа - OutDef

pgtype

Структура PGType дополняет возможности pgx v4. Код реализовывает интерфейс Marshaller и может быть заменен другим с помощью вызова SetMarshaller.

ginproc

Пакет добавляет в gin маршрутизацию для прямого вызова функций API и дополняет funcMap функциями доступа к API из шаблонов. Для работы с procapi используется интерфейс ginproc.Caller

TODO

  • JWT + OAuth
  • Проверка доступа
  • Кэш
  • тесты ошибок
  • поддержка нативных методов API (golang)
  • LISTEN для фоновой обработки задач
  • Read-Only транзакции для Method.IsRO
  • Rollback транзакции для тестов из шаблонов

История

  • 2010 - PGWS, 1я реализация API для функций Postgresql (perl)
  • 2012 - PGWS - часть проекта опубликована на github.com
  • 2016 - dbrpc - реализация API на go (+pgx)
  • 2018 - pgfc - API с поддержкой вызова из шаблонов
  • 2019 - [procapi] - API с тестами и поддержкой транзакций