Contract First ve @feelai/contract: Veri Güvenli Uygulama Geliştirmeye Yeni Bir Yaklaşım

Modern yazılım geliştirme dünyasında, istemci ve sunucu arasındaki tutarlılığı sağlamak önemli bir zorluktur. Contract First yöntemi etkili bir çözüm olarak ortaya çıkmış ve şimdi @feelai/contract kütüphanesi tarafından güçlü bir şekilde desteklenmektedir.

Contract First: Önce Sözleşme Tanımlayan Programlama Yöntemi

Contract First, uygulama programlama arayüzünün (API) ayrıntılı uygulamadan önce belirlendiği bir yazılım geliştirme yöntemidir. API'yi belirlemeden önce kod yazmak yerine, bu yöntem şunları gerektirir:

Uç noktaları (endpoints), girişleri (input) ve çıkışları (output) açıkça tanımlama
İstemci ve sunucu arasında bir sözleşme (contract) oluşturma
Tanımlanmış sözleşmeye dayanarak her iki tarafı da paralel geliştirme

Contract First'ın faydaları şunlardır:

Ekipler arasındaki iletişim hatalarını en aza indirme
Ön uç (frontend) ve arka uç (backend) paralel geliştirmesine izin verme
Veri türü tutarlılığını sağlama
Test etme ve sahte veri (mock data) oluşturma kolaylığı

@feelai/contract: Contract First için TypeScript Kütüphanesi

@feelai/contract, TypeScript projelerinde Contract First yöntemini uygulamaya yardımcı olan bir npm kütüphanesidir. Bu kütüphane, istemci ve sunucu arasında döngüsel bağımlılık sorunları olmadan paylaşılabilen, tür-güvenli (type-safe) bir şekilde API sözleşmesini tanımlamak için araçlar sunar.

Öne Çıkan Özellikler

Tür Güvenliği: Şema tanımlamak için typebox kullanır
Merkezi Sözleşme Tanımı: API, Akış (Stream) ve Soket (Socket) sözleşmelerini tek bir yerde yönetir
Statik Tip Çıkarımı: Çalışma zamanı sözleşme tanımından TypeScript türlerini çıkarır
Sorumlulukların Ayrılması: API tanımını uygulama ayrıntılarından ayırır

Kurulum

bun add @feelai/contract
# veya
npm install @feelai/contract
# veya
yarn add @feelai/contract

Gerçek Uygulamada Kullanım

Aşağıda, görev yönetimi uygulaması için bir sözleşme tanımı örneği bulunmaktadır:

import { Contract, defineApiMap, defineSocketMap } from "@feelai/contract";
import { Type } from "typebox";

// Şema Tanımlama
export const TaskSchema = Type.Object({
  id: Type.String(),
  title: Type.String(),
  completed: Type.Boolean(),
  createdAt: Type.Number(),
});

// API uç noktalarını tanımlama
const api = defineApiMap({
  getTasks: {
    output: Type.Array(TaskSchema),
  },
  createTask: {
    input: Type.Object({
      title: Type.String(),
    }),
    output: TaskSchema,
  },
});

// Soket olaylarını tanımlama
const socket = defineSocketMap({
  taskUpdates: {
    client: {
      subscribe: Type.Object({}),
    },
    server: {
      taskCreated: TaskSchema,
      taskUpdated: TaskSchema,
    },
  },
});

// Sözleşmeyi oluşturma ve dışa aktarma
export const todoListContract = new Contract().api(api).socket(socket);
export type TodoListContract = typeof todoListContract;

Veri Tipi Çıkarımı

@feelai/contract'ın güçlü yanlarından biri otomatik tip çıkarımıdır:

import { StaticApiMap, StaticSocketMap } from "@feelai/contract";
import { todoListContract } from "./todoListContract";

// API uygulaması için Türler
export type ApiTypes = StaticApiMap<typeof todoListContract>;

// Soket uygulaması için Türler
export type SocketTypes = StaticSocketMap<typeof todoListContract>;

@feelai/contract Kullanmanın Faydaları

Paralel Geliştirme: Frontend ve backend ekipleri, tanımlanmış sözleşmeye dayanarak bağımsız çalışabilir
Hataları En Aza İndirme: Derleme zamanında yapılan tip kontrolü, hataların erken tespit edilmesine yardımcı olur
Otomatik Belgeler: Sözleşme, API için canlı belge görevi görür
Bakımı Kolay: API değişiklikleri tek bir yerde merkezi olarak yönetilir

Sonuç

Contract First yöntemi, @feelai/contract kütüphanesi ile birleştiğinde, modern web uygulama geliştirmeye yapılandırılmış bir yaklaşım sunar. Uçtan uca tür güvenliği sağlama, istemci ve sunucu arasındaki iletişim hatalarını en aza indirme ve paralel geliştirmeyi destekleme yetenekleriyle, orta ila büyük ölçekli TypeScript projeleri için değerli bir araçtır.

@feelai/contract hakkında daha fazla bilgi edinmek için şurayı ziyaret edin: https://www.npmjs.com/package/@feelai/contract