Nếu bạn đã tìm hiểu về Zuplo và muốn triển khai một sản phẩm thực tế, đây là hướng dẫn từng bước tập trung vào triển khai: tạo dự án, cấu hình route, thêm xác thực API key, limit rate, viết chính sách TypeScript tùy chỉnh, deploy ra edge, và kiểm thử toàn bộ với Apidog.
Đến cuối hướng dẫn, bạn sẽ có một API gateway thực tế trước backend, có xác thực, giới hạn tốc độ, cổng thông tin dev tự động, CI-friendly Git workflow. Thực hiện tất cả trong khoảng 30 phút.
Nếu bạn chưa chắc về Zuplo, hãy đọc bài gốc: Zuplo API gateway là gì. Các trường hợp chi tiết khác xem tại tài liệu Zuplo.
Tóm tắt (TL;DR)
- Đăng ký tại portal.zuplo.com hoặc tạo local project với
npm create zuplo. - Định nghĩa route trong
config/routes.oas.json, dùng URL Forward Handler để proxy đến backend. - Thêm policies (API key, limit rate, schema validation) trong file route hoặc Route Designer.
- Code logic custom bằng TypeScript ở
modules/; runtime cung cấp kiểu cho request, context, env. - Git push lên nhánh liên kết để deploy preview; merge để production rollout trên hơn 300 PoP.
- Kiểm thử routes bằng Apidog trước production.
- Miễn phí 100K requests/tháng; Builder $25/tháng.
Điều kiện tiên quyết
Bạn cần:
- Tài khoản Zuplo
- Một backend API (hoặc dùng
https://echo.zuplo.iođể test) - Node.js 18+ nếu dùng CLI
Nếu phát triển local, dùng VS Code & extension TypeScript là tiện nhất, có thể kết hợp tiện ích mở rộng Apidog VS Code để gửi request trực tiếp từ editor.
Bước 1: Tạo dự án Zuplo
Có hai cách: qua web portal hoặc CLI.
Tùy chọn A: Bắt đầu từ portal
- Đăng nhập portal.zuplo.com.
- Chọn "New Project", đặt tên (ví dụ:
acme-gateway). - Chọn "Empty Project" để bắt đầu trống.
- Tab Code sẽ hiển thị cây file dự án.
Portal sẽ liên kết project với kho Git (GitHub, GitLab, Bitbucket, Azure DevOps). Có thể đổi kho trong Settings.
Tùy chọn B: Bắt đầu từ CLI
Tạo local project để thao tác trên IDE, push/pull Git từ đầu.
npm create zuplo@latest -- --name acme-gateway
cd acme-gateway
npm install
npm run dev
Dev server chạy trên port 9000, mở Route Designer local tại http://localhost:9100. Mọi thay đổi tự reload.
Liên kết dự án local với tài khoản Zuplo để deploy:
npx zuplo link
Chọn tài khoản/môi trường. Sau đó, npx zuplo deploy để deploy nhánh Git hiện tại.
Bước 2: Định nghĩa route đầu tiên
Mở config/routes.oas.json – file OpenAPI 3 mở rộng cho Zuplo.
Ví dụ, thêm route GET /v1/products proxy về backend:
{
"openapi": "3.1.0",
"info": { "title": "Acme Gateway", "version": "1.0.0" },
"paths": {
"/v1/products": {
"get": {
"summary": "Liệt kê sản phẩm",
"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": "Thành công" }
}
}
}
}
}
-
x-zuplo-route: mở rộng cho Zuplo nằm trong OpenAPI. -
handler: định nghĩa proxy (urlForwardHandler), target từ biến env.
Cấu hình biến ORIGIN_URL trong Settings > Environment Variables (portal) hoặc config/.env (local). Chưa có backend? Dùng https://echo.zuplo.io để test.
Sau khi lưu, dev server reload. Truy cập http://localhost:9000/v1/products sẽ thấy response từ backend.
Bước 3: Thêm xác thực API key
Sửa route để thêm policy:
"policies": {
"inbound": ["api-key-auth"]
}
Khai báo policy ở config/policies.json:
{
"name": "api-key-auth",
"policyType": "api-key-inbound",
"handler": {
"export": "ApiKeyInboundPolicy",
"module": "$import(@zuplo/runtime)",
"options": {
"allowUnauthenticatedRequests": false
}
}
}
Tạo consumer (chủ sở hữu API key):
- Vào Services > API Key Service.
- Chọn "Create Consumer".
- Đặt subject (ví dụ:
acme-customer-1). - Thêm email quản lý key.
- Copy API key.
Kiểm thử:
- Không gửi header: trả về 401.
curl -i https://YOUR-PROJECT.zuplo.app/v1/products
# HTTP/2 401
- Có API key:
curl -i https://YOUR-PROJECT.zuplo.app/v1/products \
-H "Authorization: Bearer YOUR_API_KEY"
# HTTP/2 200
Để test qua client, import OpenAPI spec vào Apidog, set header mặc định Authorization: Bearer {{api_key}}, link api_key vào biến môi trường – kiểm thử nhanh mọi route.
Bước 4: Giới hạn tốc độ (rate limit) route
Không nên public API mà thiếu rate limit. Thêm policy:
"policies": {
"inbound": ["api-key-auth", "rate-limit-by-key"]
}
Thêm policy vào 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": rate limit theo subject (API key). -
"ip": limit theo địa chỉ IP.
Kiểm tra bằng bash:
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
Bạn sẽ thấy 60 dòng 200 và 10 dòng 429.
Bước 5: Xác thực payload request (schema validation)
Với route POST nhận JSON body, policy xác thực sẽ reject payload sai format tại gateway.
Thêm route POST:
"/v1/products": {
"post": {
"summary": "Tạo sản phẩm",
"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"
]
}
}
}
}
Thêm policy:
{
"name": "validate-request",
"policyType": "open-api-request-validation-inbound",
"handler": {
"export": "OpenApiRequestValidationInboundPolicy",
"module": "$import(@zuplo/runtime)",
"options": {
"validateBody": "reject"
}
}
}
Gửi POST thiếu trường sẽ bị reject 400 trước khi tới backend. Test với Apidog: tạo các request "thành công", "thiếu trường", "enum sai" thành nhóm, chạy batch chỉ với 1 click.
Bước 6: Viết policy TypeScript custom
Nếu cần logic đặc biệt, chỉ cần viết hàm TypeScript.
Ví dụ: Policy outbound set header Cache-Control khác nhau cho khách trả phí/miễn phí.
Tạo 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;
}
Khai báo policy trong config/policies.json:
{
"name": "tiered-cache",
"policyType": "custom-code-outbound",
"handler": {
"export": "default",
"module": "$import(./modules/tiered-cache)",
"options": {
"paidPlanHeader": "x-plan",
"paidMaxAge": 300
}
}
}
Tham chiếu ở route:
"policies": {
"inbound": ["api-key-auth", "rate-limit-by-key"],
"outbound": ["tiered-cache"]
}
Policy chỉ là hàm TypeScript, có thể unit test độc lập (dùng Vitest/Jest) mà không cần deploy.
Bước 7: Triển khai ra edge
Deploy = git push:
git add .
git commit -m "Thêm gateway sản phẩm với xác thực, giới hạn tỷ lệ và bộ nhớ đệm phân cấp"
git push origin feature/products-gateway
Mỗi branch đều có môi trường preview, URL riêng dạng https://acme-gateway-feature-products-gateway-abc123.zuplo.app.
Kiểm thử preview URL qua Apidog bằng cách set làm env mới. Nếu pass, merge branch:
git checkout main
git merge feature/products-gateway
git push origin main
Sau merge, production deploy trên 300+ PoP global trong ~60s. Rollback chỉ cần git revert và push.
Bước 8: Tạo cổng thông tin developer
Cổng thông tin ở https://YOUR-PROJECT.developers.zuplo.com, rebuild mỗi lần deploy. Bao gồm:
- Trang docs cho từng route, schema, mô tả, try console
- Code sample (cURL, JS, Python, Go, ...)
- API key self-service cho user đăng ký
- Branding chỉnh ở Developer Portal > Settings
Spec OpenAPI tốt = docs auto hoàn chỉnh. Tuỳ biến? Fork source portal (Next.js) tại GitHub Zuplo/zudoku, nhưng phần lớn dùng bản hosted là đủ.
Bước 9: Kiểm thử toàn bộ với Apidog
Kiểm thử mọi route, policy, error path trước khi production bằng Apidog:
Workflow đề xuất:
- Import OpenAPI spec từ
https://YOUR-PROJECT.zuplo.app/openapivào Apidog. - Tạo env cho
local,preview,production(mỗi env cóbase_url,api_keyriêng). - Lưu ít nhất 3 request cho mỗi route: success, validation error, rate limit. Batch run trước mỗi deploy.
- Dùng test script nối các call (create, list, delete) và kiểm tra response shape.
- Gen code sample (ngôn ngữ chính của team) để dán vào runbook.
Chuyển từ Postman? Xem hướng dẫn kiểm thử API không dùng Postman. Tải Apidog nếu chưa có.
FAQ: Sử dụng Zuplo
Làm sao chuyển route giữa các môi trường mà không sửa spec?
Dùng biến môi trường. Định nghĩa ORIGIN_URL cho từng env (portal hoặc local .env), dùng ${env.ORIGIN_URL} trong handler option.
Có chạy Zuplo offline được không?
Được. npm run dev chạy local gateway port 9000, Route Designer port 9100. Policy, xác thực, rate limit vẫn chạy local; chỉ API Key Service cần mạng (có thể dùng npx zuplo link để sync cloud key).
Làm sao rollback deploy lỗi?
git revert commit merge, push lên remote. Zuplo redeploy trạng thái trước. Không cần UI rollback – Git là nguồn sự thật.
Deploy có downtime không?
Không. Deploy atomic tại edge; request đang chạy hoàn thành trên phiên bản cũ, request mới lên version mới.
Zuplo hỗ trợ gRPC/WebSocket không?
Có. urlForwardHandler proxy WebSocket upgrade, có hỗ trợ gRPC handler. REST & GraphQL là phổ biến nhất.
Làm sao public API Zuplo cho AI agent?
Thêm MCP Server Handler vào route, trỏ vào OpenAPI spec, chọn operation public. Auth & rate limit vẫn áp dụng. Xem docs Zuplo MCP Server.
Chi phí gateway Zuplo?
Miễn phí 100K request/tháng. Builder: $25/tháng + 1M request. Thêm request: $100/100K. Enterprise: từ $1,000/tháng. Xem chi tiết tại Zuplo pricing.
Kết luận
Bạn đã có gateway Zuplo có xác thực API key, rate limit, validate request, policy TypeScript custom, cổng dev portal – tất cả deploy qua Git lên edge toàn cầu. Quản lý preview, production, AI agent với cùng một cấu hình.
Vòng lặp kiểm thử giữ mọi thứ ổn định. Dùng Apidog để test preview trước khi merge, tránh lỗi header, thiếu field, rate limit... Tải Apidog và tích hợp ngay với gateway của bạn.
Top comments (0)