createService Kullanımı

Silgi'de createService, bir API endpoint'inin iş mantığını ve handler fonksiyonunu tanımlamak için kullanılır. Her servis, bir route ve şema ile ilişkilidir ve gelen isteklere yanıt veren ana fonksiyondur.

Temel Kullanım

import { createError, createService } from 'silgi'

export const getBookByIdService = createService({
  path: 'GET:/api/library/books/:id',
  setup: {
    handler: async (input, shared) => {
      // İş mantığınız burada
      const bookId = input.parameters.path?.id
      if (!bookId) {
        throw createError({
          statusCode: 400,
          message: 'Book ID is required'
        })
      }
      return {
        id: bookId,
        name: 'Sample Book',
      }
    }
  }
})

Parametreler

• path: Servisin dinleyeceği route ve HTTP metodunu belirtir. (Örn: 'GET:/api/library/books/:id')
• setup: Servisin ana yapılandırma objesidir ve aşağıdaki alanlardan oluşur:
  • handler: Servisin ana iş mantığını barındıran fonksiyon. (Zorunlu)
  • rules: Servise özel router ayarları (örn. erişim kuralları, rate limit vb.).
  • modules: Modüllerden gelen ek ayarları içeren obje. (örn. auth, metrics, logger gibi modül konfigürasyonları)
  • storage: unstorage destekli universal key-value depolama. 20+ farklı sürücü ile çalışabilen, unified bir anahtar-değer saklama API'si sağlar. Servis handler'ında shared.storage ile erişebilirsiniz.

Handler Fonksiyonu

Handler fonksiyonu, gelen isteği işler ve yanıtı döner. Handler'ın imzası:

(
  input: ServiceHandlerInput<Schema, Route, HiddenParameters>,
  shared?: SilgiRuntimeShareds,
  event?: SilgiEvent,
  source?: ServiceHandlerSource<Schema, Route>
) => Promise<any>

Parametreler:

• input: İstekten gelen path, query, body gibi parametreleri içerir.
• shared: Paylaşılan yardımcı fonksiyonlara ve altyapı araçlarına erişim sağlar.
• event: İstekle ilgili framework veya altyapı olaylarını içerir. event.req ve event.res gibi özelliklere erişim sağlar.
• source: (Opsiyonel) Handler'ın çağrıldığı kaynak veya ek meta bilgiler. Bunu graphql gibi moduller için kullanabilirsiniz.

Gelişmiş Kullanım

• Paylaşılan Yardımcılar: Handler içinde shared ile ortak fonksiyonlara erişebilirsiniz.
• Hata Yönetimi: createError ile anlamlı hata fırlatabilirsiniz.
• Tip Güvenliği: Route ve şema ile otomatik tip çıkarımı yapılır.

Örnek: Paylaşılan Yardımcı ile Kullanım

import { createError, createService } from 'silgi'

export const getBookByIdService = createService({
  path: 'GET:/api/library/books/:id',
  setup: {
    handler: async (input, shared, event, source) => {
      const bookId = input.parameters.path?.id
      if (!bookId) {
        throw createError({
          statusCode: 400,
          message: 'Book ID is required'
        })
      }
      // Paylaşılan yardımcı kullanımı
      const name = shared.formatBookName('Sample Book')
      return {
        id: bookId,
        name,
      }
    }
  }
})

Sıkça Sorulanlar

• Bir serviste hangi parametreler bulunur? Handler fonksiyonuna input ve shared parametreleri otomatik olarak gelir.

• Servisler otomatik olarak mı route ve şemaya bağlanır? Evet, route ve şema tanımlarınız ile birlikte pnpm silgi prepare komutunu çalıştırdığınızda servisler otomatik olarak bağlanır ve tip güvenliği sağlanır.

---