createSchema Kullanımı

Silgi'de şemalar, API'nizin veri sözleşmesini ve doğrulama kurallarını tanımlar. createSchema fonksiyonu ile oluşturulan şemalar, hem geliştirici deneyimini hem de uygulamanızın güvenilirliğini üst seviyeye taşır.

---

Neden Şema Kullanmalıyım?

• Uçtan Uca Tip Güvenliği: TypeScript ile tam tip kontrolü sağlar.
• Otomatik Doğrulama: Gelen ve giden veriler otomatik olarak doğrulanır.
• Kendi Kendini Belgeleyen API: Şemalar, API'nizin otomatik olarak belgelenmesini sağlar.
• Modülerlik & Yeniden Kullanım: Şemalarınızı farklı dosyalarda tutabilir, tekrar tekrar kullanabilirsiniz.
• Gelişmiş Geliştirici Deneyimi: IDE desteği, otomatik tamamlama ve hızlı hata yakalama.
• Otomatik Bağlama: Şemalarınız Silgi CLI tarafından otomatik olarak bulunur ve servislere bağlanır.
• Genişletilebilirlik: Modüller şemalara yeni parametreler ekleyebilir.

---

Şema Temelleri

Silgi'de şemalar, API'nizin veri yapısını, doğrulama kurallarını ve rotalarını belirler. Şemalar için temel yaklaşım şu şekildedir:

1. Path: API rotanızı tanımlayan yol (örn. /api/library/books/:id).
2. Method: HTTP metodu (GET, POST, PUT, DELETE, PATCH).
3. Setup: Şema konfigürasyonunu içerir (input, output, pathParams, queryParams).

INFO

Silgi'de şemalar kendi tanımlarınızla sınırlı değildir. Modüller, şemalara yeni tipler, parametreler veya doğrulama kuralları ekleyerek şemanın yapısını ve tiplerini dinamik olarak genişletebilir.

Rota Örneği:GET:/api/library/books/:id veya POST:/api/library/books/create

---

Şema Parametreleri

Her bir endpoint için aşağıdaki parametreleri tanımlayabilirsiniz:

• input: İstek gövdesi (body).
• output: Yanıt verisi.
• pathParams: URL yol parametreleri (örn. /:id).
• queryParams: URL sorgu parametreleri (örn. ?includeDetails=true).
• Ek Parametreler: Modüller tarafından eklenebilir.

---

Desteklenen Doğrulama Kütüphaneleri

Silgi, Standart Şema uyumlu kütüphaneleri destekler.

• Zod – Tam Destek ✅
• Arktype – Tam Destek ✅
• Valibot – Tam Destek ✅
• Typebox – Tam Destek ✅

---

Adım Adım Şema Oluşturma

0. Kurulum

silgi.config.ts

import { defineSilgiConfig } from 'silgi/config'

export default defineSilgiConfig({
  // Varsayılan: zod.
  // Projede birden fazla doğrulama kütüphanesi kullanmak mümkündür.
  // Tek bir kütüphane için: 'zod'
  // Birden fazla kütüphane için: ['arktype', 'zod', 'valibot']
  schemaVendor: 'zod',
  // ... diğer ayarlar
})

Paketleri ve gerekli bağımlılıkları yüklemek için aşağıdaki komutu çalıştırın:

pnpm silgi install

Şemalarınızı ve servislerinizi oluşturmak için Silgi CLI ile birlikte gelen silgi prepare komutunu çalıştırın:

pnpm silgi prepare

1. Önce Rotalarınızı Tanımlayın (Opsiyonel)

Rotalarınızı createRoute fonksiyonu ile tanımlayabilirsiniz. Bu adım opsiyoneldir, ancak daha organize bir kod yapısı sağlar.

book.ts

import { createRoute } from 'silgi'

export const getBookByIdRoute = createRoute({
  route: '/api/library/books/:id',
})

export const getBooksRoute = createRoute({
  route: '/api/library/books',
})

export const createBookRoute = createRoute({
  route: '/api/library/books/create',
})

---

2. Şemanızı Tanımlayın

Şemalarınızı server/schemas/ veya server/services/ altında tanımlayabilirsiniz.

book.ts

import { createSchema } from 'silgi'
import { z } from 'zod'

// Base types
const authorType = z.object({
  id: z.string(),
  name: z.string(),
})

const bookType = z.object({
  id: z.string(),
  name: z.string(),
  description: z.string().optional(),
  author: authorType.optional(),
})

export const getBookByIdSchema = createSchema({
  path: '/api/library/books/:id',
  method: ['GET'],
  setup: {
    pathParams: z.object({
      id: z.string(),
    }),
    queryParams: z.object({
      includeAuthor: z.boolean().optional(),
      format: z.enum(['full', 'summary']).optional(),
    }),
    output: bookType,
  },
})

export const getBooksSchema = createSchema({
  path: '/api/library/books',
  method: ['GET'],
  setup: {
    queryParams: z.object({
      limit: z.number().int().positive().optional(),
      offset: z.number().int().nonnegative().optional(),
      authorId: z.string().optional(),
      sortBy: z.enum(['name', 'date']).optional(),
    }),
    output: z.array(bookType),
  },
})

export const createBookSchema = createSchema({
  path: '/api/library/books/create',
  method: ['POST'],
  setup: {
    input: z.object({
      name: z.string(),
      description: z.string().optional(),
      authorId: z.string(),
    }),
    output: bookType,
  },
})

INFO

Export edilen şemanızın export const ile başlaması gerekmektedir. Aksi takdirde Silgi CLI şemayı bulamaz.

Tiplerin ve runtime dosyalarının güncellenmesi için tekrar:

pnpm silgi prepare

---

3. Servis İçindeki Şemaya Nasıl Erişirim?

Silgi, servislerde şema bilgilerini kullanmanızı sağlar. Servis handler'ınızda şema içinde tanımladığınız parametrelere erişebilirsiniz:

• input.parameters.path: URL yol parametreleri.
• input.parameters.query: URL sorgu parametreleri.
• input.args: POST/PUT/PATCH istek gövdesi.

handler: async (input, shared) => {
  const bookId = input.parameters.path?.id
  const includeAuthor = input.parameters.query?.includeAuthor
  // ...iş mantığı...
  return { /* doğrulanmış yanıt */ }
}

---

Şema Değişikliklerinde Ne Yapmalıyım?

Şemanızda bir değişiklik yaptığınızda, Silgi'nin tipleri ve runtime dosyalarını güncellemek için tekrar:

pnpm silgi prepare

komutunu çalıştırın.

---

Sıkça Sorulanlar

Farklı doğrulama kütüphaneleriyle çalışabilir miyim?

Evet, Zod dışında Standart Şema uyumlu diğer kütüphaneler de desteklenmektedir.

Şemalarımı modüller veya pluginler genişletebilir mi?

Evet, modüller ve pluginler şemalara yeni parametreler veya doğrulama kuralları ekleyebilir.

Şemalar otomatik olarak mı bağlanıyor?

Evet, aynı path yapısına ve HTTP metoduna sahip şema ve servisler otomatik olarak eşleştirilir.

---

Özet

Silgi şemaları ile API'nizin veri sözleşmesini, doğrulamasını ve tip güvenliğini kolayca yönetebilirsiniz. Otomatik bağlama, modülerlik ve güçlü doğrulama sayesinde hem hızlı hem de güvenilir backend servisleri geliştirmek artık çok daha kolay!

---

Gelişmiş Örnek: Kitap API'si

Aşağıda, şema tarafında gelişmiş özelliklerin nasıl kullanılabileceğine dair bir örnek bulabilirsiniz.

server/schemas/book.schema.ts

import { createRoute, createSchema } from 'silgi'
import { z } from 'zod'

// 1. Rotaları tanımla
export const getBookByIdRoute = createRoute({
  route: '/api/library/books/:id',
})

export const getBooksRoute = createRoute({
  route: '/api/library/books',
})

export const createBookRoute = createRoute({
  route: '/api/library/books/create',
})

// 2. Şemaları tanımla
const authorType = z.object({
  id: z.string(),
  name: z.string(),
})

const bookType = z.object({
  id: z.string(),
  name: z.string(),
  description: z.string().optional(),
  author: authorType.optional(),
})

export const getBookByIdSchema = createSchema({
  path: '/api/library/books/:id',
  method: ['GET'],
  setup: {
    pathParams: z.object({
      id: z.string(),
    }),
    queryParams: z.object({
      includeAuthor: z.boolean().optional(),
      format: z.enum(['full', 'summary']).optional(),
    }),
    output: bookType,
  },
})

export const getBooksSchema = createSchema({
  path: '/api/library/books',
  method: ['GET'],
  setup: {
    queryParams: z.object({
      limit: z.number().int().positive().optional(),
      offset: z.number().int().nonnegative().optional(),
      authorId: z.string().optional(),
      sortBy: z.enum(['name', 'date']).optional(),
    }),
    output: z.array(bookType),
  },
})

export const createBookSchema = createSchema({
  path: '/api/library/books/create',
  method: ['POST'],
  setup: {
    input: z.object({
      name: z.string(),
      description: z.string().optional(),
      authorId: z.string(),
    }),
    output: bookType,
  },
})

Bu örnekte:

1. Rotalar: API rotalarını tanımlar
2. Şemalar: Zod ile doğrulama ve tip tanımları

Silgi ile bu şekilde tip güvenli, modüler ve okunabilir API şemaları tanımlayabilirsiniz.