Zuplo에 대해 읽어보셨고 실제 서비스를 구축하고 싶으시다면, 이 글이 바로 여러분을 위한 것입니다. 이 플랫폼은 배우기 쉽지만, 문서는 포털 흐름, CLI 명령 및 학습 센터 기사에 분산되어 있습니다. 이 가이드는 조각들을 하나의 튜토리얼로 엮어냅니다: 프로젝트 생성, 경로 노출, API 키 인증 및 속도 제한 추가, 커스텀 TypeScript 정책 작성, 엣지 배포, 그리고 Apidog로 전체 테스트.
이 글을 마치면 인증, 속도 제한, 자동 생성된 개발자 포털, 그리고 CI 친화적인 Git 워크플로우를 갖춘 API 게이트웨이가 원본 앞에 실행될 것입니다. 전체 과정은 약 30분 정도 소요됩니다.
아직 Zuplo가 적합한 도구인지 고민 중이시라면, 저희의 관련 게시물인 Zuplo API 게이트웨이란 무엇인가부터 시작하십시오. 다른 모든 것에 대해서는 Zuplo 문서에서 이 가이드가 생략하는 예외 사항들을 다룹니다.
요약 (TL;DR)
- portal.zuplo.com에서 가입하거나
npm create zuplo로 로컬 프로젝트를 스캐폴딩하세요. config/routes.oas.json에 경로를 정의하고 URL 전달 핸들러를 사용하여 원본으로 전달합니다.- 경로 파일을 편집하거나 경로 디자이너를 클릭하여 인바운드 정책(API 키 인증, 속도 제한, 스키마 유효성 검사)을 추가합니다.
modules/에 TypeScript 모듈로 사용자 지정 로직을 작성합니다. 런타임은 요청, 컨텍스트 및 환경에 대한 유형화된 액세스를 제공합니다.- 연결된 Git 브랜치에 푸시하여 미리보기 환경을 배포합니다. 300개 이상의 엣지 위치에 배포하려면 병합합니다.
- 운영 환경으로 승격하기 전에 Apidog로 모든 경로를 테스트합니다.
- 가격은 월 10만 요청 무료로 시작합니다. 빌더 플랜은 월 25달러입니다.
사전 요구 사항
시작하기 전에 세 가지가 필요합니다:
- Zuplo 계정
- 게이트웨이를 앞에 둘 원본 API. 없으시다면, 보내는 모든 것을 그대로 반환하는
https://echo.zuplo.io를 사용하십시오. - CLI를 사용할 계획이라면 Node.js 18 이상.
로컬 개발을 위해서는 코드 편집기도 필요합니다. TypeScript 확장이 있는 VS Code가 가장 쉬운 방법이며, Apidog VS Code 확장과 함께 사용하여 편집기를 벗어나지 않고 요청을 보낼 수 있습니다.
1단계: Zuplo 프로젝트 생성
시작하는 방법은 두 가지입니다: 웹 포털 또는 CLI. 대부분의 팀은 데모하기 빠르기 때문에 포털에서 시작한 다음, CI/CD를 원할 때 CLI로 전환합니다.
옵션 A: 포털 우선
- portal.zuplo.com에 로그인합니다.
- “새 프로젝트”를 클릭하고
acme-gateway와 같은 이름을 선택합니다. - 아무것도 자동으로 생성되지 않도록 “빈 프로젝트”를 선택합니다.
- 코드 탭에 시작 파일 트리가 열립니다.
포털은 기본적으로 프로젝트를 관리형 Git 리포지토리에 연결합니다. 나중에 설정에서 자체 GitHub, GitLab, Bitbucket 또는 Azure DevOps 리포지토리를 연결할 수 있습니다.
옵션 B: CLI 우선
CLI는 동일한 프로젝트 레이아웃을 로컬에 스캐폴딩하여 IDE에서 편집하고 첫날부터 Git을 사용할 수 있도록 합니다.
npm create zuplo@latest -- --name acme-gateway
cd acme-gateway
npm install
npm run dev
개발 서버는 9000번 포트에서 시작하며 http://localhost:9100의 로컬 경로 디자이너 링크를 출력합니다. 편집기나 디자이너에서 변경하는 모든 내용은 즉시 핫-리로드됩니다.
배포 준비가 되면 로컬 프로젝트를 Zuplo 계정에 연결하려면:
npx zuplo link
요청 시 계정과 환경을 선택합니다. 여기에서 npx zuplo deploy는 현재 Git 브랜치를 배포합니다.
2단계: 첫 번째 경로 정의
config/routes.oas.json을 엽니다. 이것은 핸들러와 정책을 위한 Zuplo 확장이 포함된 OpenAPI 3 문서입니다. GET /v1/products를 원본으로 전달하는 경로를 추가합니다:
{
"openapi": "3.1.0",
"info": { "title": "Acme Gateway", "version": "1.0.0" },
"paths": {
"/v1/products": {
"get": {
"summary": "제품 목록",
"operationId": "list-products",
"x-zuplo-route": {
"corsPolicy": "anything-goes",
"handler": {
"export": "urlForwardHandler",
"module": "$import(@zuplo/runtime)",
"options": {
"baseUrl": "${env.ORIGIN_URL}"
}
},
"policies": { "inbound": [] }
},
"responses": {
"200": { "description": "성공" }
}
}
}
}
}
주목할 만한 몇 가지 세부 사항이 있습니다. x-zuplo-route 확장은 다른 일반 OpenAPI 파일 내에서 Zuplo가 존재하는 곳입니다. handler는 경로가 일치할 때 발생하는 일을 설명합니다. urlForwardHandler는 내장 프록시입니다. ${env.ORIGIN_URL} 참조는 환경 변수에서 가져와서 환경별로 다른 백엔드를 대상으로 할 수 있도록 합니다.
포털의 설정 > 환경 변수에서 ORIGIN_URL을 설정하거나 로컬에서 config/.env를 편집하여 설정합니다. 아직 실제 원본이 없으면 https://echo.zuplo.io를 사용하십시오.
저장하면 로컬 개발 서버가 다시 로드됩니다. http://localhost:9000/v1/products로 접속하면 에코된 요청을 볼 수 있습니다. 배포된 게이트웨이는 가장 가까운 엣지 데이터 센터에서 응답할 것입니다.
3단계: API 키 인증 추가
공개 API에는 자격 증명이 필요합니다. Zuplo는 자체적으로 키 저장소를 구축할 필요가 없도록 관리형 API 키 서비스를 제공합니다.
인바운드 정책을 추가하도록 경로를 편집합니다:
"policies": {
"inbound": ["api-key-auth"]
}
그런 다음 config/policies.json에 정책 정의를 추가합니다(Zuplo는 정책을 처음 추가할 때 이 파일을 생성합니다):
{
"name": "api-key-auth",
"policyType": "api-key-inbound",
"handler": {
"export": "ApiKeyInboundPolicy",
"module": "$import(@zuplo/runtime)",
"options": {
"allowUnauthenticatedRequests": false
}
}
}
이제 컨슈머(하나 이상의 API 키를 소유하는 엔티티)를 생성합니다:
- 포털의 서비스 > API 키 서비스로 이동합니다.
- “컨슈머 생성”을 클릭합니다.
- 주체를
acme-customer-1과 같은 안정적인 식별자로 설정합니다. - 키를 관리해야 하는 사람의 이메일을 추가합니다.
- 생성된 API 키를 복사합니다.
curl로 테스트합니다. 헤더가 없으면 401을 볼 수 있습니다:
curl -i https://YOUR-PROJECT.zuplo.app/v1/products
# HTTP/2 401
헤더가 있으면 원래 200 응답을 볼 수 있습니다:
curl -i https://YOUR-PROJECT.zuplo.app/v1/products \
-H "Authorization: Bearer YOUR_API_KEY"
# HTTP/2 200
실제 클라이언트에서 이 작업을 수행하고 싶다면, 게이트웨이의 OpenAPI 스펙을 Apidog로 가져와 Authorization: Bearer {{api_key}}에 대한 전역 헤더를 설정하고 api_key를 환경 변수에 바인딩하십시오. 모든 경로에 대한 깔끔한 테스트 환경을 몇 초 만에 얻을 수 있습니다.
4단계: 경로에 속도 제한 적용
속도 제한 없이 공개 API를 배포하지 마십시오. 기본 Zuplo 속도 제한 정책은 IP당, 키당 또는 사용자 지정 속성당 스로틀링을 제공합니다.
인증 후 인바운드 목록에 추가합니다:
"policies": {
"inbound": ["api-key-auth", "rate-limit-by-key"]
}
config/policies.json에 정의합니다:
{
"name": "rate-limit-by-key",
"policyType": "rate-limit-inbound",
"handler": {
"export": "RateLimitInboundPolicy",
"module": "$import(@zuplo/runtime)",
"options": {
"rateLimitBy": "sub",
"requestsAllowed": 60,
"timeWindowMinutes": 1
}
}
}
rateLimitBy: "sub"는 API 키 정책에서 인증된 주체를 기준으로 버킷을 키 지정하므로, 각 고객은 자체적으로 분당 60개의 예산을 가집니다. 익명 트래픽을 스로틀링하려면 "ip"로 교체하십시오.
60초 이내의 61번째 요청은 재시도 헤더가 첨부된 429를 반환합니다. 70개의 요청을 루프에서 실행하고 응답 코드가 바뀌는 것을 보면서 테스트하십시오.
for i in {1..70}; do
curl -s -o /dev/null -w "%{http_code}\n" \
https://YOUR-PROJECT.zuplo.app/v1/products \
-H "Authorization: Bearer YOUR_API_KEY"
done | sort | uniq -c
60줄의 200과 10줄의 429가 표시될 것입니다.
5단계: 요청 페이로드 유효성 검사
JSON 본문을 사용하는 POST 경로가 있다면, 요청 유효성 검사 정책은 원본이 아닌 게이트웨이에서 잘못된 형식의 페이로드를 잡아냅니다. OpenAPI 작업에 내장된 JSON 스키마를 사용하므로, 스펙이 정확하면 이 기능을 무료로 얻을 수 있습니다.
요청 본문이 있는 경로를 추가합니다:
"/v1/products": {
"post": {
"summary": "제품 생성",
"operationId": "create-product",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"type": "object",
"required": ["name", "priceCents"],
"properties": {
"name": { "type": "string", "minLength": 1 },
"priceCents": { "type": "integer", "minimum": 1 },
"category": { "type": "string", "enum": ["food", "drink"] }
}
}
}
}
},
"x-zuplo-route": {
"handler": { /* 위와 동일 */ },
"policies": {
"inbound": [
"api-key-auth",
"rate-limit-by-key",
"validate-request"
]
}
}
}
}
정책을 추가합니다:
{
"name": "validate-request",
"policyType": "open-api-request-validation-inbound",
"handler": {
"export": "OpenApiRequestValidationInboundPolicy",
"module": "$import(@zuplo/runtime)",
"options": {
"validateBody": "reject"
}
}
}
이제 누락된 필드가 있는 POST는 원본에 도달하기 전에 400으로 거부됩니다. Apidog로 테스트하십시오. "성공 경로" 요청, "필수 필드 누락" 요청, "잘못된 열거형 값" 요청을 동일한 요청 그룹에 별도의 예제로 저장합니다. 한 번의 클릭으로 세 가지 모두를 실행할 수 있습니다.
6단계: 사용자 지정 TypeScript 정책 작성
미리 구축된 정책은 대부분의 팀이 필요로 하는 것을 다룹니다. 하지만 Zuplo의 핵심은 사용자 지정이 필요할 때입니다. 다음은 유료 고객에게는 Cache-Control 헤더를 추가하고 무료 고객에게는 no-store를 추가하는 아웃바운드 정책입니다.
modules/tiered-cache.ts를 생성합니다:
import { ZuploRequest, ZuploContext, HttpProblems } from "@zuplo/runtime";
interface PolicyOptions {
paidPlanHeader: string;
paidMaxAge: number;
}
export default async function (
response: Response,
request: ZuploRequest,
context: ZuploContext,
options: PolicyOptions,
): Promise<Response> {
const plan = request.user?.data?.plan ?? "free";
if (plan === "free") {
response.headers.set("Cache-Control", "no-store");
} else {
response.headers.set(
"Cache-Control",
`public, max-age=${options.paidMaxAge}`,
);
}
context.log.info(`Cache header set for plan=${plan}`);
return response;
}
이를 config/policies.json에 연결합니다:
{
"name": "tiered-cache",
"policyType": "custom-code-outbound",
"handler": {
"export": "default",
"module": "$import(./modules/tiered-cache)",
"options": {
"paidPlanHeader": "x-plan",
"paidMaxAge": 300
}
}
}
그리고 경로에서 참조합니다:
"policies": {
"inbound": ["api-key-auth", "rate-limit-by-key"],
"outbound": ["tiered-cache"]
}
사용자 지정 정책은 단순한 함수입니다. Vitest 또는 Jest로 단위 테스트할 수 있으며, 통합 하네스 없이 합성 Response와 ZuploRequest를 전달하고 헤더를 어설션할 수 있습니다.
7단계: 엣지에 배포
배포는 Git 푸시입니다.
git add .
git commit -m "인증, 속도 제한, 계층형 캐시를 포함한 제품 게이트웨이 추가"
git push origin feature/products-gateway
Zuplo는 모든 브랜치에 대한 미리보기 환경을 구축하고 빌드 로그에 URL을 출력합니다. 미리보기는 https://acme-gateway-feature-products-gateway-abc123.zuplo.app와 같은 자체 서브도메인을 얻으며, 해당 환경에 설정된 ORIGIN_URL을 가리키고 모든 정책이 활성화됩니다.
새로운 환경으로 설정하여 Apidog로 미리보기 URL을 테스트하십시오. 전체 테스트 스위트를 실행하십시오. 모든 것이 통과되면 브랜치를 병합하십시오.
git checkout main
git merge feature/products-gateway
git push origin main
병합은 프로덕션 배포를 트리거합니다. 60초 이내에 새 버전이 300개 이상의 엣지 위치에서 활성화됩니다. 승격 및 롤백은 모두 git push 작업이며, 별도의 UI는 없습니다.
8단계: 개발자 포털 생성
포털은 https://YOUR-PROJECT.developers.zuplo.com에서 호스팅되며 모든 배포 시 다시 빌드됩니다. 다음을 포함합니다:
- 스키마, 설명 및 사용해보기 콘솔이 있는 경로별 페이지.
- cURL, JavaScript, Python, Go 및 기타 언어로 된 코드 샘플.
- 가입하는 모든 방문자를 위한 셀프 서비스 API 키 발급.
- 포털의 개발자 포털 > 설정에서 브랜딩 제어.
OpenAPI 스펙에 좋은 설명과 예제가 있다면, 포털은 추가 작업 없이 완성된 것처럼 보입니다. 스펙이 얇다면, 이 순간에 그 사실을 알게 될 것입니다.
사용자 정의를 위해 포털 소스는 GitHub의 Zuplo 개발자 포털 리포지토리에서 포크할 수 있는 별도의 Next.js 앱으로 제공됩니다. 대부분의 팀은 호스팅된 버전을 사용합니다.
9단계: Apidog로 모든 것을 테스트
게이트웨이가 작동하면, 운영 사고를 방지하는 규율은 모든 경로, 모든 정책, 모든 오류 경로를 테스트하는 것입니다. Apidog는 이를 빠르게 만듭니다.
효과적인 워크플로우:
https://YOUR-PROJECT.zuplo.app/openapi에서 게이트웨이의 OpenAPI 스펙을 가져옵니다. Apidog는 각 작업을 실행할 수 있는 요청으로 변환합니다.local,preview,production환경을 생성하고, 각 환경에 자체base_url및api_key를 설정합니다.- 각 경로에 대해 최소 세 가지 요청을 저장합니다: 성공 경로, 인증 실패, 속도 제한 트리거. 모든 배포 전에 그룹으로 실행합니다.
- Apidog의 자동화된 테스트 시나리오를 사용하여 호출을 연결하고(제품 생성, 목록 조회, 삭제) 응답 형태를 어설션합니다.
- 팀의 기본 언어로 코드 샘플을 생성하고 런북에 붙여넣습니다.
Postman에서 마이그레이션하는 경우, Postman 없이 API 테스트 가이드가 가져오기 과정을 안내합니다. 아직 다운로드하지 않았다면 Apidog를 다운로드하십시오.
Zuplo 사용에 대한 일반적인 질문
스펙을 변경하지 않고 환경 간에 경로를 어떻게 전환합니까?
환경 변수를 사용하십시오. 포털 설정 또는 로컬 config/.env에 환경별로 ORIGIN_URL을 정의하고 핸들러 옵션 내에서 ${env.ORIGIN_URL}로 참조하십시오. 경로는 동일하게 유지되며 변수만 변경됩니다.
Zuplo를 오프라인으로 실행할 수 있습니까?
예. npm run dev는 9000번 포트에서 로컬 게이트웨이를 시작하고 9100번 포트에서 로컬 경로 디자이너를 시작합니다. 사용자 지정 정책, 유효성 검사 및 속도 제한은 모두 로컬에서 작동합니다. 인터넷 연결이 필요한 유일한 것은 관리형 API 키 서비스이며, npx zuplo link를 실행하여 로컬 인스턴스에서 클라우드 서비스를 사용할 수 있습니다.
잘못된 배포를 어떻게 롤백합니까?
병합 커밋을 git revert하고 푸시하십시오. Zuplo는 이전 상태를 다시 배포합니다. Git 기록이 진실의 원천이므로 별도의 "롤백" 버튼은 없습니다.
배포 중 진행 중인 요청은 어떻게 됩니까?
배포는 엣지에서 원자적입니다. 진행 중인 요청은 이전 버전에서 완료되고 새 요청은 새 버전으로 전달됩니다. 다운타임은 없습니다.
Zuplo를 gRPC 또는 WebSockets와 함께 사용할 수 있습니까?
예. urlForwardHandler는 WebSocket 업그레이드를 투명하게 프록시하고, gRPC는 gRPC 핸들러를 통해 지원됩니다. REST 및 GraphQL은 일급 시민이며 가장 일반적인 경우입니다.
Zuplo API를 AI 에이전트에 어떻게 노출합니까?
경로에 MCP 서버 핸들러를 추가하고 OpenAPI 스펙을 가리킨 다음 노출할 작업을 선택하십시오. 동일한 인증 및 속도 제한 정책이 MCP 요청에 적용됩니다. Zuplo MCP 서버 문서에서 설정 방법을 다룹니다.
운영 환경에서 게이트웨이 비용은 얼마입니까?
무료 티어는 월 10만 요청을 포함합니다. 빌더 플랜은 월 25달러에 1백만 요청을 추가하며, 추가 요청은 10만 요청당 100달러입니다. 엔터프라이즈 가격은 연간 계약 시 월 1,000달러부터 시작합니다. 전체 내용은 Zuplo 가격 페이지에서 확인할 수 있습니다.
결론
이제 API 키 인증, 키별 속도 제한, 요청 유효성 검사, 사용자 지정 TypeScript 아웃바운드 정책 및 개발자 포털을 갖춘 작동하는 Zuplo 게이트웨이를 가지게 되었습니다. 이 모든 것은 Git을 통해 글로벌 엣지에 배포됩니다. 동일한 프로젝트가 미리보기 환경, 프로덕션 롤아웃 및 MCP를 통한 AI 에이전트 액세스를 처리합니다.
이를 안정적으로 유지하는 핵심은 테스트 루프입니다. 병합하기 전에 모든 미리보기 환경에서 Apidog를 사용하면, 손상된 인증 헤더, 누락된 스키마 필드, 그리고 너무 관대하게 설정된 속도 제한을 배포하기 전에 발견할 수 있습니다. 오늘 Apidog를 다운로드하여 게이트웨이에 연결하십시오.