HonoJS, Drizzle ORM ve Neon ile Başlangıç Dostu Bir Todo API Geliştirme Rehberi
Modern web uygulamaları geliştirmek, hızlı, verimli ve ölçeklenebilir backend çözümleri gerektirir. Bu rehberde, hafif ve performans odaklı bir web framework’ü olan HonoJS’i, tip güvenli ve minimalist Drizzle ORM’i ve sunucusuz PostgreSQL veritabanı çözümü Neon’u kullanarak sıfırdan bir Todo API’si geliştirmeyi adım adım öğreneceksiniz. Bu kombinasyon, özellikle sunucusuz (serverless) ortamlarda yüksek performans ve geliştirici deneyimi sunar.
1. Modern Web Geliştirme Mimarisine Genel Bakış
Günümüzün dinamik web projelerinde, doğru teknoloji seçimleri projenin başarısı için kritik öneme sahiptir. HonoJS, Drizzle ORM ve Neon üçlüsü, özellikle hızlı prototipleme ve ölçeklenebilir mikroservisler için ideal bir kombinasyon sunar.
1.1. Neden HonoJS?
HonoJS, Web Standartları API’leri üzerine inşa edilmiş, ultra hızlı ve hafif bir web framework’üdür. Edge ortamlarında (Cloudflare Workers, Vercel Edge Functions vb.) ve Node.js’te sorunsuz çalışır. Minimalist yapısı, TypeScript desteği ve performans odaklı tasarımı sayesinde, hızlı API’ler geliştirmek için mükemmel bir seçimdir. Geliştirici deneyimini ön planda tutarak, routing, middleware ve validasyon gibi temel API gereksinimlerini kolayca karşılar.
1.2. Neden Drizzle ORM?
Drizzle ORM, TypeScript’i tam anlamıyla destekleyen, minimalist ve tip güvenli bir Object-Relational Mapper’dır. SQL sorgularını doğrudan yazmaya yakın bir deneyim sunarken, şema tanımlamalarını TypeScript ile yapmanızı sağlar. Bu, veritabanı şemanız ile uygulama kodunuz arasında mükemmel bir senkronizasyon ve tip güvenliği sağlar. Drizzle, performans ve geliştirici verimliliği açısından öne çıkar.
1.3. Neden Neon (Serverless PostgreSQL)?
Neon, sunucusuz (serverless) mimariye sahip, esnek ve ölçeklenebilir bir PostgreSQL veritabanı hizmetidir. İhtiyaç duyulduğunda otomatik olarak ölçeklenir ve kullanılmadığında duraklatılarak maliyet avantajı sunar. Geliştirme ve dağıtım süreçlerini basitleştiren, dallanma (branching) gibi özellikleriyle modern geliştirme iş akışlarına mükemmel uyum sağlar. Küçük projelerden büyük ölçekli uygulamalara kadar geniş bir kullanım alanına sahiptir.
2. Proje Ortamını Hazırlama
API geliştirmeye başlamadan önce gerekli araçları kurmalı ve proje yapımızı oluşturmalıyız.
2.1. Ön Gereksinimler
- Node.js: En az 18.x sürümü önerilir.
- npm veya Yarn: Paket yöneticisi.
- Git: Versiyon kontrol sistemi (isteğe bağlı ama önerilir).
2.2. HonoJS Projesini Başlatma
Yeni bir HonoJS projesi oluşturmak için aşağıdaki komutu kullanabilirsiniz. Bu komut, temel bir HonoJS projesi yapısını ve gerekli bağımlılıkları otomatik olarak kuracaktır.
npm create hono@latest my-todo-api
cd my-todo-api
2.3. Gerekli Paketleri Kurma
Şimdi Drizzle ORM, PostgreSQL sürücüsü ve dotenv gibi ek paketleri projemize dahil edelim.
npm install drizzle-orm pg dotenv
npm install -D drizzle-kit @types/pg
drizzle-orm: Drizzle ORM'in çekirdek paketi.pg: Node.js için PostgreSQL istemcisi.dotenv: Ortam değişkenlerini yönetmek için.drizzle-kit: Drizzle CLI araçları (migrasyonlar, şema çıkarma vb.).@types/pg:pgpaketi için TypeScript tipleri.
2.4. TypeScript Yapılandırması
HonoJS projeniz zaten TypeScript ile yapılandırılmış olacaktır. Ancak, Drizzle ORM'in CLI araçlarını kullanabilmek için tsconfig.json dosyanızda bazı ayarlara ihtiyacınız olabilir. Genellikle, Hono'nun varsayılan yapılandırması yeterlidir.
3. Veritabanı Yapılandırması ve Drizzle ORM Kurulumu
Veritabanı bağlantısını kurmak ve şemamızı Drizzle ile tanımlamak projemizin temelini oluşturur.
3.1. Neon Hesabı Oluşturma ve Veritabanı Hazırlama
- Neon.tech adresine gidin ve ücretsiz bir hesap oluşturun.
- Yeni bir proje oluşturun ve bir veritabanı adı belirleyin (örneğin,
todo_db). - Projenizin panosundan "Connection Details" bölümüne gidin ve "Connection String"i kopyalayın. Bu bağlantı dizesini daha sonra kullanacağız.
3.2. Drizzle ORM ve PostgreSQL Bağlantısı
Projenizin kök dizininde bir .env dosyası oluşturun ve Neon'dan kopyaladığınız bağlantı dizesini buraya ekleyin:
DATABASE_URL="postgresql://[kullanici]:[sifre]@[host]/[veritabani]?sslmode=require"
Şimdi, veritabanı bağlantımızı kuracak bir dosya oluşturalım (örneğin, src/db/index.ts):
// src/db/index.ts
import { drizzle } from 'drizzle-orm/pg-driver';
import { Pool } from 'pg';
import 'dotenv/config';
if (!process.env.DATABASE_URL) {
throw new Error('DATABASE_URL is not set');
}
const pool = new Pool({
connectionString: process.env.DATABASE_URL,
ssl: {
rejectUnauthorized: false, // Geliştirme ortamında gerekli olabilir, üretimde true olmalı
},
});
export const db = drizzle(pool);
3.3. Şema Tanımlama (Todos Tablosu)
src/db/schema.ts adında bir dosya oluşturarak Todo tablosunun şemasını tanımlayalım:
// src/db/schema.ts
import { pgTable, serial, text, boolean, timestamp } from 'drizzle-orm/pg-core';
export const todos = pgTable('todos', {
id: serial('id').primaryKey(),
title: text('title').notNull(),
completed: boolean('completed').default(false).notNull(),
createdAt: timestamp('created_at').defaultNow().notNull(),
});
export type Todo = typeof todos.$inferSelect; // SELECT işlemleri için tip
export type NewTodo = typeof todos.$inferInsert; // INSERT işlemleri için tip
3.4. Migrasyonları Yönetme
Drizzle Kit'i kullanarak veritabanı şemamızı oluşturabilir ve güncelleyebiliriz. Öncelikle drizzle.config.ts dosyasını projenizin kök dizininde oluşturun:
// drizzle.config.ts
import type { Config } from 'drizzle-kit';
import 'dotenv/config';
export default {
schema: './src/db/schema.ts',
out: './drizzle', // Migrasyon dosyalarının kaydedileceği dizin
driver: 'pg',
dbCredentials: {
connectionString: process.env.DATABASE_URL!,
},
} satisfies Config;
Şimdi şemamızı algılamak ve bir migrasyon dosyası oluşturmak için:
npx drizzle-kit generate
Bu komut, drizzle klasöründe yeni bir migrasyon dosyası oluşturacaktır. Veritabanına bu migrasyonu uygulamak için:
npx drizzle-kit push
Artık Neon veritabanınızda todos tablosu oluşturulmuş olmalı.
4. HonoJS ile API Uç Noktalarını Geliştirme
Şimdi HonoJS kullanarak Todo API'mızın CRUD (Create, Read, Update, Delete) operasyonlarını tanımlayalım.
4.1. Todo Modelini Oluşturma
src/index.ts dosyanızı açın. Daha önce oluşturduğumuz db ve schema dosyalarını import edeceğiz.
// src/index.ts (veya src/app.ts olarak ayırabilirsiniz)
import { Hono } from 'hono';
import { db } from './db';
import { todos, NewTodo } from './db/schema';
import { eq } from 'drizzle-orm';
import { z } from 'zod'; // Validasyon için
import { zValidator } from '@hono/zod-validator'; // Hono için Zod entegrasyonu
const app = new Hono();
// Zod şemaları ile validasyon tanımları
const createTodoSchema = z.object({
title: z.string().min(1, 'Başlık boş olamaz.'),
});
const updateTodoSchema = z.object({
title: z.string().min(1, 'Başlık boş olamaz.').optional(),
completed: z.boolean().optional(),
});
4.2. Tüm Todoları Getirme (GET /todos)
Tüm todoları veritabanından çekmek için basit bir GET uç noktası oluşturalım:
// src/index.ts
app.get('/todos', async (c) => {
const allTodos = await db.select().from(todos);
return c.json(allTodos);
});
4.3. Yeni Todo Ekleme (POST /todos)
Yeni bir todo eklemek için POST uç noktası ve zValidator kullanarak girdi validasyonu yapalım:
// src/index.ts
app.post('/todos', zValidator('json', createTodoSchema), async (c) => {
const { title } = c.req.valid('json');
const newTodo: NewTodo = { title };
const result = await db.insert(todos).values(newTodo).returning();
return c.json(result[0], 201); // 201 Created
});
4.4. Todo Güncelleme (PUT /todos/:id)
Mevcut bir todoyu güncellemek için PUT uç noktası:
// src/index.ts
app.put('/todos/:id', zValidator('json', updateTodoSchema), async (c) => {
const id = Number(c.req.param('id'));
if (isNaN(id)) {
return c.json({ error: 'Geçersiz ID formatı.' }, 400);
}
const updates = c.req.valid('json');
const result = await db.update(todos).set(updates).where(eq(todos.id, id)).returning();
if (result.length === 0) {
return c.json({ error: 'Todo bulunamadı.' }, 404);
}
return c.json(result[0]);
});
4.5. Todo Silme (DELETE /todos/:id)
Bir todoyu silmek için DELETE uç noktası:
// src/index.ts
app.delete('/todos/:id', async (c) => {
const id = Number(c.req.param('id'));
if (isNaN(id)) {
return c.json({ error: 'Geçersiz ID formatı.' }, 400);
}
const result = await db.delete(todos).where(eq(todos.id, id)).returning();
if (result.length === 0) {
return c.json({ error: 'Todo bulunamadı.' }, 404);
}
return c.json({ message: 'Todo başarıyla silindi.' });
});
export default app; // Hono uygulamayı dışa aktar
5. API'yi Test Etme ve Çalıştırma
Geliştirdiğimiz API'yi yerel ortamda çalıştırıp test edebiliriz.
5.1. Uygulamayı Yerelde Çalıştırma
Hono projenizin package.json dosyasında genellikle bir dev script'i bulunur. Eğer yoksa, ekleyebilirsiniz:
// package.json
{
"scripts": {
"dev": "tsx watch src/index.ts" // veya hono'nun varsayılan script'i
}
}
Uygulamayı başlatmak için:
npm run dev
Uygulamanız varsayılan olarak http://localhost:3000 adresinde çalışmaya başlayacaktır.
5.2. Postman veya cURL ile Test Etme
API uç noktalarını test etmek için Postman, Insomnia gibi araçları veya doğrudan terminalden cURL'u kullanabilirsiniz.
Örnek cURL Komutları:
Tüm Todoları Getir:
curl http://localhost:3000/todos
Yeni Todo Ekle:
curl -X POST -H "Content-Type: application/json" -d '{"title": "Alışveriş yap"}' http://localhost:3000/todos
Todo Güncelle: (ID'yi eklenen todonun ID'si ile değiştirin)
curl -X PUT -H "Content-Type: application/json" -d '{"completed": true}' http://localhost:3000/todos/1
Todo Sil: (ID'yi silmek istediğiniz todonun ID'si ile değiştirin)
curl -X DELETE http://localhost:3000/todos/1
6. Sonuç
Bu rehberde, HonoJS, Drizzle ORM ve Neon'un güçlü kombinasyonunu kullanarak basit ama işlevsel bir Todo API'si geliştirmeyi öğrendiniz. HonoJS'in hızı ve hafifliği, Drizzle ORM'in tip güvenliği ve minimalist yapısı ile Neon'un sunucusuz esnekliği, modern ve ölçeklenebilir bir backend çözümü oluşturmak için ideal bir zemin sunar. Bu temel bilgileri kullanarak daha karmaşık API'ler geliştirebilir, kimlik doğrulama, daha gelişmiş validasyon ve hata yönetimi gibi özellikler ekleyerek projenizi genişletebilirsiniz. Bu teknoloji yığını, özellikle Edge fonksiyonları ve sunucusuz mimariler için geleceğin web geliştirme pratiklerine kapı aralamaktadır.
7. Sıkça Sorulan Sorular (SSS)
7.1. HonoJS'in Express.js'e göre avantajları nelerdir?
HonoJS, Express.js'e göre çok daha hafif ve performanslıdır. Web Standartları API'leri üzerine kurulduğu için farklı JavaScript çalışma zamanlarında (Node.js, Cloudflare Workers, Vercel Edge Functions vb.) sorunsuz çalışır. TypeScript desteği ve minimal API yüzeyi, geliştirme hızını ve kod kalitesini artırır. Express.js daha köklü ve geniş bir ekosisteme sahipken, HonoJS modern, performans odaklı ve sunucusuz ortamlar için optimize edilmiştir.
7.2. Drizzle ORM, Prisma gibi diğer ORM'lerden nasıl ayrılır?
Drizzle ORM, diğer popüler ORM'lere (Prisma, TypeORM) göre daha minimalist ve SQL'e yakın bir yaklaşıma sahiptir. Tip güvenliğini TypeScript ile sağlarken, SQL sorgularını doğrudan yazmaya benzer bir deneyim sunar. Bu, daha az soyutlama ve daha fazla kontrol anlamına gelir. Prisma, daha yüksek seviyeli bir soyutlama ve güçlü bir CLI ile gelirken, Drizzle daha hafif bir ayak izi ve daha az bağımlılık sunar, bu da özellikle performansın kritik olduğu sunucusuz ortamlarda avantaj sağlar.
7.3. Neon'u ücretsiz kullanabilir miyim?
Evet, Neon cömert bir ücretsiz katman sunar. Bu katman, geliştirme ve küçük ölçekli projeler için fazlasıyla yeterlidir. Otomatik duraklatma özelliği sayesinde, veritabanınız kullanılmadığında kaynak tüketmez, bu da maliyetleri daha da düşürür. Ücretsiz katmanın limitlerini aşmanız durumunda ücretli planlara geçiş yapabilirsiniz.
7.4. Bu API'yi nasıl dağıtabilirim (deploy)?
HonoJS'in çoklu çalışma zamanı desteği sayesinde bu API'yi birçok farklı platforma dağıtabilirsiniz:
- Vercel: Hono, Vercel Edge Functions ile mükemmel uyum sağlar.
- Cloudflare Workers: Hono'nun temel olarak tasarlandığı ortamlardan biridir.
- Netlify Functions: Sunucusuz fonksiyon olarak dağıtabilirsiniz.
- Render/Fly.io: Geleneksel Node.js uygulaması olarak da dağıtabilirsiniz.
Dağıtım süreci, seçtiğiniz platforma göre değişiklik gösterecektir, ancak genellikle projenizi Git deposuna itmek ve platformun otomatik dağıtım özelliklerini kullanmak kadar basittir.