게이트웨이 마스터하기: 프로토콜, 프록시, 그리고 현대적 메시

SchemaBridge Team · 2026-01-14 · Protocols, REST, API

파편화된 클라우드를 위한 하나의 구성 가능한 HTTP 게이트웨이: 상한이 있는 재시도, 목적지별 레이트 리밋, 송신 시점에 주입되는 시크릿.

프로토콜 수프: 끝없는 파편화의 시대를 살아가기

하이프를 믿는다면 세상은 온통 JSON을 쓰는 HTTPS 위의 RESTful입니다. 진짜 하이프를 믿는다면 세상은 GraphQL이나 gRPC로 옮겨 가고 있습니다. 하지만 현대 기업 IT 환경의 현실을 보면, 세상은 40년에 걸친 아키텍처 유행이 뒤섞인 어수선하고 조율되지 않은 프로토콜 수프입니다.

한 조직 안에도 아마 다음이 모두 있을 것입니다.

통합이란 이 프로토콜 수프 위에 다리를 놓는 기술입니다. 전통적으로 이는 "어댑터 서비스", 즉 HTTP 호출 하나만 하는 작고 깨지기 쉬운 Node나 Go 프로그램을 작성하는 일을 뜻했습니다. 우리는 이를 "글루 코드"라고 불렀고(글루 코드 위기 참고), 이는 엔지니어링 속도에 막대한 부담입니다.

SchemaBridge는 이 문제를 Managed Gateway로 해결합니다. REST 스타일 API를 위한 구성 가능한 HTTP 게이트웨이로, 비즈니스 로직을 특정 엔드포인트 구현으로부터 분리합니다. 이는 의도적으로 하나의 프로토콜을 제대로 다루는 것입니다(GET, POST, PUT, DELETE를 사용하는 HTTP). GraphQL, gRPC, SOAP 클라이언트는 내장되어 있지 않으므로, 그런 엔드포인트는 HTTP 표면을 통해 접근하거나 아예 접근하지 못합니다.

Managed Gateway의 아키텍처

SchemaBridge 게이트웨이는 단순한 프록시 이상입니다. 인프라의 "연결 유지 관리", 즉 재시도, 레이트 리밋, 자격 증명을 담당하는 중개자입니다.

응답 정규화: JSONata 우선 접근법

응답을 파싱하는 코드를 작성하는 대신, 게이트웨이를 TRANSFORMATION 단계와 짝지어 사용합니다.

1. 호출: GATEWAY vertex가 외부 서비스를 호출하고 결과를 response.statusCode와 response.body로 돌려줍니다. JSON 본문은 파싱된 상태로 오고, 그 밖의 것은 원시 문자열로 옵니다.

2. 매핑: 다운스트림 JSONata 변환이 워크플로에 필요한 특정 필드를 추출하고 재구성합니다.

이를 일관되게 적용하면, 나머지 시각적 로직은 기반 소스의 구조와 관계없이 여러분이 정의한 깔끔한 형태만 보게 됩니다.

적응형 재시도 정책: "3회 재시도" 그 너머

대부분의 개발자는 "고정 재시도" 정책, 즉 1초 간격으로 3번 재시도하는 방식을 씁니다. 이는 득보다 실이 많은 경우가 많습니다. 서비스가 부하 때문에 다운된 상황이라면, 매초 재시도하는 워커 무리는 조직적인 DDoS 공격처럼 작동해 서비스의 회복을 막습니다.

SchemaBridge 게이트웨이는 백오프를 적용하고, 정해진 범위 안에서 재시도합니다.

HTTP 재시도 후에도 공급자가 과부하 상태라면, 해당 단계는 수용 제어를 거쳐 몇 번 더 재디스패치됩니다(maxAutoRetries, 기본값 3). 그 후에도 공급자가 계속 실패하면, 해당 단계는 영원히 루프를 도는 대신 눈에 보이게 실패하며, 공급자가 복구된 뒤 재시도할 수 있습니다.

레이트 리밋 전쟁 관리하기: 전역 동시성 제어

모든 SaaS 공급자에게는 레이트 리밋이 있습니다. 어떤 것은 단순합니다(초당 10건 요청). 100개의 워커가 통합을 실행하고 있다면, 이들은 한도 아래에 머물기 위해 어떻게 조율할까요?

각 워커가 자기 속도를 따로 추적하려 하면, 필연적으로 한도를 넘어 차단됩니다. SchemaBridge는 디스패치 시점에 적용되는 워크스페이스 전역의 목적지별 한도를 제공합니다.

비교: 전통적인 API 게이트웨이 vs. SchemaBridge 게이트웨이

| 기능 | API 게이트웨이(Apigee/Kong) | SchemaBridge Managed Gateway |

| :--- | :--- | :--- |

| 초점 | 인바운드 트래픽(남북) | 아웃바운드(이그레스) 비즈니스 호출 |

| 상태 | 주로 요청 단위(카운터, 캐시) | 영속화된 실행 위에서의 상한 있는 재시도 |

| 로직 | 스크립팅(Lua/JS) | 시각적(JSONata) |

| 아이덴티티 | 인증 검증 | 송신 시점에 주입되는 시크릿({{ secrets.NAME }}) |

페이로드 정규화: 어댑터 서비스의 종말

이 시리즈의 앞부분에서 이야기했듯이, 데이터를 변환하기 위해 전용 서비스를 작성하는 것은 시니어 엔지니어링 인재의 낭비입니다. 게이트웨이를 공유 변환과 짝지으면 정규화는 연결의 속성이 됩니다.

두 가지 기본 요소가 이 재사용을 현실로 만듭니다. custom app은 공급자의 연결 설정(기본 URL, 헤더, 인증)을 워크스페이스에 한 번만 등록해, 그것을 사용하는 모든 게이트웨이에 미리 채워 줍니다. 영속화된 변환 규칙은 매핑을 ruleId 아래에 한 번만 등록해, 같은 레거시 ERP와 통신하는 모든 워크플로가 이를 공유하게 합니다. "기술적 오버헤드"는 플랫폼으로 옮기고, "비즈니스 로직"은 깔끔하고 시각적으로 유지한 것입니다.

예시 시나리오: 레거시 API를 현대 웹으로 이식하기

주문 관리 시스템을 현대화하고 있는 다국적 유통 그룹을 생각해 봅시다.

과제

핵심 재고 데이터가 수천 개 매장에 걸친 불안정한 레거시 시스템에 있고, 새 이커머스 프런트엔드는 React/Next.js 앱이라고 상상해 보세요. 손으로 작성한 "어댑터 마이크로서비스" 묶음으로 두 세계를 잇는 일은 여러 분기에 걸친 대규모 작업이 될 것입니다.

SchemaBridge 방식

대신 팀이 SchemaBridge의 게이트웨이 기본 요소를 활용한다고 그려 봅시다.

1. 게이트웨이 구성: 코드를 작성하는 대신, 레거시 시스템을 SchemaBridge의 custom app으로 구성하고, 자격 증명은 암호화된 시크릿 저장소에 보관합니다.

2. 시각적 로직: 제품 팀이 "Check Inventory"의 시각적 그래프를 직접 구축합니다.

3. 내장된 복원력: 게이트웨이의 백오프 재시도가 레거시 시스템의 짧은 일시적 장애를 흡수하고, 목적지별 한도가 프런트엔드 트래픽이 레거시 시스템을 압도하지 않도록 막습니다.

그럴듯한 결과

미래: 프로토콜에 구애받지 않는 기업

API의 구체적인 프로토콜은 로드맵을 막는 장애물이 아니라 구현 세부 사항이어야 합니다. 게이트웨이 마스터리 모델로 나아감으로써 우리는 "레거시의 유령"에서 벗어납니다. 비즈니스 로직은 깔끔하고 계층적인 진실의 토대 위에 세우고, 파편화된 클라우드의 어수선한 현실은 인프라가 처리합니다.

게이트웨이 설계를 위한 전문가 체크리스트

통합 계층을 설계할 때는 아웃바운드 연결에 대해 다음 휴리스틱을 따르세요.

1. 프로토콜을 격리하라: 비즈니스 로직에는 프로토콜별 구현 세부 사항이 절대 들어가서는 안 됩니다. 이를 게이트웨이와 그 변환 단계로 추상화하세요.

2. 자격 증명을 금고에 넣어라: 인증 헤더를 구성에 직접 붙여 넣지 마세요. {{ secrets.NAME }}으로 참조해, 요청이 플랫폼을 떠날 때에만 토큰이 주입되도록 하세요.

3. 백오프하고, 상한을 두라: 그냥 "1초 뒤에 다시 재시도"하지 마세요. 지수 백오프를 사용하고, Retry-After를 준수하고, 목적지별로 동시성을 제한하세요. 클라이언트를 직접 제어한다면 지터도 추가해 동기화된 재시도를 분산시키세요.

결론: 다리는 곧 게이트웨이다

인프라란 로직이 순수할 수 있도록 어수선한 세부 사항을 처리하는 기술입니다. 게이트웨이 마스터리는 엔지니어링 속도를 과거의 기술 부채로부터 분리하는 마지막 단계입니다. 어댑터 작성을 멈추고 다리를 놓기 시작하세요.

"Building the Bridge" 시리즈의 관련 글: 오류 복구. 장애를 일급 비즈니스 라이프사이클로 다루는 방법에 대해.

살펴보기