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ế với nó, thì đây là bài viết dành cho bạn. Nền tảng này rất nhanh để học, nhưng tài liệu hướng dẫn lại rải rác trên các luồng cổng thông tin, lệnh CLI và các bài viết trung tâm học tập. Hướng dẫn này sẽ kết nối các phần lại với nhau thành một hướng dẫn duy nhất: tạo một dự án, lộ trình một tuyến đường (route), thêm xác thực khóa API và giới hạn tỷ lệ, viết một chính sách TypeScript tùy chỉnh, triển khai đến biên, và kiểm tra toàn bộ với Apidog.
Đến cuối cùng, bạn sẽ có một API gateway hoạt động đang chạy trước máy chủ gốc của mình, với xác thực, giới hạn tỷ lệ, một cổng thông tin nhà phát triển tự động tạo và quy trình làm việc Git thân thiện với CI. Toàn bộ hướng dẫn mất khoảng ba mươi phút.
Nếu bạn vẫn đang quyết định liệu Zuplo có phải là công cụ phù hợp hay không, hãy bắt đầu với bài viết đi kèm của chúng tôi: Zuplo API gateway là gì. Đối với mọi thứ khác, tài liệu Zuplo sẽ đề cập đến các trường hợp đặc biệt mà hướng dẫn này bỏ qua.
Tóm tắt (TL;DR)
- Đăng ký tại portal.zuplo.com hoặc tạo dự án cục bộ với
npm create zuplo. - Xác định các tuyến đường trong
config/routes.oas.jsonvà chuyển tiếp chúng đến nguồn gốc của bạn bằng URL Forward Handler. - Thêm các chính sách đến (xác thực khóa API, giới hạn tỷ lệ, xác thực lược đồ) bằng cách chỉnh sửa tệp tuyến đường hoặc nhấp qua Trình thiết kế tuyến đường (Route Designer).
- Viết logic tùy chỉnh dưới dạng các mô-đun TypeScript trong
modules/; môi trường runtime cung cấp cho bạn quyền truy cập có kiểu đến request, context và environment. - Đẩy lên nhánh Git đã liên kết của bạn để triển khai môi trường xem trước; hợp nhất (merge) để đưa ra sản xuất trên hơn 300 địa điểm biên.
- Kiểm tra mọi tuyến đường bằng Apidog trước khi đưa vào sản xuất.
- Giá bắt đầu miễn phí với 100K yêu cầu mỗi tháng; gói Builder là 25 đô la mỗi tháng.
Điều kiện tiên quyết
Bạn cần ba điều trước khi bắt đầu:
- Một tài khoản Zuplo
- Một API gốc để đặt gateway phía trước. Nếu bạn chưa có, hãy sử dụng
https://echo.zuplo.io, nơi phản hồi lại bất cứ thứ gì bạn gửi. - Node.js 18 trở lên nếu bạn định sử dụng CLI.
Đối với phát triển cục bộ, bạn cũng cần một trình soạn thảo mã. VS Code với tiện ích mở rộng TypeScript là con đường dễ dàng nhất, và bạn có thể kết hợp nó với tiện ích mở rộng Apidog VS Code để gửi yêu cầu mà không cần rời khỏi trình soạn thảo của mình.
Bước 1: Tạo dự án Zuplo của bạn
Bạn có hai cách để bắt đầu: cổng web hoặc CLI. Hầu hết các nhóm bắt đầu trong cổng vì nó nhanh hơn để demo, sau đó chuyển sang CLI khi họ muốn CI/CD.
Tùy chọn A: Bắt đầu từ cổng
- Đăng nhập tại portal.zuplo.com.
- Nhấp vào “New Project” và chọn một tên như
acme-gateway. - Chọn “Empty Project” để không có gì được tự động tạo.
- Tab Code mở ra một cây tệp khởi tạo.
Theo mặc định, cổng sẽ liên kết dự án với một kho Git được quản lý. Bạn có thể kết nối kho GitHub, GitLab, Bitbucket hoặc Azure DevOps của riêng mình từ Cài đặt sau.
Tùy chọn B: Bắt đầu từ CLI
CLI tạo bố cục dự án tương tự cục bộ để bạn có thể chỉnh sửa trong IDE của mình và sử dụng Git ngay từ ngày đầu.
npm create zuplo@latest -- --name acme-gateway
cd acme-gateway
npm install
npm run dev
Máy chủ dev khởi động trên cổng 9000 và in một liên kết đến Trình thiết kế tuyến đường cục bộ tại http://localhost:9100. Bất kỳ thay đổi nào bạn thực hiện trong trình soạn thảo hoặc trong trình thiết kế sẽ tự động tải lại ngay lập tức.
Để liên kết dự án cục bộ với tài khoản Zuplo của bạn khi bạn sẵn sàng triển khai:
npx zuplo link
Chọn tài khoản và môi trường khi được hỏi. Từ đây, npx zuplo deploy sẽ triển khai nhánh Git hiện tại.
Bước 2: Xác định tuyến đường đầu tiên của bạn
Mở config/routes.oas.json. Đây là tài liệu OpenAPI 3 với các tiện ích mở rộng Zuplo cho trình xử lý và chính sách. Thêm một tuyến đường chuyển tiếp GET /v1/products đến nguồn gốc của bạn:
{
"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" }
}
}
}
}
}
Một vài chi tiết đáng chú ý. Tiện ích mở rộng x-zuplo-route là nơi Zuplo nằm bên trong một tệp OpenAPI thuần túy. handler mô tả điều gì xảy ra khi tuyến đường khớp; urlForwardHandler là proxy tích hợp sẵn. Tham chiếu ${env.ORIGIN_URL} lấy từ các biến môi trường để bạn có thể nhắm mục tiêu các backend khác nhau cho mỗi môi trường.
Đặt ORIGIN_URL từ Settings > Environment Variables trong cổng, hoặc bằng cách chỉnh sửa config/.env cục bộ. Sử dụng https://echo.zuplo.io nếu bạn chưa có nguồn gốc thực sự.
Lưu lại và máy chủ dev cục bộ sẽ tải lại. Truy cập http://localhost:9000/v1/products và bạn sẽ thấy yêu cầu được phản hồi. Các gateway đã triển khai sẽ phản hồi từ trung tâm dữ liệu biên gần nhất.
Bước 3: Thêm xác thực khóa API
API công khai cần thông tin xác thực. Zuplo cung cấp một dịch vụ khóa API được quản lý để bạn không phải tự xây dựng kho khóa.
Chỉnh sửa tuyến đường để thêm chính sách đến:
"policies": {
"inbound": ["api-key-auth"]
}
Sau đó thêm định nghĩa chính sách vào config/policies.json (Zuplo sẽ tạo tệp này lần đầu tiên bạn thêm một chính sách):
{
"name": "api-key-auth",
"policyType": "api-key-inbound",
"handler": {
"export": "ApiKeyInboundPolicy",
"module": "$import(@zuplo/runtime)",
"options": {
"allowUnauthenticatedRequests": false
}
}
}
Bây giờ hãy tạo một consumer (thực thể sở hữu một hoặc nhiều khóa API):
- Vào Services > API Key Service trong cổng.
- Nhấp vào “Create Consumer”.
- Đặt chủ thể thành một định danh ổn định như
acme-customer-1. - Thêm email của người sẽ quản lý khóa.
- Sao chép khóa API đã tạo.
Kiểm tra với curl. Nếu không có tiêu đề, bạn sẽ thấy 401:
curl -i https://YOUR-PROJECT.zuplo.app/v1/products
# HTTP/2 401
Với tiêu đề, bạn sẽ thấy phản hồi 200 gốc:
curl -i https://YOUR-PROJECT.zuplo.app/v1/products \
-H "Authorization: Bearer YOUR_API_KEY"
# HTTP/2 200
Nếu bạn muốn điều khiển việc này từ một client thực, hãy nhập thông số kỹ thuật OpenAPI của gateway vào Apidog, đặt tiêu đề chung cho Authorization: Bearer {{api_key}}, và liên kết api_key với một biến môi trường. Bạn sẽ có một bề mặt kiểm thử sạch cho mọi tuyến đường chỉ trong vài giây.
Bước 4: Giới hạn tỷ lệ tuyến đường
Không bao giờ triển khai API công khai mà không có giới hạn tỷ lệ. Chính sách giới hạn tỷ lệ Zuplo mặc định cung cấp cho bạn khả năng điều tiết theo IP, theo khóa hoặc theo thuộc tính tùy chỉnh.
Thêm nó vào danh sách đến, sau xác thực:
"policies": {
"inbound": ["api-key-auth", "rate-limit-by-key"]
}
Xác định nó trong 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" khóa nhóm dựa trên chủ thể được xác thực từ chính sách khóa API, vì vậy mỗi khách hàng sẽ có ngân sách 60 yêu cầu mỗi phút riêng. Thay thế bằng "ip" nếu bạn muốn điều tiết lưu lượng truy cập ẩn danh.
Yêu cầu thứ 61 trong bất kỳ cửa sổ sáu mươi giây nào sẽ trả về 429 với tiêu đề thử lại được đính kèm. Hãy kiểm tra bằng cách gửi 70 yêu cầu trong một vòng lặp và xem mã phản hồi thay đổi.
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 đọc 200 và 10 dòng đọc 429.
Bước 5: Xác thực payload yêu cầu
Nếu bạn có một tuyến đường POST nhận một body JSON, chính sách xác thực yêu cầu sẽ bắt các payload không đúng định dạng tại gateway thay vì tại nguồn gốc của bạn. Nó sử dụng JSON Schema được nhúng trong hoạt động OpenAPI của bạn, vì vậy bạn có được điều này miễn phí nếu đặc tả của bạn chính xác.
Thêm một tuyến đường với request body:
"/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": { /* tương tự như trên */ },
"policies": {
"inbound": [
"api-key-auth",
"rate-limit-by-key",
"validate-request"
]
}
}
}
}
Thêm chính sách:
{
"name": "validate-request",
"policyType": "open-api-request-validation-inbound",
"handler": {
"export": "OpenApiRequestValidationInboundPolicy",
"module": "$import(@zuplo/runtime)",
"options": {
"validateBody": "reject"
}
}
}
Bây giờ, một yêu cầu POST với một trường bị thiếu sẽ bị từ chối với mã 400 trước khi nó đến nguồn gốc của bạn. Kiểm tra nó bằng Apidog bằng cách lưu một yêu cầu "đường dẫn thành công", một yêu cầu "thiếu trường bắt buộc" và một yêu cầu "giá trị enum sai" dưới dạng các ví dụ riêng biệt trong cùng một nhóm yêu cầu. Bạn có thể chạy cả ba chỉ với một cú nhấp chuột.
Bước 6: Viết chính sách TypeScript tùy chỉnh
Các chính sách được xây dựng sẵn bao gồm hầu hết những gì các nhóm cần. Tuy nhiên, điểm mấu chốt của Zuplo là khi bạn cần một cái gì đó tùy chỉnh. Đây là một chính sách outbound thêm tiêu đề Cache-Control cho khách hàng trả phí và no-store cho khách hàng 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;
}
Kết nối nó vào config/policies.json:
{
"name": "tiered-cache",
"policyType": "custom-code-outbound",
"handler": {
"export": "default",
"module": "$import(./modules/tiered-cache)",
"options": {
"paidPlanHeader": "x-plan",
"paidMaxAge": 300
}
}
}
Và tham chiếu nó từ tuyến đường:
"policies": {
"inbound": ["api-key-auth", "rate-limit-by-key"],
"outbound": ["tiered-cache"]
}
Chính sách tùy chỉnh chỉ là một hàm. Bạn có thể kiểm thử đơn vị nó với Vitest hoặc Jest bằng cách truyền vào một Response và ZuploRequest tổng hợp và kiểm định các tiêu đề, không yêu cầu công cụ tích hợp nào.
Bước 7: Triển khai ra biên
Triển khai là một thao tác 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
Zuplo xây dựng một môi trường xem trước cho mọi nhánh và in URL trong nhật ký xây dựng. Bản xem trước có một tên miền phụ riêng như https://acme-gateway-feature-products-gateway-abc123.zuplo.app, với tất cả các chính sách của bạn đang hoạt động và trỏ đến bất kỳ ORIGIN_URL nào được đặt cho môi trường đó.
Kiểm tra URL xem trước với Apidog bằng cách đặt nó làm môi trường mới trong dự án của bạn. Chạy toàn bộ bộ kiểm thử của bạn chống lại nó. Nếu mọi thứ đều vượt qua, hãy hợp nhất nhánh.
git checkout main
git merge feature/products-gateway
git push origin main
Việc hợp nhất kích hoạt triển khai sản xuất. Trong vòng sáu mươi giây, phiên bản mới sẽ hoạt động trên hơn 300 vị trí biên. Khôi phục và lùi lại đều là các thao tác git push; không có giao diện người dùng riêng biệt.
Bước 8: Tạo cổng thông tin nhà phát triển
Cổng thông tin được lưu trữ tại https://YOUR-PROJECT.developers.zuplo.com và được xây dựng lại trên mỗi lần triển khai. Nó bao gồm:
- Một trang cho mỗi tuyến đường, với lược đồ, mô tả và bảng điều khiển thử nghiệm.
- Các mẫu mã bằng cURL, JavaScript, Python, Go và một vài ngôn ngữ khác.
- Tự phục vụ cấp khóa API cho bất kỳ khách truy cập nào đăng ký.
- Điều khiển thương hiệu trong cổng thông tin dưới Developer Portal > Settings.
Nếu thông số kỹ thuật OpenAPI của bạn có các mô tả và ví dụ tốt, cổng thông tin sẽ trông hoàn chỉnh mà không cần thêm công việc. Nếu thông số kỹ thuật của bạn sơ sài, đây là lúc bạn phát hiện ra.
Để tùy chỉnh, mã nguồn cổng thông tin được phân phối dưới dạng một ứng dụng Next.js riêng biệt mà bạn có thể fork từ kho lưu trữ cổng thông tin nhà phát triển Zuplo trên GitHub. Hầu hết các nhóm vẫn sử dụng phiên bản được lưu trữ.
Bước 9: Kiểm tra mọi thứ với Apidog
Khi gateway của bạn hoạt động, nguyên tắc ngăn ngừa sự cố sản xuất là kiểm tra mọi tuyến đường, mọi chính sách và mọi đường dẫn lỗi. Apidog giúp việc này nhanh chóng.
Quy trình làm việc hiệu quả:
- Nhập thông số kỹ thuật OpenAPI của gateway từ
https://YOUR-PROJECT.zuplo.app/openapi. Apidog biến mỗi hoạt động thành một yêu cầu mà bạn có thể gửi. - Tạo các môi trường cho
local,previewvàproduction, mỗi môi trường cóbase_urlvàapi_keyriêng. - Lưu tối thiểu ba yêu cầu cho mỗi tuyến đường: đường dẫn thành công, lỗi xác thực và kích hoạt giới hạn tỷ lệ. Chạy chúng theo nhóm trước mỗi lần triển khai.
- Sử dụng các kịch bản kiểm thử tự động của Apidog để liên kết các cuộc gọi với nhau (tạo sản phẩm, liệt kê, xóa) và kiểm định hình dạng phản hồi.
- Tạo các mẫu mã bằng ngôn ngữ chính của nhóm bạn và dán chúng vào các runbook của bạn.
Nếu bạn đang di chuyển từ Postman, hướng dẫn kiểm thử API không dùng Postman sẽ hướng dẫn qua việc nhập khẩu. Tải xuống Apidog nếu bạn chưa có.
Các câu hỏi thường gặp về việc sử dụng Zuplo
Làm cách nào để chuyển đổi một tuyến đường giữa các môi trường mà không cần thay đổi đặc tả?
Sử dụng các biến môi trường. Định nghĩa ORIGIN_URL cho mỗi môi trường trong Cài đặt cổng hoặc trong config/.env cục bộ, và tham chiếu nó dưới dạng ${env.ORIGIN_URL} bên trong các tùy chọn trình xử lý. Tuyến đường vẫn giữ nguyên; chỉ biến đổi biến.
Tôi có thể chạy Zuplo ngoại tuyến không?
Có. npm run dev khởi động một gateway cục bộ trên cổng 9000 với Trình thiết kế tuyến đường cục bộ trên 9100. Các chính sách tùy chỉnh, xác thực và giới hạn tỷ lệ đều hoạt động cục bộ; điều duy nhất yêu cầu kết nối internet là dịch vụ khóa API được quản lý, và bạn có thể chạy npx zuplo link để sử dụng dịch vụ đám mây từ phiên bản cục bộ của mình.
Làm cách nào để khôi phục một lần triển khai lỗi?
git revert commit hợp nhất và push. Zuplo sẽ triển khai lại trạng thái trước đó. Không có nút "rollback" riêng biệt vì lịch sử Git là nguồn sự thật.
Điều gì xảy ra với các yêu cầu đang thực hiện trong quá trình triển khai?
Các lần triển khai là nguyên tử tại biên; các yêu cầu đang thực hiện sẽ hoàn tất trên phiên bản cũ và các yêu cầu mới sẽ đến phiên bản mới. Không có thời gian ngừng hoạt động.
Tôi có thể sử dụng Zuplo với gRPC hoặc WebSockets không?
Có. urlForwardHandler proxy các nâng cấp WebSocket một cách minh bạch, và gRPC được hỗ trợ thông qua gRPC handler. REST và GraphQL là hàng đầu và là trường hợp phổ biến nhất.
Làm cách nào để tôi công khai API Zuplo của mình cho các tác nhân AI?
Thêm MCP Server Handler vào một tuyến đường, trỏ nó vào đặc tả OpenAPI của bạn và chọn các hoạt động để công khai. Các chính sách xác thực và giới hạn tỷ lệ tương tự áp dụng cho các yêu cầu MCP. Tài liệu Zuplo MCP Server bao gồm thiết lập.
Gateway tốn bao nhiêu chi phí trong sản xuất?
Gói miễn phí bao gồm 100K yêu cầu mỗi tháng. Gói Builder bổ sung 1M yêu cầu với giá 25 đô la mỗi tháng, và các yêu cầu bổ sung có giá 100 đô la cho mỗi 100K. Giá dành cho doanh nghiệp bắt đầu từ 1.000 đô la mỗi tháng theo hợp đồng hàng năm. Chi tiết đầy đủ trên trang giá Zuplo.
Kết luận
Bây giờ bạn đã có một gateway Zuplo hoạt động với xác thực khóa API, giới hạn tỷ lệ theo khóa, xác thực yêu cầu, một chính sách outbound TypeScript tùy chỉnh và một cổng thông tin nhà phát triển, tất cả đều được triển khai thông qua Git ra biên toàn cầu. Cùng một dự án xử lý môi trường xem trước, triển khai sản xuất và truy cập tác nhân AI thông qua MCP.
Yếu tố giữ cho nó ổn định là vòng lặp kiểm thử. Sử dụng Apidog để kiểm tra mọi bản xem trước trước khi hợp nhất, và bạn sẽ phát hiện ra các tiêu đề xác thực bị hỏng, các trường lược đồ bị thiếu và các giới hạn tỷ lệ quá hào phóng một cách vô ý trước khi chúng được triển khai. Tải xuống Apidog và kết nối nó vào gateway của bạn ngay hôm nay.