Перейти до основного вмісту
Перекладена сторінка

Цю сторінку перекладено з англійської мови за допомогою ШІ. Якщо тексти відрізняються, еталоном є англійська версія.

Розробка провайдерів StackQL

Див. також: [ StackQL Provider Registry ] [ Використання провайдера ] [ REGISTRY ] [ Архітектура ]

Огляд​

Провайдер StackQL - це версійований набір документів OpenAPI з розширеннями x-stackQL-*, які рушій omnisdk перетворює на таблиці SQL: SELECT для читання, INSERT, UPDATE, REPLACE і DELETE для операцій життєвого циклу та EXEC для дій. Документи провайдера повідомляють StackQL, що вміє робити API провайдера і як викликати його із семантикою SQL. Це звичайний YAML, тож провайдер можна збирати, тестувати й версіонувати, як будь-який інший код.

Екосистему провайдерів становлять три репозиторії та один рівень розповсюдження:

КомпонентРоль
stackql-provider-TEMPLATEВідправна точка для нового проєкту провайдера: детермінований конвеєр make від закріпленої специфікації upstream до згенерованого провайдера, рівні тестів без облікових даних, набір smoke test із реальним API, мікросайт документації та CI. Містить skill Claude Code для розробки провайдерів.
omnisdkРушій, що читає документи провайдерів і виконує запити до API, починаючи з StackQL v1.0. Його попередник, any-sdk, досі містить довідку щодо контракту документа провайдера, розширень x-stackQL-*, автентифікації, розбиття на сторінки, перетворень і передавання предикатів, а також схеми JSON, посилання на які наведено нижче.
stackql-provider-registryДжерело істини для опублікованих провайдерів. Документи зберігаються з версіями в providers/src/<provider>/<version>/, після чого GitHub Actions підписує, пакує та публікує їх.
Рівень розповсюдження CloudflareCloudflare Worker роздає запаковані артефакти провайдерів із Cloudflare R2 на периферії мережі за адресами registry.stackql.app (робоче середовище) і registry-dev.stackql.app (середовище розробки). Саме до нього звертаються REGISTRY LIST і REGISTRY PULL.

Наведена нижче діаграма показує шлях від проєкту провайдера до встановленого екземпляра StackQL:

Структура документів провайдера​

Об'єкти StackQL дотримуються ієрархії provider.service.resource.method, наприклад google.compute.instances.list. Документи відображають цю ієрархію:

provider.yaml # provider metadata, providerServices, provider-level config
services/
<service>.yaml # an OpenAPI 3 document per service, plus
components.x-stackQL-resources
<resource> # id, name, methods, sqlVerbs, optional config
methods.<method> # operation $ref, response, request, optional config
  • Документ провайдера (provider.yaml): id, name, title, version, providerServices (кожен із service.$ref на свій документ сервісу та необов'язковим прапорцем preferred), необов'язкові description, protocolType (за замовчуванням http) і config.
  • Документ сервісу: стандартний документ OpenAPI 3. Єдине обов'язкове доповнення - components.x-stackQL-resources, що оголошує ресурси, доступні як таблиці.
  • Ресурс: id, name, methods і sqlVerbs. Кожен ресурс - це таблиця; її стовпці беруться зі схеми відповіді основного методу select.
  • Метод: operation, що є вказівником JSON на paths (наприклад, $ref: '#/paths/~1orgs~1{org}~1repos/get'), блок response (mediaType, openAPIDocKey, objectKey), що повідомляє рушію, де розташовано рядки, а також необов'язкові блок request і config.
  • Зіставлення дієслів SQL: sqlVerbs.select, insert, update, replace і delete - це впорядковані списки посилань на методи. StackQL розглядає методи зі списку, усі обов'язкові параметри яких надає речення WHERE, і вибирає той, що має найбільше обов'язкових параметрів, незалежно від порядку в списку: запит, що надає ідентифікатор, потрібний методу get, спрямовується до get, запит без нього - до list, а якщо два методи рівноцінні, StackQL повідомляє про помилку, а не вибирає між ними. Будь-який метод, на який немає посилання в жодному списку дієслів, можна викликати через EXEC.

Мінімальний ресурс має такий вигляд:

components:
x-stackQL-resources:
repos:
id: github.repos.repos
name: repos
title: Repos
methods:
list_for_org:
operation:
$ref: '#/paths/~1orgs~1{org}~1repos/get'
response:
mediaType: application/json
openAPIDocKey: '200'
create_in_org:
operation:
$ref: '#/paths/~1orgs~1{org}~1repos/post'
response:
mediaType: application/json
openAPIDocKey: '201'
config:
requestBodyTranslate:
algorithm: naive
sqlVerbs:
select:
- $ref: '#/components/x-stackQL-resources/repos/methods/list_for_org'
insert:
- $ref: '#/components/x-stackQL-resources/repos/methods/create_in_org'

Повний контракт, зокрема кожен ключ і його призначення, описано в специфікації провайдера в any-sdk. Схеми JSON для provider.yaml, документів сервісів і блоку конфігурації розташовано в any-sdk/cicd/schema-definitions; схема конфігурації відхиляє невідомі ключі, тож ключ з помилкою в назві не проходить перевірку, а не ігнорується мовчки.

Розширення OpenAPI​

РозширенняДеПризначення
x-stackQL-resourcescomponentsСловник ресурсів документа сервісу (обов'язковий)
x-stackQL-configсервіс, ресурс, метод або операціяБлок конфігурації (див. нижче), що застосовується на цьому рівні
x-stackQL-envVarзмінна сервераВказує змінну середовища, що надає значення змінної сервера, коли його не вказано в реченні WHERE. Використовується, щоб обмежити область API тенантом, організацією, проєктом або розгортанням
x-stackQL-aliasпараметр або властивість схемиАльтернативне ім'я, яке SQL приймає замість імені на рівні протоколу
x-stackQL-stringOnlyвластивість схемиСеріалізує властивість як рядкове значення незалежно від її оголошеного типу
x-stackQL-graphQLопераціяРеалізує метод через запит GraphQL, коли в REST API немає потрібних даних
x-alwaysRequiredпараметрПозначає параметр як завжди обов'язковий
x-protocolinfoПідказка щодо мережевого протоколу (query, ec2, rest-xml) для обробки відповідей XML на основі схеми

Блок конфігурації​

Ключ config у файлі provider.yaml і розширення x-stackQL-config у документах сервісів мають спільну схему. Допустимі ключі: auth, pagination, queryParamPushdown, queryParamTranspose, requestTranslate, requestBodyTranslate, variations, views, sqlExternalTables, retry, minStackQLVersion і snake_case_aliases. Конфігурація визначається від найконкретнішого рівня назовні, метод -> ресурс -> сервіс -> сервіс провайдера -> провайдер, тож значення за замовчуванням для всього провайдера можна перевизначити для окремого ресурсу або методу.

Що забезпечують провайдери​

Провайдери беруть на себе завдання, які приховують складність API, тож користувачі отримують узгоджений інтерфейс SQL і не мусять керувати обміном HTTP на нижньому рівні.

Автентифікація​

Кожен провайдер містить блок auth за замовчуванням, що вказує змінні середовища з його обліковими даними, тож у заповненому середовищі конфігурація автентифікації під час виконання не потрібна. У документі провайдера допускаються лише непрямі посилання (імена змінних середовища, шляхи до файлів); буквальні значення облікових даних можна передавати виключно в контексті --auth під час виконання. Імена змінних середовища мають відповідати провайдеру Terraform від постачальника, якщо такий існує.

auth.typeТипові поля
bearercredentialsenvvar
api_keycredentialsenvvar, valuePrefix, необов'язкові location (header або query) і name
basicusername_var, password_var
customlocation, name, credentialsenvvar, необов'язковий valuePrefix; другі облікові дані додаються ланцюжком через successor
oauth2client_id_env_var, client_secret_env_var, grant_type: client_credentials, token_url, scopes
service_accountcredentialsenvvar або credentialsfilepathenvvar, scopes
aws_signing_v4, aws_assume_rolekeyIDenvvar, credentialsenvvar
azure_defaultнемає
oci_signing_v1tenancy_ocid_envvar, user_ocid_envvar, oci_fingerprint_envvar, oci_private_key_envvar, oci_region_envvar
interactiveнемає
null_authнемає (явно без автентифікації)

Наприклад:

config:
auth:
type: api_key
credentialsenvvar: OKTA_API_TOKEN
valuePrefix: 'SSWS '

Користувачі можуть перевизначити автентифікацію провайдера під час виконання за допомогою --auth='{"<provider>": {...}}'.

Розбиття на сторінки​

Провайдери оголошують схему розбиття на сторінки, яку використовує постачальник, а рушій проходить усі сторінки, тож користувачі отримують повні набори результатів. Підтримувані схеми:

  • Токен або курсор у тілі: requestToken: {key: cursor, location: query}, responseToken: {key: $.cursor, location: body}; обхід зупиняється, коли токен відсутній або порожній.
  • URL наступної сторінки в тілі: requestToken: {key: '', location: request}, responseToken: {key: $.next, location: body}; algorithm: odata_next_link для OData @odata.nextLink.
  • Заголовок Link за RFC 5988: responseToken: {key: Link, location: header}.
  • Номер сторінки з кількістю сторінок: algorithm: page_number з responseToken (поточна сторінка) і responseTerminator (загальна кількість сторінок).

API зі зсувом і лімітом без маркера наступної сторінки не є схемою розбиття на сторінки; натомість надайте offset і limit як параметри WHERE. Глобальний прапорець --http.response.pageLimit обмежує обхід сторінок.

Передавання предикатів​

Ключі WHERE зіставляються з оголошеними параметрами операції за іменем (спочатку параметри шляху, потім параметри запиту, заголовка й cookie) і надсилаються в API, тож фільтрування відбувається на джерелі. Будь-який ключ WHERE, що залишився без відповідного параметра, додається як параметр запиту.

Крім звичайних параметрів, queryParamPushdown перетворює стовпці SELECT, WHERE, ORDER BY, LIMIT, OFFSET і COUNT на параметри API. dialect: odata заповнює значення за замовчуванням $select, $filter, $orderby, $top, $skip і $count, які використовують Microsoft Graph та API у стилі Azure; dialect: custom використовує paramName дослівно, найчастіше top: {paramName: limit, maxValue: 1000}, щоб LIMIT n перетворювався на ?limit=n. Предикати, які неможливо передати, однаково обчислюються на боці клієнта.

Перетворення відповідей і запитів​

  • response.objectKey - це вираз JSONPath (або XPath для API на XML), що вибирає з конверта відповіді елементи, які містять рядки, наприклад $.data[*] або $.value.
  • response.transform застосовує текстовий шаблон Go до тіла відповіді, перш ніж його буде збережено як рядки; типи перетворень охоплюють JSON, XML і звичайний текст, і саме так API AWS на XML і вивід CLI стають таблицями.
  • requestBodyTranslate: {algorithm: naive} дає змогу інструкції INSERT приймати поля тіла запиту як звичайні імена стовпців, а не у формі з префіксом data__.
  • snake_case_aliases: true на рівні провайдера надає імена протоколу в camelCase як стовпці й параметри в snake_case.
  • retry встановлює політику повторних спроб з експоненційною затримкою (max_attempts, initial_delay_ms, max_delay_ms, multiplier, jitter_fraction, retryable_methods, retryable_conditions.status_codes). Діє перший рівень, на якому її оголошено; див. політику повторних спроб в any-sdk.

Типи стовпців відповідають схемі OpenAPI: string -> text, integer -> integer, number -> numeric, boolean -> boolean. Властивості object і array зберігаються як текст JSON, тому вкладені поля в запитах читають за допомогою json_extract, і тому провайдери часто постачають подання (config.views з ddl для кожного діалекту та fallback) для поширених вкладених проєкцій.

Провайдери без HTTP​

protocolType: local_templated у файлі provider.yaml реалізує провайдер на основі локальних команд замість HTTP: методи містять масив inline із фрагментами argv у вигляді шаблонів Go, параметри використовують in: inline, а response.transform перетворює вивід команди на рядки. Еталонний провайдер local_openssl в any-sdk демонструє цю структуру. Конвеєр шаблону, призначений для API HTTP, цього не охоплює.

Створення проєкту провайдера​

Починайте кожен новий провайдер із stackql-provider-TEMPLATE. Це шаблонний репозиторій GitHub, що втілює поточний стандарт провайдера: закріплену специфікацію upstream, детермінований конвеєр збірки, у якому кожне ручне рішення є правилом у скрипті, а не ручним редагуванням згенерованого YAML, три рівні тестів без облікових даних, набір smoke test із реальним API з обмеженим бюджетом, сайт документації на Docusaurus та CI. Опубліковані провайдери, зібрані в такий спосіб, розміщено в організації GitHub stackql-registry; вони є корисним довідковим матеріалом поряд із шаблоном.

Передумови: Node.js 20 або новіший, GNU make і bash (Linux, macOS або WSL), Python 3 для набору smoke test і двійковий файл stackql (bin/start-server.sh завантажує його, якщо його не знайдено).

  1. Створіть репозиторій із шаблону (GitHub "Use this template") і виконайте npm install.
  2. Виконайте bin/init-provider.sh <name> "<Title>" [https://api.vendor.com], щоб замінити заповнювачі в усьому репозиторії.
  3. Заповніть константи у файлі provider-dev/scripts/lib/spec_helpers.mjs (URL специфікації, префікс версії в шляху, префікс області для API з областю тенанта або проєкту) і конфігурацію в provider-dev/config/ (servers.json, provider_config.json, service_names.json).
  4. Пройдіть конвеєр вручну через цілі make або відкрийте сеанс Claude Code у репозиторії (див. нижче).
  5. grep -rn "TODO(template)" виводить список того, що ще не зроблено.

Конвеєром керує make (make help виводить список усіх цілей):

make fetch-spec # verify the upstream spec against the recorded pin (fails on drift)
make inventory # one CSV row per operation with the proposed service, resource, method and verb
make split # write provider-dev/source/<service>.yaml from the ordered path rules
make mappings-report # print every derived operation -> resource.method mapping without writing
make mappings # regenerate provider-dev/config/all_services.csv and validate it
make normalize # flatten allOf, lower oneOf/anyOf, wrap bare arrays
make generate # generate provider.yaml + services/*.yaml, then post-process and merge GraphQL/views
make test # offline SHOW/DESCRIBE, mock API integration tests, meta-route walk (no credentials)
make smoke # live smoke suite against a dedicated dev account (sources .env)
make docs # generate the provider documentation site content
make all # everything above except the live suites

Усередині конвеєр використовує @stackql/provider-utils (split, normalize, analyze, generate і docgen) із правилами для конкретного провайдера в provider-dev/scripts/. Згенерований провайдер потрапляє до provider-dev/openapi/src/<name>/v00.00.00000/ - саме цей каталог зрештою публікується в реєстрі.

Файл provider-dev/config/all_services.csv - це зафіксований у коміті контракт зіставлення кожної операції з ресурсом і методом. Різниця після повторної генерації - це привід для перевірки на несумісні зміни, а не шум. CI завершується помилкою в разі дрейфу генерації, не зафіксованого в коміті, тож повторна генерація має відтворювати зафіксовані артефакти байт у байт.

Для наявного репозиторію провайдера, створеного до появи шаблону, скопіюйте в нього каталог .claude/skills і почніть із файлу references/uplift-checklist.md цього skill.

Використання Claude Code для розробки провайдерів​

Шаблон містить skill StackQL Provider Development для Claude Code. Відкрийте сеанс Claude Code у репозиторії, створеному із шаблону, і попросіть його зібрати провайдер; Claude Code підхоплює CLAUDE.md і skill та виконує кроки послідовно. Skill також є письмовою процедурою для виконання цієї роботи вручну.

Skill охоплює такі теми:

  • Вибір архетипу: документ OpenAPI, Swagger або discovery, опублікований постачальником (direct), чи специфікація, похідна від SDK постачальника, коли SDK є джерелом істини (derived)
  • Отримання, виправлення, перевірка коректності й закріплення специфікації upstream, щоб кожне оновлення було різницею, яку можна переглянути
  • Інвентаризація кінцевих точок, розподіл на сервіси та правила зіставлення, з яких утворюється all_services.csv
  • Кожен примітив документа провайдера і коли його використовувати: обмеження області через x-stackQL-envVar, objectKey, перетворення запитів і відповідей, розбиття на сторінки, передавання параметрів запиту (pushdown), методи EXEC для життєвого циклу, злиття GraphQL і подання провайдера
  • Три рівні тестів без облікових даних і набір smoke test із реальним API
  • Сайт документації, робочі процеси CI та нотатки для передавання проєкту

Каталог references/ цього skill містить подробиці щодо кожного кроку, а scripts/find_extension_examples.sh виводить YAML, що вже постачається у провайдерах, для будь-якого ключа розширення з клону реєстру провайдерів, тож примітив можна побачити в дії, перш ніж його писати.

Локальне тестування провайдера​

StackQL читає провайдери з реєстру, описаного глобальним прапорцем --registry. Під час розробки вкажіть йому каталог згенерованого провайдера в локальній файловій системі з вимкненою перевіркою підписів (документи підписуються лише під час публікації):

export LOCAL_REG='{ "url": "file:///path/to/provider-dev/openapi", "localDocRoot": "/path/to/provider-dev/openapi", "verifyConfig": { "nopVerify": true } }'
stackql --registry="${LOCAL_REG}" shell

Каталог, указаний у localDocRoot, має містити src/<provider>/<version>/provider.yaml і src/<provider>/<version>/services/*.yaml - саме це й генерує шаблон. В оболонці інструкції SHOW SERVICES IN <provider>, SHOW RESOURCES IN <provider>.<service>, SHOW METHODS IN <provider>.<service>.<resource> і DESCRIBE EXTENDED <provider>.<service>.<resource> дають змогу перевірити поверхню провайдера до виконання будь-якого запиту. Файл шаблону tests/offline_validation.mjs автоматизує ці перевірки, а npm run probe -- "SELECT ..." виконує разовий SQL до імітаційного API і виводить виклики на рівні протоколу.

Провайдери, завантажені з віддаленого реєстру, за замовчуванням кешуються в <cwd>/.stackql; щоб змінити розташування, використовуйте прапорець --approot.

CLI any-sdk зручний для перевірки документа без участі StackQL: anysdk aot <registry> <provider.yaml> виконує статичний аналіз провайдера (objectKey, для якого неможливо визначити маршрут, відсутні схеми відповідей, неповне розбиття на сторінки, суміжні параметри шляху тощо), а anysdk query виконує окремий метод безпосередньо з документів провайдера й сервісу. Тестування Automock генерує імітаційний API та очікувані результати зі схем провайдера для повного циклу без звернення до реального API.

Тестування провайдера за допомогою реєстру dev​

Після злиття провайдера в гілку dev реєстру він стає доступним у реєстрі розробки. Вкажіть StackQL цей реєстр, щоб перевірити опублікований артефакт:

export DEV_REG='{ "url": "https://registry-dev.stackql.app/providers" }'
stackql --registry="${DEV_REG}" shell
REGISTRY PULL myprovider;

Ціль шаблону make smoke-live запускає набір smoke test для опублікованого провайдера, щоб перевірити його після публікації.

Публікація провайдера​

Публікація - це окремий крок за участю людини, який не входить до конвеєра шаблону.

  1. Створіть форк stackql-provider-registry і скопіюйте згенерований каталог provider-dev/openapi/src/<name> до providers/src/<name> в окремій робочій гілці (feature branch).
  2. Створіть pull request до гілки dev з описом провайдера та змін (див. посібник для учасників реєстру).
  3. GitHub Actions перевіряє коректність і тестує провайдер за допомогою stackql-provider-tests. Перевіряються такі правила: документ має бути допустимою специфікацією OpenAPI, для всіх сервісів має бути можливо перелічити ресурси, для всіх ресурсів - методи, методи, які можна викликати через SELECT, повинні мати допустиму схему відповіді, а методи, які можна викликати через INSERT, - допустиму схему запиту.
  4. Після злиття робочий процес виділяє версію, підписує документи (ML-DSA-65), пакує їх і публікує артефакт в архіві AWS S3. Потім дерево документів віддзеркалюється в Cloudflare R2, і розгортається Cloudflare Worker, що обслуговує registry-dev.stackql.app. Провайдер одразу стає доступним для екземплярів StackQL, налаштованих на використання реєстру dev.
  5. Після періоду моніторингу гілку dev просувають до main, і публікація повторюється для registry.stackql.app. Це публікація для екземплярів StackQL з конфігурацією за замовчуванням.

Той самий harness stackql-provider-tests можна запустити локально для каталогу реєстру, перш ніж створювати PR:

test-provider.sh <provider_name> false /path/to/provider-dev/openapi

Докладний опис робочого процесу, зокрема запобіжника від видалення провайдерів, що захищає providers/src, див. у документі збірка та розгортання в репозиторії реєстру.