Silgi'de Şemalar

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ı ve doğrulama kurallarını belirler. Her şema dört ana bölümden oluşur:

1. Namespace: API'nizi mantıksal olarak böler (örn. core, mobilya).
2. Service: Belirli bir işlevi temsil eder (örn. profile, product).
3. Method: HTTP metodu (get, post, put, delete, patch).
4. Action: O servis/metodun özel bir işlemi (örn. byId, create).

INFO

Silgi'de şemalar sadece 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.

URI Örneği:core/profile/get/byId veya mobilya/product/get/details

---

Ş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. /core/profile/:profileId).
• 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. Namespace Tanımlayın

Kullanacağınız namespace'leri silgi.config.ts dosyanızda belirtin:

silgi.config.ts

import { defineSilgiConfig } from 'silgi/config'

export default defineSilgiConfig({
  namespaces: ['core', 'mobilya'],
})

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

pnpm silgi prepare

---

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

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

server/schemas/profile.schema.ts

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

export const profileSchema = createSchema({
  core: {
    profile: {
      get: {
        byId: {
          input: z.object({}),
          output: z.object({
            id: z.string().uuid(),
            name: z.string(),
            email: z.string().email(),
          }),
          pathParams: z.object({
            profileId: z.string().uuid()
          }),
          queryParams: z.object({
            includeDetails: z.boolean().optional()
          })
        }
      }
    }
  }
})

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. Şemayı Servise Otomatik Bağlama

Şemalar ve servisler ayrı dosyalarda tanımlanır. Silgi, URI yapısına göre şemaları ve servisleri otomatik olarak eşleştirir. Şemayı createService fonksiyonuna manuel geçirmenize gerek yoktur.

server/services/profile.service.ts

import { createService } from 'silgi'

export const profileService = createService({
  core: {
    profile: {
      get: {
        byId: {
          handler: async (input, shared) => {
            const { profileId, includeDetails } = input.parameters
            // ...veritabanı işlemleri...
            return {
              id: profileId,
              name: 'Test Profili',
              email: '[email protected]'
            }
          }
        }
      }
    }
  }
})

---

4. Handler'da Parametrelere Erişim

Handler fonksiyonunuzda:

• input: Doğrulanmış istek gövdesi.
• input.parameters: pathParams ve queryParams'ın birleşimi.
• shared: Paylaşılan yardımcılar (ör. veritabanı).
• event: Framework'e özgü event nesnesi.
• source: İsteğin kaynağı.

handler: async (input, shared) => {
  const { profileId, includeDetails } = input.parameters
  // ...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 için de destek geliştirilmektedir.

Ş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ı URI yapısına 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: Sipariş Detayı Servisi

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

1. Şema Tanımı

server/schemas/order.schema.ts

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

const OrderItemSchema = z.object({
  productId: z.string().uuid(),
  name: z.string(),
  quantity: z.number().int().min(1),
  price: z.number().min(0)
})

const OrderSchema = z.object({
  id: z.string().uuid(),
  userId: z.string().uuid(),
  status: z.enum(['pending', 'completed', 'cancelled']),
  items: z.array(OrderItemSchema),
  total: z.number().min(0),
  createdAt: z.string().datetime()
})

export const orderSchema = createSchema({
  commerce: {
    order: {
      get: {
        detail: {
          input: z.object({}),
          output: OrderSchema,
          pathParams: z.object({
            orderId: z.string().uuid()
          }),
          queryParams: z.object({
            includeUser: z.boolean().optional()
          })
        }
      }
    }
  }
})

2. Servis Tanımı

server/services/order.service.ts

import { createService, ErrorFactory } from 'silgi'

export const orderService = createService({
  commerce: {
    order: {
      get: {
        detail: {
          handler: async (input, shared) => {
            const { orderId, includeUser } = input.parameters

            // Siparişi veritabanından çek
            const order = await shared.db.getOrderById(orderId)
            if (!order) {
              throw ErrorFactory.notFound('Sipariş bulunamadı')
            }

            // İsteğe bağlı olarak kullanıcı bilgisi ekle
            let user
            if (includeUser) {
              user = await shared.db.getUserById(order.userId)
            }

            // Yanıtı oluştur
            return {
              ...order,
              ...(user ? { user } : {})
            }
          }
        }
      }
    }
  }
})

3. Paylaşılan Yardımcı (Shared)

Veritabanı işlemlerini merkezi bir yerden yönetmek için shared yardımcı oluşturun. Tüm servisler otomatik olarak bu yardımcıya erişebilir.

server/shared/db.ts

import { createShared } from 'silgi'
import type { ExtendShared } from 'silgi/types'
import { useDatabase } from '../utils/db'

export interface SharedDatabase extends ExtendShared {
  database: ReturnType<typeof useDatabase>
}

export const db = createShared({
  database: useDatabase,
})

Dikkat

Export edilen shared yardımcılarınızın export const ile başlaması gerekmektedir. Aksi takdirde Silgi CLI bu yardımcıyı bulamaz.

TIP

Shared kodları yazdıktan sonra şu komutu çalıştırmayı unutmayın:

pnpm silgi prepare

---

Bu örnekte:

• Şema: Sipariş detayları, ilişkili ürünler ve opsiyonel kullanıcı bilgisi için yapılandırılmıştır.
• Servis: Hem path hem query parametrelerini kullanır, hata yönetimi uygular ve shared yardımcıya erişir.
• Shared: Veritabanı işlemleri için merkezi yardımcı fonksiyonlar sağlar.

Gerçek dünyadaki karmaşık API uç noktalarını Silgi ile bu şekilde tip güvenli, modüler ve okunabilir biçimde tanımlayabilirsiniz.