NitroJs ile Backend API'leri Nasıl Oluşturulur?

İlk üretim API'mi oluşturduğumda Express.js kullandım ve kurulum yaklaşık iki saat sürdü: şablon kodları, ara katman yazılımları, rota işleyicileri, TypeScript yapılandırması ve dağıtım betikleri. Yakın zamanda NitroJs kullanarak eksiksiz bir REST API'yi sadece 20 dakikada yayına aldım. app.use() zincirleri yok, manuel yönlendirme yok, dağıtım sorunları yok.

Bu kılavuz, NitroJs'in şablon kodlarını nasıl ortadan kaldırdığını ve size Node, Bun, Deno, sunucusuz veya uçta çalışan, üretime hazır bir arka uç sağladığını gösteriyor.

NitroJs Nedir ve Neden Arka Uç API'leri İçin Kullanılmalı?

NitroJs, arka ucunuzu bir derleme yapısı olarak ele alan UnJS ekosisteminden bir sunucu araç kitidir. Bir çalışma zamanına bağlı bir sunucu yazmak yerine, rota işleyicileri yazarsınız ve Nitro bunları taşınabilir bir pakete derler. Aynı kodu Node.js, Cloudflare Workers, Vercel veya bir Docker kapsayıcısına tek bir satır değiştirmeden dağıtabilirsiniz.

Temel zihinsel model: Sunucular değil, rotalar yazın. Siz API mantığına odaklanırsınız; Nitro HTTP, ara katman yazılımı ve platform entegrasyonunu halleder.

Arka uç API'leri için temel avantajlar:

Sıfır yapılandırma: server.js şablon kodu yok
Dosya sistemi yönlendirmesi: routes/users.get.ts, GET /users olur
TypeScript yerel: İşleyicilerden otomatik çıkarılan türler
Evrensel dağıtım: Tek derleme, birden çok hedef
Dahili önbellekleme: API yanıtlarını bellekte, Redis'te veya Cloudflare KV'de saklayın
Depolama katmanı: Geçici veriler için soyutlanmış dosya sistemi

API geliştiricileri için bu, altyapı değiştirirken daha hızlı dağıtım yapmanız ve daha az yeniden düzenleme yapmanız anlamına gelir.

button

Başlarken: NitroJs'i 5 Dakikada Kurun

Adım 1: Bir Proje Oluşturun

# pnpm kullanılıyor (önerilir)
pnpm dlx giget@latest nitro nitro-api-backend

# Veya npm
npm create nitro@latest nitro-api-backend

# Veya bun
bunx giget@latest nitro nitro-api-backend

Bu, resmi başlangıç şablonunu nitro-api-backend dizinine klonlar.

Adım 2: Yapıyı Keşfedin

cd nitro-api-backend
tree -L 2

Çıktı:

├── server
│   ├── api
│   ├── routes
│   ├── tasks
│   └── middleware
├── nitro.config.ts
├── package.json
└── tsconfig.json

Kritik dizinler:

server/api/: API rotaları (UI yok)
server/routes/: Tam yığın rotalar (SSR için)
server/middleware/: Global ara katman yazılımı
server/tasks/: Arka plan görevleri

Saf bir arka uç API'si için routes dizinini göz ardı edin ve her şeyi api dizinine koyun.

Adım 3: Geliştirme Sunucusunu Çalıştırın

pnpm install
pnpm dev

Nitro, sıcak yeniden yükleme ile http://localhost:3000 adresinde başlar. Bir dosyayı düzenleyin ve sunucu 200ms'den kısa sürede yeniden başlar.

İlk API Uç Noktanızı Oluşturma

Basit GET İşleyicisi

server/api/users.get.ts dosyasını oluşturun:

// server/api/users.get.ts
export default defineEventHandler(() => {
  return [
    { id: 1, name: "Alice", email: "alice@example.com" },
    { id: 2, name: "Bob", email: "bob@example.com" }
  ];
});

Nitro bunu otomatik olarak GET /api/users adresinde sunar. defineEventHandler sarmalayıcısı, tür güvenliği ve istek bağlamına erişim sağlar.

Parametreli Dinamik Rota

server/api/users/[id].get.ts dosyasını oluşturun:

// server/api/users/[id].get.ts
export default defineEventHandler((event) => {
  const id = getRouterParam(event, 'id');
  
  if (!id) {
    throw createError({
      statusCode: 400,
      statusMessage: 'User ID is required'
    });
  }
  
  return {
    id: Number(id),
    name: `User ${id}`,
    email: `user${id}@example.com`
  };
});

GET /api/users/42 adresine erişerek { id: 42, name: "User 42", ... } çıktısını görün.

JSON Gövdesi ile POST İsteği

server/api/users.post.ts dosyasını oluşturun:

// server/api/users.post.ts
export default defineEventHandler(async (event) => {
  const body = await readBody(event);
  
  // Nitro JSON'u otomatik olarak ayrıştırır
  const { name, email } = body;
  
  if (!name || !email) {
    throw createError({
      statusCode: 422,
      statusMessage: 'Name and email are required'
    });
  }
  
  // Veritabanı ekleme işlemini simüle edin
  const newUser = {
    id: Math.floor(Math.random() * 1000),
    name,
    email,
    createdAt: new Date().toISOString()
  };
  
  return newUser;
});

Şu şekilde test edin:

curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"Charlie","email":"charlie@example.com"}'

Tür Güvenli Yanıtlar

Nitro, dönüş değerlerinizden yanıt türlerini çıkarır. Katı sözleşmeler için açık türler kullanın:

// server/api/products.get.ts
interface Product {
  id: number;
  name: string;
  price: number;
  inStock: boolean;
}

export default defineEventHandler<Product[]>(() => {
  return [
    { id: 1, name: "Laptop", price: 1299.99, inStock: true },
    { id: 2, name: "Mouse", price: 29.99, inStock: false }
  ];
});

Artık bu uç noktayı içe aktaran istemciler tam IntelliSense desteği alır.

Gelişmiş API Desenleri

Kimlik Doğrulama İçin Ara Katman Yazılımı

server/middleware/auth.ts dosyasını oluşturun:

// server/middleware/auth.ts
export default defineEventHandler(async (event) => {
  const protectedRoutes = ['/api/admin', '/api/users/me'];
  
  if (protectedRoutes.some(route => event.path.startsWith(route))) {
    const token = getHeader(event, 'authorization')?.replace('Bearer ', '');
    
    if (!token || token !== process.env.API_SECRET) {
      throw createError({
        statusCode: 401,
        statusMessage: 'Unauthorized'
      });
    }
  }
});

Ara katman yazılımı her rotadan önce çalışır. Bunu nitro.config.ts dosyasına ekleyin:

// nitro.config.ts
export default defineNitroConfig({
  srcDir: 'server',
  runtimeConfig: {
    apiSecret: process.env.API_SECRET
  }
});

API Yanıtlarını Önbelleğe Alma

Maliyetli hesaplamaları 60 saniye boyunca önbelleğe alın:

// server/api/stats.get.ts
export default defineCachedEventHandler(async () => {
  const db = useStorage('data');
  const users = await db.getItem('users') || [];
  
  return {
    totalUsers: users.length,
    activeUsers: users.filter(u => u.lastSeen > Date.now() - 86400000).length
  };
}, {
  maxAge: 60, // saniye
  name: 'stats',
  getKey: () => 'global-stats'
});

Nitro, önbellek geçersiz kılma ve depolamayı (dağıtım hedefine bağlı olarak bellek, Redis veya Cloudflare KV) yönetir.

Dosya Yükleme İşlemi

// server/api/upload.post.ts
export default defineEventHandler(async (event) => {
  const files = await readMultipartFormData(event);
  
  if (!files?.length) {
    throw createError({ statusCode: 400, statusMessage: 'No files uploaded' });
  }
  
  const storage = useStorage('uploads');
  const file = files[0];
  
  await storage.setItem(file.filename, file.data);
  
  return { success: true, filename: file.filename };
});

Şu şekilde test edin:

curl -X POST http://localhost:3000/api/upload \
  -F "file=@/path/to/image.jpg"

Dağıtım: Yerelden Üretime

Üretim İçin Derleme

pnpm build

Nitro, platforma özgü giriş noktaları içeren bir `.output` dizini oluşturur.

Node.js Üzerinde Çalıştırın

node .output/server/index.mjs

`node_modules` gerekmez—derleme her şeyi paketler.

Cloudflare Workers'a Dağıtım

# Ön ayarı kurun
pnpm add -D nitro-preset-cloudflare-workers

# Ön ayarla derleyin
NITRO_PRESET=cloudflare-workers pnpm build

# Dağıtın
wrangler deploy .output

Vercel'e Dağıtım (Sunucusuz)

# Vercel Nitro'yu otomatik olarak algılar
vercel

Veya nitro.config.ts dosyasını yapılandırın:

export default defineNitroConfig({
  preset: 'vercel-edge'
});

Ortam Değişkenleri

Yerel olarak .env oluşturun, ardından üretimde platform panolarını kullanın:

# .env
API_SECRET=dev-secret-key
DATABASE_URL=file:./dev.db

İşleyicilerde erişim:

const config = useRuntimeConfig();
const secret = config.apiSecret;

Gelişmiş Kullanım Senaryoları

WebSockets ve Sunucu Tarafından Gönderilen Olaylar

Nitro, defineWebSocketHandler aracılığıyla WebSockets'i destekler:

// server/api/ws.ts
export default defineWebSocketHandler({
  open(peer) {
    console.log('WebSocket connected:', peer);
  },
  message(peer, message) {
    peer.send(`Echo: ${message.text()}`);
  },
  close(peer, details) {
    console.log('WebSocket closed:', details);
  }
});

ws://localhost:3000/api/ws adresinden erişin.

Arka Plan Görevleri

server/tasks/cleanup.ts dosyasını oluşturun:

// server/tasks/cleanup.ts
export default defineCronHandler('0 2 * * *', async () => {
  const db = useStorage('temp');
  const keys = await db.getKeys();
  
  for (const key of keys) {
    const metadata = await db.getMeta(key);
    if (metadata.expiresAt < Date.now()) {
      await db.removeItem(key);
    }
  }
  
  console.log('Cleanup completed');
});

Bu, her gün sabah 2'de çalışır. Cron desteği olan bir platforma (örn. Vercel, Netlify) dağıtın.

İş Akışı Motorları

Karmaşık orkestrasyon için useWorkflow.dev ile entegre edin:

// server/api/workflows/process.ts
import { createWorkflow } from '@useworkflow/sdk';

export default defineEventHandler(async (event) => {
  const workflow = createWorkflow('data-pipeline', {
    steps: [
      { id: 'fetch', run: 'https://api.example.com/data' },
      { id: 'transform', run: 'transform.js' },
      { id: 'store', run: async (data) => {
        const storage = useStorage('results');
        await storage.setItem('latest', data);
      }}
    ]
  });
  
  await workflow.start();
  return { status: 'started' };
});

Gerçek Geliştirici Senaryoları

Senaryo 1: Statik Site Arka Ucu

Statik bir JAMstack sitesine JSON verileri sunan bir Nitro API'yi Cloudflare Workers'a dağıtın. Ücretsiz katman günde 100 bin isteği işler.

Senaryo 2: Mobil Uygulama API'si

Bir React Native uygulaması için REST uç noktaları oluşturun. Nitro'nun dahili CORS işleme özelliğini kullanın:

// nitro.config.ts
export default defineNitroConfig({
  routeRules: {
    '/api/**': { cors: true }
  }
});

Senaryo 3: Mikroservis Ağ Geçidi

Nitro'yu mikroservisleri bir araya getiren bir API ağ geçidi olarak çalıştırın. İstekleri vekil sunucu üzerinden yönlendirmek için $fetch kullanın:

// server/api/aggregate.get.ts
export default defineEventHandler(async (event) => {
  const [users, posts] = await Promise.all([
    $fetch('https://users-service.internal/users'),
    $fetch('https://posts-service.internal/posts')
  ]);
  
  return { users, posts };
});

Apidog ile NitroJs API'lerinizi Test Edin

Nitro arka uçları hızlı bir şekilde oluşturur, ancak uç noktalarınız bozulursa hız hiçbir anlam ifade etmez. Yeni bir POST /api/users yayınladığınızda, rota tanımını Apidog'a aktarın. İşleyicinizin dönüş türünü tersine mühendislikle çözümler ve sözleşme testlerini otomatik olarak oluşturur.

button

Kırılma yaratan değişiklikleri ön uç ekibiniz çileden çıkmadan yakalamak için bunları CI'da çalıştırın. Başlamak ücretsizdir ve hızlı Nitro geliştirmenizin ihtiyacı olan güvencedir.

Sıkça Sorulan Sorular

1. Nitro Express.js'i tamamen değiştirebilir mi?
Evet. Nitro, yönlendirme, ara katman yazılımı ve dağıtımı daha iyi yönetir. Express ara katman yazılımını Nitro eklentilerine ve rotaları server/api/ dizinine taşıyarak geçiş yapın.

2. Nitro veritabanı bağlantılarını nasıl yönetir?
Başlangıçta havuzları başlatmak için Nitro eklentilerini kullanın. Depolama katmanı önbelleklemeyi soyutlar, ancak SQL için kendi ORM'inizi (Prisma, Drizzle) getirin.

3. Nitro üretime hazır mı?
Kesinlikle. Nuxt, milyonlarca üretim sitesi için Nitro'yu kullanıyor. Ölçek için defalarca test edilmiş bir yapıdır.

4. Nitro'yu GraphQL ile kullanabilir miyim?
Evet. server/api/graphql.post.ts içinde bir GraphQL işleyicisi ekleyin. Herhangi bir Node GraphQL kütüphanesini kullanın—Nitro sizi kısıtlamaz.

5. Nitro ve Hono arasındaki fark nedir?
Hono hafif bir yönlendiricidir. Nitro ise derlemeler, ön ayarlar ve depolama ile eksiksiz bir sunucu araç kitidir. Mikroservisler için Hono'yu, tam arka uçlar için Nitro'yu kullanın.

Sonuç

NitroJs, API'nizi taşınabilir bir yapıya derleyerek arka uç geliştirmeyi yeniden düşünür. Şablon kodlarına ihtiyaç duymadan dosya sistemi yönlendirmesi, TypeScript güvenliği ve evrensel dağıtım elde edersiniz. Bir sonraki REST API'nizi Nitro ile oluşturun ve Apidog ile doğrulayın. Node'dan uç (edge) ortama tek bir yapılandırma satırıyla geçiş yaptığınızda gelecekteki benliğiniz size teşekkür edecek.

button