Zuplo hakkında bilgi edindiyseniz ve onunla gerçek bir şeyler göndermek istiyorsanız, bu yazı tam size göre. Platformu öğrenmesi hızlıdır, ancak belgeler portal akışları, CLI komutları ve öğrenme merkezi makalelerine yayılmıştır. Bu kılavuz, parçaları tek bir eğitimde bir araya getiriyor: bir proje oluşturma, bir rota açığa çıkarma, API anahtarı yetkilendirmesi ve hız sınırlaması ekleme, özel bir TypeScript ilkesi yazma, uca dağıtma ve tüm bunları Apidog ile test etme.
düğme
Sonunda, kimlik doğrulama, hız sınırlaması, otomatik oluşturulmuş bir geliştirici portalı ve CI dostu bir Git iş akışı ile kaynağınızın önünde çalışan bir API ağ geçidine sahip olacaksınız. Tüm bu süreç yaklaşık otuz dakika sürer.
Hala Zuplo'nun doğru araç olup olmadığına karar vermeye çalışıyorsanız, tamamlayıcı yazımızla başlayın: Zuplo API ağ geçidi nedir. Diğer her şey için, Zuplo belgeleri bu kılavuzun atladığı uç durumları kapsar.
Özet
- portal.zuplo.com adresinden kaydolun veya
npm create zuploile yerel bir proje oluşturun. config/routes.oas.jsoniçinde rotaları tanımlayın ve URL İletme İşleyicisi ile kaynağınıza iletin.- Gelen ilkeleri (API anahtarı yetkilendirmesi, hız limiti, şema doğrulama) rota dosyasını düzenleyerek veya Rota Tasarımcısı üzerinden tıklayarak ekleyin.
- Özel mantığı
modules/içinde TypeScript modülleri olarak yazın; çalışma zamanı size istek, bağlam ve ortama tip güvenli erişim sağlar. - Bağlı Git dalınıza göndererek bir önizleme ortamı dağıtın; 300'den fazla uç konuma üretim sürümü göndermek için birleştirin.
- Üretime geçirmeden önce her rotayı Apidog ile test edin.
- Fiyatlandırma ayda 100 bin istekle ücretsiz başlar; Builder planı aylık 25 dolardır.
Ön Koşullar
Başlamadan önce üç şeye ihtiyacınız var:
- Bir Zuplo hesabı
- Ağ geçidini önüne koyacağınız bir kaynak API. Eğer bir tane yoksa, gönderdiğiniz her şeyi yankılayan
https://echo.zuplo.ioadresini kullanın. - CLI'yi kullanmayı planlıyorsanız Node.js 18 veya daha yüksek sürüm.
Yerel geliştirme için ayrıca bir kod düzenleyiciye ihtiyacınız var. TypeScript uzantısı ile VS Code en az dirençli yoldur ve düzenleyicinizden çıkmadan istek göndermek için Apidog VS Code uzantısı ile eşleştirebilirsiniz.
Adım 1: Zuplo projenizi oluşturun
Başlamak için iki yolunuz var: web portalı veya CLI. Çoğu ekip portalda başlar çünkü demosu daha hızlıdır, daha sonra CI/CD istediklerinde CLI'ya geçerler.
Seçenek A: Önce Portal
- portal.zuplo.com adresinden oturum açın.
- "Yeni Proje"ye tıklayın ve
acme-gatewaygibi bir ad seçin. - Hiçbir şeyin otomatik oluşturulmaması için "Boş Proje"yi seçin.
- Kod sekmesi bir başlangıç dosya ağacına açılır.
Portal, projeyi varsayılan olarak yönetilen bir Git deposuna bağlar. Daha sonra Ayarlar'dan kendi GitHub, GitLab, Bitbucket veya Azure DevOps deponuzu bağlayabilirsiniz.
Seçenek B: Önce CLI
CLI, aynı proje düzenini yerel olarak iskeletlendirir, böylece IDE'nizde düzenleyebilir ve ilk günden itibaren Git'i kullanabilirsiniz.
npm create zuplo@latest -- --name acme-gateway
cd acme-gateway
npm install
npm run dev
Geliştirme sunucusu 9000 numaralı bağlantı noktasında başlar ve yerel Rota Tasarımcısı'na http://localhost:9100 adresinde bir bağlantı yazdırır. Düzenleyicide veya tasarımcıda yaptığınız herhangi bir değişiklik anında yeniden yüklenir.
Yerel projeyi dağıtıma hazır olduğunuzda Zuplo hesabınıza bağlamak için:
npx zuplo link
İstendiğinde hesabı ve ortamı seçin. Buradan, npx zuplo deploy mevcut Git dalını gönderir.
Adım 2: İlk rotanızı tanımlayın
config/routes.oas.json dosyasını açın. Bu, işleyiciler ve ilkeler için Zuplo uzantıları içeren bir OpenAPI 3 belgesidir. GET /v1/products öğesini kaynağınıza ileten bir rota ekleyin:
{
"openapi": "3.1.0",
"info": { "title": "Acme Ağ Geçidi", "version": "1.0.0" },
"paths": {
"/v1/products": {
"get": {
"summary": "Ürünleri listele",
"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": "Başarılı" }
}
}
}
}
}
Dikkat edilmesi gereken birkaç ayrıntı var. x-zuplo-route uzantısı, Zuplo'nun aksi takdirde standart bir OpenAPI dosyasının içinde yaşadığı yerdir. handler, rota eşleştiğinde ne olacağını tanımlar; urlForwardHandler yerleşik proxy'dir. ${env.ORIGIN_URL} referansı, ortam değişkenlerinden çeker, böylece her ortam için farklı arka uçları hedefleyebilirsiniz.
Portaldaki Ayarlar > Ortam Değişkenleri'nden veya yerel olarak config/.env dosyasını düzenleyerek ORIGIN_URL değerini ayarlayın. Henüz gerçek bir kaynağınız yoksa https://echo.zuplo.io adresini kullanın.
Kaydedin ve yerel geliştirme sunucusu yeniden yüklenir. http://localhost:9000/v1/products adresine gidin ve yankılanan isteği görmelisiniz. Dağıtılan ağ geçitleri bunun yerine en yakın uç veri merkezinden yanıt verecektir.
Adım 3: API anahtarı kimlik doğrulaması ekleyin
Genel API'lerin kimlik bilgilerine ihtiyacı vardır. Zuplo, kendi anahtar deponuzu oluşturmanıza gerek kalmaması için yönetilen bir API anahtarı hizmeti sunar.
Gelen ilkeyi eklemek için rotayı düzenleyin:
"policies": {
"inbound": ["api-key-auth"]
}
Ardından ilke tanımını config/policies.json dosyasına ekleyin (Zuplo bu dosyayı ilk kez bir ilke eklediğinizde oluşturur):
{
"name": "api-key-auth",
"policyType": "api-key-inbound",
"handler": {
"export": "ApiKeyInboundPolicy",
"module": "$import(@zuplo/runtime)",
"options": {
"allowUnauthenticatedRequests": false
}
}
}
Şimdi bir tüketici oluşturun (bir veya daha fazla API anahtarına sahip olan varlık):
- Portaldaki Hizmetler > API Anahtarı Hizmeti'ne gidin.
- "Tüketici Oluştur"a tıklayın.
- Konuyu
acme-customer-1gibi sabit bir tanımlayıcı olarak ayarlayın. - Anahtarı kimin yönetmesi gerektiğini belirten e-postayı ekleyin.
- Oluşturulan API anahtarını kopyalayın.
Curl ile test edin. Başlık olmadan, 401 görmelisiniz:
curl -i https://PROJENİZ.zuplo.app/v1/products
# HTTP/2 401
Başlık ile orijinal 200 yanıtını görmelisiniz:
curl -i https://PROJENİZ.zuplo.app/v1/products \
-H "Authorization: Bearer SİZİN_API_ANAHTARINIZ"
# HTTP/2 200
Bunu gerçek bir istemciden sürmeyi tercih ediyorsanız, ağ geçidinin OpenAPI spesifikasyonunu Apidog'a aktarın, Authorization: Bearer {{api_key}} için genel bir başlık ayarlayın ve api_key'yi bir ortam değişkenine bağlayın. Her rota için saniyeler içinde temiz bir test yüzeyi elde edersiniz.
Adım 4: Rotayı hız sınırına tabi tutun
Herkese açık bir API'yi asla hız sınırlamaları olmadan göndermeyin. Varsayılan Zuplo hız sınırı ilkesi size IP başına, anahtar başına veya özel nitelik başına kısıtlama sağlar.
Doğrulama sonrası gelen listeye ekleyin:
"policies": {
"inbound": ["api-key-auth", "rate-limit-by-key"]
}
Bunu config/policies.json içinde tanımlayın:
{
"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", kovayı API anahtar ilkesinden kimliği doğrulanmış konuya göre anahtarlar, böylece her müşteri kendi 60 istek/dakika bütçesine sahip olur. Anonim trafiği kısıtlamak istiyorsanız "ip" ile değiştirin.
Herhangi bir altmış saniyelik penceredeki 61. istek, yeniden deneme başlıklarıyla birlikte 429 döndürür. Bir döngüde 70 istek göndererek ve yanıt kodlarının değişmesini izleyerek test edin.
for i in {1..70}; do
curl -s -o /dev/null -w "%{http_code}\n" \
https://PROJENİZ.zuplo.app/v1/products \
-H "Authorization: Bearer SİZİN_API_ANAHTARINIZ"
done | sort | uniq -c
60 satır 200 ve 10 satır 429 görmelisiniz.
Adım 5: İstek yüklerini doğrulayın
JSON gövdesi alan bir POST rotanız varsa, istek doğrulama ilkesi, hatalı biçimlendirilmiş yükleri kaynağınızda değil, ağ geçidinde yakalar. OpenAPI işleminize gömülü JSON Şemasını kullanır, bu nedenle spesifikasyonunuz doğruysa bunu ücretsiz olarak alırsınız.
İstek gövdesi içeren bir rota ekleyin:
"/v1/products": {
"post": {
"summary": "Ürün oluştur",
"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": { /* yukarıdakiyle aynı */ },
"policies": {
"inbound": [
"api-key-auth",
"rate-limit-by-key",
"validate-request"
]
}
}
}
}
İlkeyi ekleyin:
{
"name": "validate-request",
"policyType": "open-api-request-validation-inbound",
"handler": {
"export": "OpenApiRequestValidationInboundPolicy",
"module": "$import(@zuplo/runtime)",
"options": {
"validateBody": "reject"
}
}
}
Şimdi eksik bir alan içeren bir POST, kaynağınıza ulaşmadan önce 400 ile reddedilir. Bunu Apidog ile, aynı istek grubunda "başarılı yol" isteği, "eksik gerekli alan" isteği ve "yanlış enum değeri" isteğini ayrı örnekler olarak kaydederek test edin. Üçünü tek tıklamayla çalıştırabilirsiniz.
Adım 6: Özel bir TypeScript ilkesi yazın
Hazır ilkeler, ekiplerin ihtiyaç duyduğu çoğu şeyi karşılar. Ancak Zuplo'nun amacı, özel bir şeye ihtiyaç duyduğunuz andır. İşte ücretli müşteriler için Cache-Control başlığı ekleyen, ücretsiz müşteriler için ise no-store ekleyen bir giden ilke.
modules/tiered-cache.ts dosyasını oluşturun:
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 içine bağlayın:
{
"name": "tiered-cache",
"policyType": "custom-code-outbound",
"handler": {
"export": "default",
"module": "$import(./modules/tiered-cache)",
"options": {
"paidPlanHeader": "x-plan",
"paidMaxAge": 300
}
}
}
Ve rotadan referans verin:
"policies": {
"inbound": ["api-key-auth", "rate-limit-by-key"],
"outbound": ["tiered-cache"]
}
Özel ilke sadece bir fonksiyondur. Sentetik bir Response ve ZuploRequest ile Vitest veya Jest ile birim testini yapabilir ve başlıklarda iddiada bulunabilirsiniz, entegrasyon donanımı gerektirmez.
Adım 7: Uca dağıtım
Dağıtım bir Git gönderme işlemidir.
git add .
git commit -m "Kimlik doğrulama, hız sınırı ve katmanlı önbellek içeren ürünler ağ geçidi eklendi"
git push origin feature/products-gateway
Zuplo, her dal için bir önizleme ortamı oluşturur ve URL'yi yapı günlüğünde yazdırır. Önizleme, https://acme-gateway-feature-products-gateway-abc123.zuplo.app gibi kendi alt alan adına sahip olur; tüm ilkeleriniz aktif ve o ortam için ayarlanmış herhangi bir ORIGIN_URL'ye işaret eder.
Projenizde yeni bir ortam olarak ayarlayarak Apidog ile önizleme URL'sini test edin. Tam test paketini buna karşı çalıştırın. Her şey geçerse, dalı birleştirin.
git checkout main
git merge feature/products-gateway
git push origin main
Birleştirme, üretim dağıtımını tetikler. Altmış saniye içinde yeni sürüm 300'den fazla uç konumda yayında olur. Yükseltme ve geri alma her ikisi de git push işlemleridir; ayrı bir kullanıcı arayüzü yoktur.
Adım 8: Geliştirici portalını oluşturun
Portal, https://PROJENİZ.developers.zuplo.com adresinde barındırılır ve her dağıtımda yeniden oluşturulur. İçeriği:
- Her rota için şema, açıklama ve deneme konsolu içeren tek bir sayfa.
- cURL, JavaScript, Python, Go ve diğer birkaç dilde kod örnekleri.
- Kaydolan her ziyaretçi için kendi kendine API anahtarı verme.
- Geliştirici Portalı > Ayarlar altında portaldaki markalama kontrolleri.
OpenAPI spesifikasyonunuz iyi açıklamalara ve örneklere sahipse, portal başka bir işe gerek kalmadan bitmiş görünüyor. Spesifikasyonunuz zayıfsa, bunu şimdi öğrenirsiniz.
Özelleştirmek için, portal kaynak kodu, GitHub'daki Zuplo geliştirici portalı deposundan çatallayabileceğiniz ayrı bir Next.js uygulaması olarak gelir. Çoğu ekip barındırılan sürümü kullanır.
Adım 9: Her şeyi Apidog ile test edin
Ağ geçidiniz yayına girdikten sonra, üretimde sorunları önleyen disiplin, her rotayı, her ilkeyi ve her hata yolunu test etmektir. Apidog bunu hızlandırır.
İyi çalışan iş akışı:
- Ağ geçidinin OpenAPI spesifikasyonunu
https://PROJENİZ.zuplo.app/openapiadresinden içe aktarın. Apidog, her işlemi tetikleyebileceğiniz bir isteğe dönüştürür. local,previewveproductioniçin ortamlar oluşturun, her biri kendibase_urlveapi_key'sine sahip olsun.- Her rota için en az üç istek kaydedin: başarılı yol, kimlik doğrulama hatası ve hız sınırı tetikleyicisi. Her dağıtımdan önce bunları bir grup olarak çalıştırın.
- Apidog'un otomatik test senaryolarını kullanarak çağrıları zincirleyin (bir ürün oluşturun, listeleyin, silin) ve yanıt şekillerini doğrulayın.
- Ekibinizin ana dilinde kod örnekleri oluşturun ve bunları çalışma kitaplarınıza yapıştırın.
Postman'dan geçiş yapıyorsanız, Postman olmadan API testi kılavuzu içe aktarma işlemini adım adım anlatır. Henüz yapmadıysanız Apidog'u indirin.
Zuplo kullanımı hakkında sık sorulan sorular
Bir rotayı spesifikasyonu değiştirmeden ortamlar arasında nasıl değiştiririm?
Ortam değişkenlerini kullanın. Portaldaki Ayarlar'da veya yerel olarak config/.env içinde her ortam için ORIGIN_URL tanımlayın ve işleyici seçeneklerinin içinde ${env.ORIGIN_URL} olarak referans verin. Rota aynı kalır; sadece değişken değişir.
Zuplo'yu çevrimdışı çalıştırabilir miyim?
Evet. npm run dev, 9000 numaralı bağlantı noktasında yerel bir ağ geçidi ve 9100 numaralı bağlantı noktasında yerel Rota Tasarımcısı başlatır. Özel ilkeler, doğrulama ve hız sınırlaması yerel olarak çalışır; internet bağlantısı gerektiren tek şey yönetilen API anahtarı hizmetidir ve yerel örneğinizden bulut hizmetini kullanmak için npx zuplo link komutunu çalıştırabilirsiniz.
Kötü bir dağıtımı nasıl geri alırım?
Birleştirme commit'ini git revert yapın ve push edin. Zuplo önceki durumu yeniden dağıtır. Ayrı bir "geri al" düğmesi yoktur çünkü Git geçmişi doğruluk kaynağıdır.
Bir dağıtım sırasında devam eden isteklere ne olur?
Dağıtımlar uçta atomiktir; devam eden istekler eski sürümde tamamlanır ve yeni istekler yeni sürüme ulaşır. Kesinti süresi penceresi yoktur.
Zuplo'yu gRPC veya WebSockets ile kullanabilir miyim?
Evet. urlForwardHandler, WebSocket yükseltmelerini şeffaf bir şekilde proxy eder ve gRPC, gRPC işleyicisi aracılığıyla desteklenir. REST ve GraphQL birinci sınıf olup en yaygın durumdur.
Zuplo API'mı AI aracılarından nasıl erişime açarım?
Bir rotaya MCP Sunucu İşleyicisi'ni ekleyin, OpenAPI spesifikasyonunuza işaret edin ve açığa çıkarılacak işlemleri seçin. Aynı yetkilendirme ve hız sınırlaması ilkeleri MCP istekleri için de geçerlidir. Zuplo MCP Sunucu belgeleri kurulumu kapsar.
Üretimde ağ geçidi ne kadara mal olur?
Ücretsiz katman aylık 100 bin isteği kapsar. Builder planı aylık 25 dolara 1 milyon istek ekler ve ek istekler her 100 bin için 100 dolar tutarındadır. Kurumsal fiyatlandırma, yıllık sözleşmede aylık 1.000 dolardan başlar. Tam döküm Zuplo fiyatlandırma sayfasında.
Sonuç
Artık API anahtarı doğrulaması, anahtar başına hız sınırlaması, istek doğrulaması, özel bir TypeScript giden ilkesi ve bir geliştirici portalına sahip, hepsi Git aracılığıyla küresel uca dağıtılan çalışan bir Zuplo ağ geçidiniz var. Aynı proje, önizleme ortamlarını, üretim dağıtımlarını ve MCP aracılığıyla AI aracı erişimini yönetir.
Bunu stabil tutan parça test döngüsüdür. Her önizleme birleşmeden önce Apidog'u kullanın ve bozuk kimlik doğrulama başlıklarını, eksik şema alanlarını ve yanlışlıkla çok cömert olan hız sınırlarını gönderilmeden önce yakalayın. Apidog'u indirin ve bugün ağ geçidinize bağlayın.
düğme