본문으로 건너뛰기
번역된 페이지

이 페이지는 AI의 도움을 받아 영어에서 번역되었습니다. 두 내용이 다를 경우 영어 버전을 기준으로 합니다.

StackQL 프로바이더 개발

참고 항목: [ StackQL Provider Registry ] [ 프로바이더 사용 ] [ REGISTRY ] [ 아키텍처 ]

개요​

StackQL 프로바이더는 버전이 지정된 OpenAPI 문서와 x-stackQL-* 확장의 집합이며, omnisdk 엔진이 이를 SQL 테이블로 변환합니다. 읽기에는 SELECT 문을, 수명 주기 작업에는 INSERT, UPDATE, REPLACE, DELETE 문을, 동작에는 EXEC 문을 사용합니다. 프로바이더 문서는 프로바이더의 API로 무엇을 할 수 있는지, 그리고 SQL 의미 체계로 이를 호출하는 방법을 StackQL에 알려 줍니다. 프로바이더 문서는 일반 YAML이므로 프로바이더를 다른 코드와 마찬가지로 빌드하고, 테스트하고, 버전을 관리할 수 있습니다.

프로바이더 생태계는 3개의 리포지토리와 1개의 배포 계층으로 구성됩니다:

구성 요소역할
stackql-provider-TEMPLATE새 프로바이더 프로젝트의 시작점입니다. 고정된 업스트림 사양에서 생성된 프로바이더까지 이어지는 결정적 make 파이프라인, 자격 증명이 필요 없는 테스트 계층, 라이브 스모크 테스트 모음, 문서 마이크로사이트와 CI를 포함합니다. Claude Code 프로바이더 개발 스킬이 번들로 포함되어 있습니다.
omnisdkStackQL v1.0부터 프로바이더 문서를 읽고 요청을 실행하는 엔진입니다. 이전 엔진인 any-sdk에는 프로바이더 문서 계약, x-stackQL-* 확장, 인증, 페이지네이션, 변환 및 푸시다운에 대한 참조 문서와 아래에 링크된 JSON 스키마가 여전히 있습니다.
stackql-provider-registry게시된 프로바이더의 단일 정보 출처입니다. 문서는 providers/src/<provider>/<version>/ 디렉터리 아래에서 버전별로 관리된 후 GitHub Actions에 의해 서명, 패키징, 게시됩니다.
Cloudflare 배포 계층패키징된 프로바이더 아티팩트는 registry.stackql.app(프로덕션)과 registry-dev.stackql.app(개발)의 Cloudflare Worker에 의해 Cloudflare R2에서 에지로 제공됩니다. 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 메서드의 응답 스키마에서 가져옵니다.
  • 메서드: paths 섹션을 가리키는 JSON 포인터인 operation(예: $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 메서드로 라우팅됩니다. 두 메서드가 동률이면 둘 중 하나를 선택하지 않고 오류로 보고합니다. 동사 목록에서 참조되지 않는 메서드는 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의 프로바이더 사양에 있습니다. provider.yaml 파일, 서비스 문서, config 블록의 JSON 스키마는 any-sdk/cicd/schema-definitions에 있습니다. config 스키마는 알 수 없는 키를 거부하므로, 잘못 입력한 키는 자동으로 무시되지 않고 유효성 검사에 실패합니다.

OpenAPI 확장​

확장위치용도
x-stackQL-resourcescomponents서비스 문서의 리소스 사전(필수)
x-stackQL-config서비스, 리소스, 메서드 또는 작업해당 수준에 적용되는 config 블록(아래 참조)
x-stackQL-envVar서버 변수WHERE 절에 서버 변수가 지정되지 않은 경우 그 값을 제공하는 환경 변수의 이름을 지정합니다. 테넌트, 조직, 프로젝트 또는 배포별로 API의 범위를 지정하는 데 사용됩니다.
x-stackQL-alias매개 변수 또는 스키마 속성와이어 수준 이름 대신 SQL에서 허용되는 대체 이름
x-stackQL-stringOnly스키마 속성선언된 형식과 관계없이 속성을 문자열로 직렬화
x-stackQL-graphQL작업REST API에 필요한 데이터가 없는 경우 메서드를 GraphQL 쿼리로 구현합니다.
x-alwaysRequired매개 변수매개 변수를 항상 필수로 표시합니다.
x-protocolinfo스키마 기반 XML 응답 처리를 위한 와이어 프로토콜 힌트(query, ec2, rest-xml)

config 블록​

provider.yaml 파일의 config 키와 서비스 문서의 x-stackQL-config 확장은 하나의 스키마를 공유합니다. 허용되는 키는 auth, pagination, queryParamPushdown, queryParamTranspose, requestTranslate, requestBodyTranslate, variations, views, sqlExternalTables, retry, minStackQLVersion, snake_case_aliases입니다. config 값은 가장 구체적인 수준에서 바깥쪽으로, 즉 메서드 -> 리소스 -> 서비스 -> 프로바이더 서비스 -> 프로바이더 순서로 결정됩니다. 따라서 프로바이더 전체의 기본값을 하나의 리소스나 메서드에 대해 재정의할 수 있습니다.

프로바이더가 처리하는 기능​

프로바이더는 API의 복잡성을 추상화하는 기능을 담당하므로, 사용자는 기본 HTTP 통신을 관리하지 않고도 일관된 SQL 인터페이스를 사용할 수 있습니다.

인증​

각 프로바이더에는 자격 증명을 담은 환경 변수의 이름을 지정하는 기본 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}. OData @odata.nextLink 속성에는 algorithm: odata_next_link 설정을 사용합니다.
  • RFC 5988 Link 헤더: responseToken: {key: Link, location: header}.
  • 페이지 수가 있는 페이지 번호: algorithm: page_number 설정에 responseToken 필드(현재 페이지)와 responseTerminator 필드(전체 페이지 수)를 함께 지정합니다.

다음 마커가 없는 오프셋 및 제한 방식의 API는 페이지네이션 방식이 아닙니다. 대신 offset 및 limit 매개 변수를 WHERE 절의 매개 변수로 노출하세요. --http.response.pageLimit 전역 플래그로 순회 범위를 제한합니다.

조건자 푸시다운​

WHERE 절의 키는 작업에 선언된 매개 변수와 이름으로 비교되어(경로, 그다음 쿼리, 헤더, 쿠키 순) API로 전송되므로, 필터링이 소스에서 이루어집니다. 일치하는 매개 변수가 없는 나머지 WHERE 키는 쿼리 매개 변수로 추가됩니다.

일반 매개 변수 외에도 queryParamPushdown 설정은 SELECT 열, WHERE, ORDER BY, LIMIT, OFFSET, COUNT를 API 매개 변수로 다시 작성합니다. dialect: odata 설정은 Microsoft Graph 및 Azure 스타일 API에서 사용하는 $select, $filter, $orderby, $top, $skip, $count 기본값을 채웁니다. dialect: custom 설정은 paramName 값을 그대로 사용하며, 가장 일반적인 예는 LIMIT n을 ?limit=n으로 바꾸는 top: {paramName: limit, maxValue: 1000}입니다. 푸시다운할 수 없는 조건자는 여전히 클라이언트 측에서 평가됩니다.

응답 및 요청 변환​

  • response.objectKey 키는 엔벨로프에서 행을 담은 항목을 선택하는 JSONPath(XML API의 경우 XPath)입니다. 예를 들어 $.data[*] 또는 $.value입니다.
  • response.transform 키는 본문이 행으로 스테이징되기 전에 Go 텍스트 템플릿을 적용합니다. 변환 형식은 JSON, XML, 일반 텍스트를 다루며, 이를 통해 AWS XML API와 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 이외의 프로바이더​

provider.yaml 파일의 protocolType: local_templated 설정은 HTTP 대신 로컬 명령으로 프로바이더를 구현합니다. 메서드는 Go 템플릿 argv 조각의 inline 배열을 가지고, 매개 변수는 in: inline 설정을 사용하며, response.transform 키가 명령 출력을 행으로 변환합니다. any-sdk의 local_openssl 참조 프로바이더에서 그 형태를 볼 수 있습니다. 이 방식은 HTTP API를 대상으로 하는 템플릿 파이프라인의 범위에 포함되지 않습니다.

프로바이더 프로젝트 시작​

모든 새 프로바이더는 stackql-provider-TEMPLATE에서 시작하세요. 이 리포지토리는 프로바이더의 현재 표준을 담은 GitHub 템플릿 리포지토리입니다. 고정된 업스트림 사양, 모든 수동 결정이 생성된 YAML의 직접 편집이 아니라 스크립트의 규칙으로 표현되는 결정적 빌드 파이프라인, 자격 증명이 필요 없는 3개의 테스트 계층, 예산이 정해진 라이브 스모크 테스트 모음, Docusaurus 문서 사이트, CI가 포함됩니다. 이 방식으로 빌드되어 게시된 프로바이더는 stackql-registry GitHub 조직에 있으며, 템플릿과 함께 참고 자료로 유용합니다.

사전 요구 사항: Node.js 20 이상, GNU make 및 bash(Linux, macOS 또는 WSL), 스모크 테스트 모음용 Python 3, 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

내부적으로 파이프라인은 provider-dev/scripts/ 디렉터리의 프로바이더별 규칙과 함께 @stackql/provider-utils 패키지(split, normalize, analyze, generate, docgen)를 사용합니다. 생성된 프로바이더는 provider-dev/openapi/src/<name>/v00.00.00000/ 디렉터리에 저장되며, 이 디렉터리가 최종적으로 레지스트리에 게시됩니다.

provider-dev/config/all_services.csv 파일은 모든 작업과 리소스 및 메서드 간 매핑에 대해 커밋된 계약입니다. 재생성 시 생기는 diff는 노이즈가 아니라 호환성이 손상되는 변경으로 검토해야 할 대상입니다. 커밋되지 않은 생성 드리프트가 있으면 CI가 실패하므로, 재생성은 커밋된 아티팩트를 바이트 단위로 정확히 재현해야 합니다.

템플릿보다 먼저 만들어진 기존 프로바이더 리포지토리의 경우 .claude/skills 디렉터리를 해당 리포지토리에 복사하고 스킬의 references/uplift-checklist.md 파일부터 시작하세요.

Claude Code를 사용한 프로바이더 개발​

템플릿에는 Claude Code용 StackQL 프로바이더 개발 스킬이 번들로 포함되어 있습니다. 템플릿에서 만든 리포지토리에서 Claude Code 세션을 열고 프로바이더를 빌드하도록 요청합니다. Claude Code는 CLAUDE.md 파일과 스킬을 읽어 들이고 단계를 순서대로 진행합니다. 이 스킬은 작업을 직접 수행하기 위한 문서화된 절차이기도 합니다.

이 스킬은 다음을 다룹니다:

  • 아키타입 선택: 공급업체가 게시한 OpenAPI, Swagger 또는 디스커버리 문서(직접), 또는 SDK가 단일 정보 출처인 경우 공급업체 SDK에서 파생한 사양(파생)
  • 모든 새로 고침이 검토 가능한 diff가 되도록 업스트림 사양을 가져오고, 수정하고, 검증하고, 고정하는 작업
  • 엔드포인트 인벤토리, 서비스 분할, all_services.csv 파일을 생성하는 매핑 규칙
  • 모든 프로바이더 문서 기본 요소와 그 사용 시기: x-stackQL-envVar 범위 지정, objectKey, 요청 및 응답 변환, 페이지네이션, 쿼리 매개 변수 푸시다운, 수명 주기 EXEC 메서드, GraphQL 병합, 프로바이더 뷰
  • 자격 증명이 필요 없는 3개의 테스트 계층과 라이브 스모크 테스트 모음
  • 문서 사이트, CI 워크플로, 인수인계 노트

스킬의 references/ 디렉터리에는 각 단계의 세부 정보가 있습니다. 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 ..." 명령은 모의 API에 대해 애드혹 SQL을 실행하고 와이어 호출을 출력합니다.

원격 레지스트리에서 가져온 프로바이더는 기본적으로 <cwd>/.stackql 디렉터리에 캐시됩니다. 위치를 변경하려면 --approot 플래그를 사용하세요.

any-sdk CLI는 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 대상은 게시 후 검증을 위해 게시된 프로바이더에 대해 스모크 테스트 모음을 실행합니다.

프로바이더 게시​

게시는 사람이 직접 참여하는 별도의 단계이며 템플릿 파이프라인에 포함되지 않습니다.

  1. stackql-provider-registry를 포크하고, 기능 브랜치에서 생성된 provider-dev/openapi/src/<name> 디렉터리를 providers/src/<name> 경로에 복사합니다.
  2. 프로바이더와 변경 사항에 대한 설명을 포함하여 dev 브랜치를 대상으로 끌어오기 요청을 만듭니다(레지스트리의 기여 가이드 참조).
  3. GitHub Actions는 stackql-provider-tests를 사용하여 프로바이더를 검증하고 테스트합니다. 평가되는 규칙은 다음과 같습니다. 문서는 유효한 OpenAPI 사양이어야 합니다. 모든 서비스에서 리소스를 열거할 수 있어야 하고, 모든 리소스에서 메서드를 열거할 수 있어야 합니다. SELECT 문으로 호출할 수 있는 메서드에는 유효한 응답 스키마가 있어야 하고, INSERT 문으로 호출할 수 있는 메서드에는 유효한 요청 스키마가 있어야 합니다.
  4. 병합되면 워크플로가 버전을 할당하고, 문서에 서명(ML-DSA-65)하고, 패키징한 후 아티팩트를 AWS S3 아카이브에 게시합니다. 그런 다음 문서 트리가 Cloudflare R2로 미러링되고 registry-dev.stackql.app에서 서비스하는 Cloudflare Worker가 배포됩니다. 프로바이더는 dev 레지스트리를 사용하도록 구성된 설치에서 즉시 사용할 수 있습니다.
  5. 일정 기간 모니터링한 후 dev 브랜치가 main 브랜치로 승격되며, 이때 registry.stackql.app에 대해 게시가 반복됩니다. 이것이 기본 구성된 StackQL 인스턴스에 대한 게시입니다.

PR을 만들기 전에 동일한 stackql-provider-tests 하네스를 레지스트리 디렉터리에 대해 로컬에서 실행할 수 있습니다:

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

providers/src 디렉터리를 보호하는 프로바이더 삭제 가드를 포함한 워크플로의 자세한 내용은 레지스트리 리포지토리의 빌드 및 배포를 참조하세요.