본문으로 건너뛰기
OpenAPI로 다시 설계한 Cloudflare SDK 파이프라인
목차

OpenAPI로 다시 설계한 Cloudflare SDK 파이프라인 (2024-04)

원문 정보

작은 변경에도 최소 PR 4개가 필요했던 SDK

API에 새 기능이 생겨도 쓰던 언어의 SDK에 들어오지 않으면, 그 SDK로 API를 호출하는 사용자에게는 없는 기능이나 마찬가지입니다. 수작업으로 SDK를 관리하던 Cloudflare의 고민이었습니다. 제품 팀이 변경을 보태도 모든 언어까지 챙기지는 못했고, 나머지는 커뮤니티 기여나 라이브러리 관리자에게 의존했습니다.

내부 팀도 같은 불편을 겪었습니다. 적어도 하나는 제대로 유지하자는 생각으로 Go SDK에 노력을 모았고, 새 제품을 지원하고 Terraform Provider를 대체로 최신 상태로 유지하는 데는 효과가 있었습니다. 그래도 부담은 컸습니다. 아무리 작은 변경이라도 배포까지 최소 4개의 pull request(PR)를 조율해야 했고, 그 의존성 관계도 깊이 알아야 했습니다. 사람이 일일이 고치는 만큼 지원 범위와 언어 간 동등한 지원, 정확성을 보장하지도 못했습니다.

JSON Hyper-Schema에서 OpenAPI로 전환을 마친 뒤 새로운 길이 보였습니다. 문서화에 쓰던 스키마로 SDK까지 생성하기로 한 것입니다.

생성 코드보다 먼저 쓴 언어별 사용법

생성기를 어떤 언어로 만들었는지 SDK에 드러나서는 안 된다는 원칙부터 세웠습니다. Ruby에서는 do_something if bar?라고 쓸 수 있지만, 대부분의 생성기는 같은 뜻을 여러 줄 if/else로 풀어 씁니다. 사소해 보이는 차이입니다. 하지만 이런 차이가 쌓이면 개발자는 익숙한 언어 기능을 쓰는 대신 생성기가 만든 방식에 맞춰 코드를 고쳐야 합니다. 강타입 언어로 타입 없는 언어의 SDK를 생성할 때는 쓰이지도 않을 타입을 전제로 코드를 구성하는 문제가 더 두드러집니다.

Cloudflare는 생성 코드를 한 줄도 쓰기 전에 README 주도 설계에 따라 대상 언어별 사용법을 문서로 만들었습니다. Python 키워드 인자, Go 인터페이스, 필수 매개변수 강제, 클라이언트 생성과 재정의, 타입을 이 단계에서 검토했습니다. 문서만으로도 사용자가 마주할 문제를 미리 발견하고, 구현에 들어갈 때 남아 있는 불확실성을 줄였습니다.

언어의 관용구는 살리되 기능을 찾는 경로는 일정해야 했습니다. DNS 레코드 목록이라면 어느 SDK에서나 dns 네임스페이스 아래 list 메서드를 찾을 수 있어야 합니다. Go의 client.DNS.Records.List(...)와 TypeScript·Python의 client.dns.records.list(...)가 그 예입니다. 호출법을 찾느라 문서를 뒤지는 시간을 줄이고, 익숙한 도구에서 새 기능을 쓸 수 있게 하려는 선택입니다.

생성 엔진을 맡긴 Stainless

생성기를 직접 만들면 고품질 SDK 하나를 내놓는 데만 최소 6~9개월이 걸릴 것으로 봤습니다. 언어를 추가할 때마다 후속 작업이 생길 가능성도 있었습니다. 새 언어를 낮은 비용으로 지원하려는 목표와는 맞지 않았습니다.

기성 도구도 쉽게 들어맞지는 않았습니다. Cloudflare의 스키마가 크고 복잡했기 때문입니다. 여러 도구와 우회 방법을 시험한 끝에 선택한 곳은 SDK 생성 전문 회사 Stainless였습니다. Stripe에서 API 경험을 만들던 엔지니어가 설립했으며, OpenAI의 Python·TypeScript SDK도 이 생성기로 만들어졌습니다.

입력은 OpenAPI 스키마와 매핑 설정입니다. 설정에서 get /zones를 zones 리소스의 list 메서드에 연결하면 각 SDK에 client.zones.list()에 해당하는 호출이 생깁니다. 대부분의 변경은 API 스키마에서 처리하고, 특정 SDK만의 문제는 설정 파일에서 해당 SDK의 동작을 조정합니다. 어디를 누가 고쳐야 하는지도 분명해졌습니다.

  • 서비스 팀: 사용자에게 보일 서비스 표현 관리
  • API 팀: API·SDK 규약 구현, 공통 도구 구축, Stainless에 맞춘 서비스 매핑
  • Stainless: 일관된 SDK를 생성하는 인터페이스 제공

Cloudflare는 생성 엔진 대신 서비스를 정확히 설명하는 스키마에 집중할 수 있었습니다. 몇 달 만에 TypeScript, Go, Python SDK를 자동 배포하게 됐고, Developer Week 2024에서 이 SDK들의 제공을 발표했습니다. 내부 팀의 변경이 별도의 수작업 없이 전달되면서 대부분의 변경은 PR 하나로 끝납니다. 파이프라인에 새 언어나 통합을 추가하더라도 대부분의 변경에 필요한 PR 수는 그대로입니다.

스키마의 차이를 한꺼번에 고치는 코드모드

자동 생성에 앞서 스키마의 관행과 구조, 사용자에게 보일 표현을 맞춰야 했습니다. 일관성이 있어야 오류의 출처도 구분하기 쉽습니다. 모든 곳에서 깨지면 생성 파이프라인의 문제이고, 특정 부분만 깨지면 개별 스키마의 문제로 좁힐 수 있습니다. 라우트가 늘 복수형 리소스 이름 뒤에 식별자를 두는 식으로 일정하면, 사용자는 문서가 부족해도 어떤 입력이 필요한지 짐작할 수 있습니다.

고칠 대상은 많았습니다. 당시 공개 문서에 실린 엔드포인트만 약 1,300개여서 파일을 하나씩 수정하는 방식으로는 감당하기 어려웠습니다. Cloudflare는 코드의 문법 맥락까지 살피는 강력한 찾기·바꾸기 도구인 코드모드를 사용했습니다.

처음에는 comby를 버전 관리 엔드포인트와 통신하는 자체 CLI로 감쌌습니다. 변환마다 TOML 설정, PR 설명, 커밋 메시지를 받아 처리하도록 했습니다. account_identifier나 accountId처럼 제각각이던 식별자 표기를 account_id로 맞추는 작업이 한 예입니다.

comby는 내부 변경 대부분을 처리했지만, 표현식이 복잡해질수록 익숙하지 않은 사람이 문법을 읽기 어려웠습니다. 고객이 직접 SDK를 마이그레이션할 도구도 원했던 Cloudflare는 Grit를 선택했습니다. 필요한 CLI 기능을 갖췄고, GritQL은 JavaScript 기초를 아는 사람에게 친숙한 질의 언어였습니다. Grit Pattern Library에 마이그레이션 패턴을 기여하면 고객도 가져다 쓸 수 있습니다. CLI를 설치한 뒤 grit apply cloudflare_go_v2를 실행하는 방식입니다.

변경을 제안하는 순간 규약을 확인하는 CI

기존 표기를 맞추는 작업만으로는 부족했습니다. 트래픽 급증이나 잘못된 입력을 자주 겪는 주요 API는 드물게 쓰이는 API보다 더 견고했고, API마다 설계 규약도 달랐습니다. 한 팀이 얻은 교훈을 다른 팀도 변경을 제안하는 시점부터 쉽게 따를 수 있어야 했습니다.

Cloudflare는 OpenAPI 스키마 파이프라인에 redocly CLI 린트를 넣었습니다. 위반의 심각도에 따라 경고하거나 변경을 차단합니다. 예를 들어 세분화된 권한의 API 토큰 사용을 장려하기 위해, 인증 옵션에 api_token이 정의돼 있고 첫 번째로 나오는지 검사하는 플러그인을 작성했습니다. 이 규칙을 어기면 CI가 실패하며, 실패 메시지에는 배경을 확인할 규약 링크가 붙습니다.

문서 스타일도 같은 자리에서 검사합니다. 설명이 대문자로 시작하고 마침표로 끝나야 한다는 규칙이 그 예입니다. 팀마다 과거의 API 설계 규약을 찾아 읽게 하는 대신, 변경 중인 스키마에서 바로 피드백을 받게 했습니다.

오타를 놓치기 쉬운 공유 $ref

원문이 든 예시에서 created_at은 실수로 thing_updated_at을 참조합니다. 필드 이름만 보면 지나치기 쉽습니다. 생성 시각을 설명할 자리에 수정 시각의 설명이 붙지만, 참조를 따라가 보기 전에는 잘 드러나지 않습니다. 여기서는 문서 설명이 틀리는 정도에 그쳐도, 다른 경우에는 스키마가 표현하는 내용 자체가 틀릴 수 있습니다.

공유 $ref는 처음 작성할 때 재사용하기 좋아 보입니다. 지나치게 쓰면 올바른 값을 찾기 어려워지고, 의미를 살피지 않은 채 기존 참조를 따라 쓰는 관행이 생깁니다. 결과는 품질이 낮고 수정하기 어려운 스키마입니다.

Cloudflare는 여러 컴포넌트 스키마를 oneOf, allOf, anyOf로 조합할 때 주로 $ref를 사용합니다. 참조로 분리할지 애매할 때는 YAGNI 원칙을 권합니다. 사용례가 충분히 쌓여 적절한 추상화를 판단할 수 있을 때 분리해도 늦지 않다는 뜻입니다.

SDK 다음의 생성 대상인 Terraform Provider

2024년 4월 당시 Cloudflare는 같은 원칙으로 Terraform Provider도 생성해 유지보수 부담을 더 줄이려 했습니다. 2024년 안에 Cloudflare 개발자 플랫폼의 다른 부분과 연결하는 개선과 통합도 예고했습니다. 다음에 지원할 SDK 언어를 고르는 데 참고하려고 사용자 요청도 받고 있었습니다.

수치와 도구
항목값
기존 변경 1건당 필요한 PR최소 4개
변경 1건당 필요한 PR(자동화 후)대부분 1개
자체 구축 시 예상 기간고품질 SDK 하나까지 최소 6~9개월
공개 문서화된 엔드포인트약 1,300개
제공 SDK 언어TypeScript, Go, Python
코드모드 도구comby에서 Grit(GritQL)로 이동
스키마 린트redocly CLI
마지막 수정 일자