- Moderatör
- #1
- Kayıtlı
- 1 Yıl 9 Ay 26 Gün
- Katılım
- 10 Ocak 2025
- Konular
- 163
- Mesajlar
- 257
- Tepkime puanı
- 36
- Online süresi
- 11h 19m
- Puan
- 53
- Konum
- Türkiye
- Web sitesi
- www.zyncra.shop
Konu İçeriği — Hızlı Bakış (
cPanel / Web • ⏱ ~5 dk okuma •
Kod: SQL)
01. Hono + Zod ile Tip Güvenli API Geliştirmek: Doğrulama, TypeScript ve OpenAPI
02. 1. Hono nedir?
03. 2. Zod neden gerekli?
04. 3. Projeyi oluşturalım
05. 4. Zod ile veri şeması tanımlama
06. 5. Hono ile doğrulanan API endpoint'i oluşturma
Hono + Zod ile Tip Güvenli API Geliştirmek: Doğrulama, TypeScript ve OpenAPI
Modern web uygulamalarında API geliştirirken yalnızca doğru HTTP yanıtlarını döndürmek yeterli değildir. Gelen verilerin doğrulanması, TypeScript tiplerinin tutarlı tutulması ve API dokümantasyonunun güncel olması da en az iş mantığı kadar önemlidir.
Bu yazıda Hono, Zod ve OpenAPI kullanarak daha güvenilir, bakımı kolay ve tip güvenli bir REST API'nin nasıl geliştirilebileceğini inceleyeceğiz.
1. Hono nedir?
Hono, Web Standard API'leri üzerine kurulmuş hafif bir web framework'üdür.
Node.js, Bun, Deno ve Cloudflare Workers gibi farklı JavaScript çalışma ortamlarında kullanılabilir.Hono'nun öne çıkan özellikleri şunlardır:
- Hafif ve modüler bir yapı sunması
- TypeScript ile çalışmaya uygun olması
- Middleware desteği
- Farklı JavaScript runtime ortamlarında çalışabilmesi
- Zod tabanlı doğrulama ve OpenAPI entegrasyonu
Özellikle küçük ve orta ölçekli REST API projelerinde hızlı bir başlangıç yapmak isteyen geliştiriciler için değerlendirilebilecek bir seçenektir.
2. Zod neden gerekli?
TypeScript, geliştirme aşamasında veri tiplerini kontrol eder. Ancak bir istemciden gelen JSON verisinin gerçekten beklenen yapıda olduğunu tek başına garanti etmez.
Örneğin API'miz aşağıdaki veriyi bekliyor olsun:
{
"title": "Yeni görev",
"status": "todo"
}
İstemci aşağıdaki gibi hatalı bir veri gönderirse ne olacak?
{
"title": "",
"status": "unknown"
}
Yalnızca TypeScript interface kullanmak bu veriyi çalışma zamanında doğrulamaz. İşte Zod burada devreye girer.
Zod ile verinin yapısını tanımlayabilir, gelen veriyi çalışma zamanında doğrulayabilir ve TypeScript tiplerini aynı şemadan türetebiliriz.
3. Projeyi oluşturalım
Öncelikle
Node.js ve npm yüklü bir ortamda yeni bir proje oluşturalım:mkdir hono-type-safe-api
cd hono-type-safe-api
npm init -y
npm install hono @hono/zod-openapi @scalar/hono-api-reference zod
npm install -D typescript tsx @types/node
Basit bir geliştirme komutu eklemek için
package.json dosyasındaki scripts alanını düzenleyelim:{
"scripts": {
"dev": "tsx watch src/index.ts"
}
}
Ardından
src/index.ts dosyasını oluşturalım.4. Zod ile veri şeması tanımlama
Bir görev oluşturma isteğinde başlık ve durum bilgilerini kabul edelim:
import { z } from "@hono/zod-openapi";
export const createTaskSchema = z.object({
title: z.string().min(1).max(120),
status: z
.enum(["todo", "in_progress", "done"])
.default("todo"),
});
export type CreateTaskInput =
z.infer<typeof createTaskSchema>;
Burada birkaç önemli nokta bulunuyor:
- z.string() başlığın metin olmasını zorunlu kılar.
- min(1) boş başlıkları engeller.
- max(120) başlığın uzunluğunu sınırlar.
- z.enum() yalnızca belirlenen durumların kabul edilmesini sağlar.
- z.infer sayesinde TypeScript tipi yeniden elle yazılmaz.
Böylece doğrulama kuralları ve TypeScript tipi arasında gereksiz tekrar oluşmaz.
5. Hono ile doğrulanan API endpoint'i oluşturma
Şimdi şemayı bir HTTP endpoint'ine bağlayalım:
import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
import { apiReference } from "@scalar/hono-api-reference";
import { z } from "@hono/zod-openapi";
const app = new OpenAPIHono();
const createTaskSchema = z.object({
title: z.string().min(1).max(120),
status: z
.enum(["todo", "in_progress", "done"])
.default("todo"),
});
const taskSchema = z.object({
id: z.string().uuid(),
title: z.string(),
status: z.enum(["todo", "in_progress", "done"]),
});
const createTaskRoute = createRoute({
method: "post",
path: "/tasks",
request: {
body: {
content: {
"application/json": {
schema: createTaskSchema,
},
},
},
},
responses: {
201: {
description: "Görev başarıyla oluşturuldu",
content: {
"application/json": {
schema: taskSchema,
},
},
},
},
});
app.openapi(createTaskRoute, (c) => {
const input = c.req.valid("json");
const task = {
id: crypto.randomUUID(),
title: input.title,
status: input.status,
};
return c.json(task, 201);
});
app.doc("/doc", {
openapi: "3.0.0",
info: {
title: "Tasks API",
version: "1.0.0",
},
});
app.get(
"/reference",
apiReference({
spec: { url: "/doc" },
}),
);
export default app;
Bu örnek, bir görev oluşturma endpoint'inin temel yapısını gösterir. Uygulama gerçek bir sunucuda çalıştırılmadan önce kullanılan Hono sürümüyle uyumlu bir başlatma dosyası ve gerekli TypeScript yapılandırması da eklenmelidir.
Ayrıca bu örnekte görevler veritabanına kaydedilmiyor; veri yalnızca yanıt oluşturmak için kullanılıyor.
6. OpenAPI dokümantasyonu ne işe yarar?
API geliştirirken endpoint'lerin hangi parametreleri kabul ettiğini, hangi yanıtları döndürdüğünü ve olası hata kodlarını belgelemek gerekir.
OpenAPI, bu bilgileri standart bir formatta ifade etmeyi sağlar.
Yukarıdaki yapılandırmayla:
- /doc adresinden OpenAPI JSON tanımı alınabilir.
- /reference adresinden etkileşimli API dokümantasyonu görüntülenebilir.
- İstek ve yanıt şemaları endpoint tanımlarıyla birlikte tutulabilir.
Bunun en önemli avantajı, API değiştiğinde dokümantasyonun da aynı tanımlardan üretilebilmesidir.
7. Veritabanı şeması ile API şemasını ayırmak
Bir API'de istemciden alınan veri ile veritabanında saklanan veri her zaman aynı olmak zorunda değildir.
Örneğin veritabanında passwordHash alanı bulunabilir. Ancak bu alanın API yanıtında istemciye gönderilmesi ciddi bir güvenlik hatası olur.
Bu nedenle:
- Veritabanı şeması, verinin nasıl saklandığını tanımlar.
- İstek şeması, istemciden hangi verilerin kabul edileceğini belirler.
- Yanıt şeması, istemciye hangi verilerin gönderilebileceğini sınırlar.
Bu ayrım hem güvenlik hem de bakım kolaylığı açısından önemlidir.
8. Üretim ortamında dikkat edilmesi gerekenler
Gerçek projelerde aşağıdaki konular da ele alınmalıdır:
- Bütün hatalar için tutarlı bir yanıt formatı oluşturmak
- Kimlik doğrulama ve yetkilendirme eklemek
- Rate limiting ve CORS politikalarını doğru yapılandırmak
- Hassas bilgileri loglara yazmamak
- Veritabanı işlemlerini ayrı servis katmanlarında yönetmek
- API endpoint'lerini otomatik testlerle kontrol etmek
- Ortam değişkenlerini doğrulamak
Tip güvenliği tek başına uygulamayı güvenli hale getirmez. İstek doğrulama, erişim kontrolü ve hata yönetimi birlikte ele alınmalıdır.
Sonuç
Hono, Zod ve OpenAPI entegrasyonu, API sözleşmesini kod içerisinde merkezi olarak tanımlamaya yardımcı olur. Böylece çalışma zamanı doğrulaması, TypeScript tipleri ve dokümantasyon arasındaki tutarsızlıkların azaltılması mümkün hale gelir.
Özellikle TypeScript tabanlı backend projelerinde bu yaklaşım, API'lerin daha öngörülebilir ve sürdürülebilir olmasını sağlayabilir.
SQL ile Bölgesel Anahtarlı Tablo Şeması
SQL:
CREATE TABLE orders (
order_id UUID NOT NULL DEFAULT gen_random_uuid(),
region_code STRING NOT NULL,
customer_id INT8 NOT NULL,
payload JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
PRIMARY KEY (region_code, order_id)
);
CREATE INDEX idx_orders_customer ON orders (customer_id, created_at DESC);Sıkça Sorulan Sorular (SSS)
Soru 1: Paylaşılan SQL örneği canlı (production) ortamda kullanılabilir mi?
Evet. Konudaki kod bloğu bellek güvenliği, hata yakalama ve performans kriterleri gözetilerek hazırlanmıştır; kendi proje mimarinize uyarlayarak doğrudan kullanabilirsiniz.
Soru 2: Hono + Zod ile Tip Güvenli API Geliştirmek ve OpenAPI Dokümantasyonu Oluşturmak uygulamasında en sık yapılan hata nedir?
Girdi doğrulamasını (validation) ve zaman aşımı/kaynak sınırlarını varsayılan değerlerde bırakmaktır. Rehberdeki yapılandırma adımlarını eksiksiz uygulayarak olası darboğazları önleyebilirsiniz.
Evet. Konudaki kod bloğu bellek güvenliği, hata yakalama ve performans kriterleri gözetilerek hazırlanmıştır; kendi proje mimarinize uyarlayarak doğrudan kullanabilirsiniz.
Soru 2: Hono + Zod ile Tip Güvenli API Geliştirmek ve OpenAPI Dokümantasyonu Oluşturmak uygulamasında en sık yapılan hata nedir?
Girdi doğrulamasını (validation) ve zaman aşımı/kaynak sınırlarını varsayılan değerlerde bırakmaktır. Rehberdeki yapılandırma adımlarını eksiksiz uygulayarak olası darboğazları önleyebilirsiniz.
