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.
옵션 A: 포털 우선
- portal.zuplo.com에 로그인합니다.
- "새 프로젝트"를 클릭하고
acme-gateway와 같은 이름을 선택합니다. - "빈 프로젝트"를 선택하세요.
- 코드 탭에서 시작 파일 트리를 확인합니다.
포털은 기본적으로 프로젝트를 관리형 Git 리포지토리에 연결합니다. 필요시 자체 GitHub, GitLab, Bitbucket 또는 Azure DevOps 리포지토리 연결도 가능합니다.
옵션 B: CLI 우선
로컬에서 바로 개발하려면 CLI를 사용하세요.
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
2단계: 첫 번째 경로 정의
config/routes.oas.json을 열고 아래 예시처럼 경로를 추가합니다. OpenAPI 3 문서에 Zuplo 확장이 포함된 구조입니다.
{
"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": "성공" }
}
}
}
}
}
ORIGIN_URL 환경 변수는 포털 설정 > 환경 변수 또는 로컬에서는 config/.env에서 설정하세요. 실제 원본이 없으면 https://echo.zuplo.io를 사용하면 됩니다.
로컬 개발 서버에서 http://localhost:9000/v1/products로 접속해 확인할 수 있습니다.
3단계: API 키 인증 추가
API에 인증을 적용하려면 다음과 같이 설정합니다.
경로의 인바운드 정책에 추가:
"policies": {
"inbound": ["api-key-auth"]
}
config/policies.json 파일에 정책 정의를 작성:
{
"name": "api-key-auth",
"policyType": "api-key-inbound",
"handler": {
"export": "ApiKeyInboundPolicy",
"module": "$import(@zuplo/runtime)",
"options": {
"allowUnauthenticatedRequests": false
}
}
}
API 키 생성 및 테스트:
- 포털 > 서비스 > API 키 서비스로 이동
- "컨슈머 생성" → 식별자 및 이메일 입력, 키 복사
- 헤더 없이 호출 시 401, 키 포함 시 200 확인
curl -i https://YOUR-PROJECT.zuplo.app/v1/products
curl -i https://YOUR-PROJECT.zuplo.app/v1/products \
-H "Authorization: Bearer YOUR_API_KEY"
OpenAPI 스펙을 Apidog로 가져와 환경에 따라 api_key를 바인딩하면 전체 테스트를 빠르게 구성할 수 있습니다.
4단계: 경로에 속도 제한 적용
속도 제한 정책을 추가하여 API의 안정성을 높이세요.
경로 인바운드 정책에 추가:
"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
}
}
}
테스트 예시:
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단계: 요청 페이로드 유효성 검사
POST 경로에 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"
}
}
}
누락‧잘못된 필드에 대해 400 반환. Apidog에서 성공/실패/에러 시나리오를 각각 예제로 저장하고, 그룹 실행으로 빠르게 검증하세요.
6단계: 사용자 지정 TypeScript 정책 작성
커스텀 정책 예시: 유료 고객에게는 Cache-Control, 무료 고객에게는 no-store 헤더를 부여.
modules/tiered-cache.ts 작성:
import { ZuploRequest, ZuploContext } 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
}
}
}
경로에서 outbound 정책 연결:
"policies": {
"inbound": ["api-key-auth", "rate-limit-by-key"],
"outbound": ["tiered-cache"]
}
Vitest/Jest 등으로 단위 테스트도 가능합니다.
7단계: 엣지에 배포
배포는 Git 기반으로 단순합니다.
git add .
git commit -m "인증, 속도 제한, 계층형 캐시를 포함한 제품 게이트웨이 추가"
git push origin feature/products-gateway
Zuplo는 브랜치별 미리보기 환경을 자동 빌드하며, 미리보기 URL에서 바로 테스트할 수 있습니다.
배포 확정:
git checkout main
git merge feature/products-gateway
git push origin main
병합 후 60초 이내에 300+ 엣지에 자동 배포됩니다.
8단계: 개발자 포털 생성
포털은 https://YOUR-PROJECT.developers.zuplo.com에서 자동 생성 및 호스팅됩니다.
- 라우트별 문서 및 Try-it 콘솔
- 다양한 언어의 코드 샘플
- API 키 셀프 발급
- 브랜딩 커스터마이즈 (포털 > 개발자 포털 > 설정)
커스터마이즈가 필요하다면 Zuplo 개발자 포털 리포지토리를 포크하여 별도 Next.js 앱으로도 사용 가능합니다.
9단계: Apidog로 모든 것을 테스트
운영 중 사고를 예방하려면, 모든 경로/정책/에러 케이스를 반드시 테스트하세요. Apidog로 자동화할 수 있습니다.
워크플로우:
-
https://YOUR-PROJECT.zuplo.app/openapi에서 OpenAPI 스펙을 Apidog로 가져오기 -
local,preview,production환경 생성 및 각 환경별base_url,api_key지정 - 각 경로별로 성공/실패/속도제한 트리거 요청 예제 저장 후 그룹 실행
- Apidog 자동화 시나리오로 호출 연결 및 응답 어설션
- 코드 샘플 자동 생성 후 팀 문서/런북에 활용
Postman에서 이전하려면 API Testing without Postman 가이드 참고. 아직 설치하지 않았다면 Apidog 다운로드하세요.
Zuplo 사용에 대한 일반적인 질문
스펙을 변경하지 않고 환경 간에 경로를 어떻게 전환합니까?
환경별로 ORIGIN_URL을 환경 변수로 관리하고, 핸들러 옵션에서 ${env.ORIGIN_URL}로 참조하면 됩니다.
Zuplo를 오프라인으로 실행할 수 있습니까?
가능합니다. npm run dev로 로컬 게이트웨이(9000번), 로컬 경로 디자이너(9100번)를 실행하세요. 관리형 API 키 서비스만 클라우드 연결이 필요하며, npx zuplo link로 연동할 수 있습니다.
잘못된 배포를 어떻게 롤백합니까?
git revert로 병합 커밋을 되돌리고 푸시하면 Zuplo가 이전 상태로 롤백합니다. 별도의 롤백 UI는 없습니다.
배포 중 진행 중인 요청은 어떻게 됩니까?
엣지에서 원자적으로 처리됩니다. 진행 중인 요청은 이전 버전에서 완료되고 새 요청은 새 버전으로 전달됩니다.
Zuplo를 gRPC 또는 WebSockets와 함께 사용할 수 있습니까?
지원합니다. urlForwardHandler는 WebSocket 업그레이드를 프록시하고, gRPC 핸들러도 제공합니다.
Zuplo API를 AI 에이전트에 어떻게 노출합니까?
경로에 MCP 서버 핸들러 설정 후 OpenAPI 스펙을 지정하면, 동일한 인증 및 속도 제한 정책으로 AI 에이전트에 노출할 수 있습니다. 자세한 내용은 Zuplo MCP 서버 문서 참고.
운영 환경에서 게이트웨이 비용은 얼마입니까?
무료는 월 10만 요청, 빌더 플랜은 월 25달러(100만 요청), 엔터프라이즈는 연간 계약 시 월 1,000달러부터 시작합니다. Zuplo 가격 페이지에서 최신 정보를 확인하세요.
결론
이제 API 키 인증, 키별 속도 제한, 요청 유효성 검사, 사용자 지정 TypeScript 아웃바운드 정책 및 개발자 포털을 갖춘 Zuplo 게이트웨이를 완성했습니다. 모든 것은 Git 워크플로우로 글로벌 엣지에 배포됩니다. 동일한 프로젝트가 미리보기, 프로덕션, MCP 기반 AI 에이전트까지 모두 처리합니다.
테스트 루프를 자동화하는 것이 핵심입니다. 브랜치 병합 전 Apidog로 모든 미리보기 환경을 테스트하면, 인증 헤더 누락, 스키마 오류, 잘못된 속도 제한 등 문제를 사전에 방지할 수 있습니다. 오늘 Apidog 다운로드로 게이트웨이에 연결하십시오.
Top comments (0)