Yapılır?. Nasıl Yapılır?

Node.js ile modern, güvenli ve yüksek performanslı bir backend (arka uç) uygulaması geliştirmek, günümüz yazılım dünyasının en çok talep gören becerilerinden biridir. Özellikle 2026 yılı itibarıyla Node.js ekosisteminin sunduğu yerleşik test araçları, ES modülleri desteği ve optimize edilmiş çalışma zamanı (runtime) performansı, bu platformu kurumsal projelerin vazgeçilmezi haline getirmiştir. Peki, sıfırdan profesyonel düzeyde bir Node.js projesi nasıl yapılır?. Nasıl yapılır? sorusunun yanıtı, sadece kod yazmaktan değil; doğru mimariyi seçmekten, güvenlik önlemlerini almaktan ve ölçeklenebilir kod yazmaktan geçer.

Bu kapsamlı eğitim rehberinde, Node.js ve Express.js kullanarak modern standartlara uygun, güvenli ve ölçeklenebilir bir REST API (Temsili Durum Aktarımı) uygulamasını adım adım inşa edeceğiz. Yazılım mimarisi prensiplerine sadık kalarak; yönlendirme (routing), veri doğrulama (validation), hata yönetimi (error handling), güvenlik (security) ve veritabanı entegrasyonu gibi kritik aşamaları uygulamalı kod örnekleriyle ele alacağız. Bu rehber, orta ve ileri düzey backend geliştiricisi olmak isteyen tüm yazılımcılar için başucu kaynağı niteliğindedir.

Rehber boyunca yazacağımız tüm kodlar, Node.js'in en güncel uzun vadeli destek (LTS) sürümü olan v22 ve üzeri standartlarına uygun olarak, modern ES Modülleri (import/export) sözdizimiyle kaleme alınmıştır. Hazırsanız, terminalinizi açın ve modern backend dünyasına adım atın.

Gereksinimler ve Ön Hazırlık

Projeyi başarıyla tamamlayabilmek ve kodları kendi yerel bilgisayarınızda çalıştırabilmek için aşağıdaki araçların ve ortamların sisteminizde kurulu olması gerekmektedir:

• Node.js (v22.x veya üzeri): En son LTS sürümünün kurulu olduğundan emin olun. Terminalde node -v komutu ile kontrol edebilirsiniz.
• npm (Node Package Manager): Node.js ile birlikte otomatik olarak yüklenir. Paket yönetimi için kullanılacaktır.
• Kod Editörü: Visual Studio Code veya tercih ettiğiniz herhangi bir modern kod editörü.
• API Test Aracı: Geliştirdiğimiz uç noktaları (endpoints) test etmek için Postman, Thunder Client veya cURL.

Gereksinimleri tamamladıktan sonra projemiz için boş bir klasör oluşturalım ve terminal üzerinden bu klasöre geçiş yaparak projemizi başlatalım. Aşağıdaki komutları sırasıyla terminalinizde çalıştırın:

mkdir nodejs-api-projesi
cd nodejs-api-projesi
npm init -y

Bu komut, projenizin kök dizininde varsayılan ayarlara sahip bir package.json dosyası oluşturacaktır. Projemizde modern JavaScript (ES Modules) kullanabilmek için bu dosyayı açıp "type": "module" satırını eklememiz gerekmektedir. Güncellenmiş package.json dosyanız şu şekilde görünmelidir:

{
  "name": "nodejs-api-projesi",
  "version": "1.0.0",
  "type": "module",
  "main": "server.js",
  "scripts": {
    "start": "node server.js",
    "dev": "node --watch server.js"
  },
  "dependencies": {}
}

Yukarıdaki yapılandırmada, Node.js'in yerleşik dosya izleme özelliği olan --watch parametresini kullandık. Bu sayede, 2026 standartlarında harici bir kütüphaneye (nodemon gibi) ihtiyaç duymadan, kodda değişiklik yaptığımızda sunucumuz otomatik olarak yeniden başlayacaktır.

Adım 1: Proje Yapısının Kurulması ve İlk Sunucunun Çalıştırılması

Profesyonel bir backend projesinde tüm kodları tek bir dosyaya yazmak, projenin bakımını (maintenance) imkansız hale getirir. Bu nedenle, projemizde katmanlı mimari (layered architecture) prensiplerini uygulayacağız. İlk olarak gerekli bağımlılıkları yükleyelim:

npm install express dotenv cors helmet

Yüklediğimiz paketlerin işlevleri şu şekildedir:

• express: Minimalist ve hızlı web framework'ü.
• dotenv: Hassas verileri (API anahtarları, DB şifreleri) .env dosyasında saklamak için kullanılan kütüphane.
• cors: Tarayıcı tabanlı güvenlik politikalarını (Cross-Origin Resource Sharing) yönetmek için middleware.
• helmet: HTTP başlıklarını (headers) güvenli hale getirerek yaygın web açıklarına karşı koruma sağlayan middleware.

Şimdi projenin kök dizininde .env adında bir dosya oluşturalım ve çevre değişkenlerimizi tanımlayalım:

PORT=5000
NODE_ENV=development

Ardından, projenin ana giriş noktası olan server.js dosyasını oluşturalım. Bu dosyada Express uygulamasını başlatacak, temel güvenlik katmanlarını entegre edecek ve uygulamayı dinlemeye alacağız. Ayrıca, uygulamanın beklenmedik şekilde çökmesini engellemek için hata yakalama mekanizmalarını da kuracağız:

import express from 'express';
import dotenv from 'dotenv';
import cors from 'cors';
import helmet from 'helmet';

// Çevre değişkenlerini yükle
dotenv.config();

const app = express();
const PORT = process.env.PORT || 5000;

// Güvenlik ve Yardımcı Ara katman yazılımları (Middleware)
app.use(helmet());
app.use(cors());
app.use(express.json()); // Gelen JSON istek gövdelerini (body) ayrıştırır

// Temel Sağlık Kontrolü (Health Check) Rotası
app.get('/api/health', (req, res) => {
    res.status(200).json({
        status: 'success',
        message: 'Sunucu aktif ve çalışıyor',
        timestamp: new Date().toISOString()
    });
});

// Sunucuyu Başlatma ve Hata Yönetimi
const server = app.listen(PORT, () => {
    console.log(`[Sunucu] Uygulama ${process.env.NODE_ENV} modunda, ${PORT} portunda çalışıyor.`);
});

// Beklenmeyen hata durumlarında sunucuyu güvenli kapatma (Graceful Shutdown)
process.on('unhandledRejection', (err) => {
    console.error(`[HATA] Yakalanamayan Reddetme: ${err.message}`);
    server.close(() => process.exit(1));
});

Yukarıdaki kod bloğu, modern Node.js standartlarında güvenli bir başlangıç şablonudur. helmet ve cors entegrasyonu sayesinde uygulamanız temel web saldırılarına karşı korunur. unhandledRejection dinleyicisi ise veritabanı bağlantı hataları gibi asenkron işlemlerde meydana gelebilecek ve uygulamayı çökertebilecek hataları yakalayarak sunucunun güvenli bir şekilde kapanmasını sağlar.

Adım 2: Gelişmiş Yönlendirme (Routing) ve Controller Yapısı

Uygulamamızın ölçeklenebilir olması için rotaları (routes) ve bu rotaların çalıştıracağı iş mantığını (controllers) birbirinden ayırmalıyız. Bu adımda, kullanıcı yönetimi için örnek bir yapı kuracağız. Proje dizininde routes ve controllers adında iki yeni klasör oluşturalım.

Öncelikle controllers/userController.js dosyasını oluşturarak kullanıcı işlemlerini yönetecek fonksiyonları tanımlayalım:

// Geçici bellek içi (in-memory) veri deposu
const users = [
    { id: 1, name: 'Ahmet Yılmaz', email: 'ahmet@example.com' },
    { id: 2, name: 'Ayşe Demir', email: 'ayse@example.com' }
];

// Tüm kullanıcıları getir
export const getUsers = async (req, res, next) => {
    try {
        res.status(200).json({
            status: 'success',
            results: users.length,
            data: { users }
        });
    } catch (error) {
        next(error);
    }
};

// Yeni kullanıcı oluştur
export const createUser = async (req, res, next) => {
    try {
        const { name, email } = req.body;
        
        const newUser = {
            id: users.length + 1,
            name,
            email
        };

        users.push(newUser);

        res.status(201).json({
            status: 'success',
            data: { user: newUser }
        });
    } catch (error) {
        next(error);
    }
};

Şimdi bu controller fonksiyonlarını tetikleyecek rotaları tanımlamak için routes/userRoutes.js dosyasını oluşturalım:

import express from 'express';
import { getUsers, createUser } from '../controllers/userController.js';

const router = express.Router();

// /api/v1/users rotasına gelen istekleri eşleştirme
router.route('/')
    .get(getUsers)
    .post(createUser);

export default router;

Oluşturduğumuz bu rotayı ana sunucu dosyamız olan server.js dosyasına entegre etmemiz gerekir. server.js dosyasını açın ve uygun yerlere şu satırları ekleyin:

// Rotaları içe aktar (server.js dosyasının üst kısmına ekleyin)
import userRouter from './routes/userRoutes.js';

// Rota tanımlaması (Sağlık kontrolü rotasının altına ekleyin)
app.use('/api/v1/users', userRouter);

Bu modüler yapı sayesinde, gelecekte uygulamaya yeni özellikler (örneğin ürünler, siparişler) eklendiğinde, sadece yeni rota ve controller dosyaları oluşturarak karmaşanın önüne geçmiş olursunuz.

Adım 3: Veri Doğrulama (Validation) ve Güvenlik Önlemleri

Geliştirilen API'lerin en büyük zafiyet noktalarından biri, istemciden (client) gelen verilerin doğrudan işlenmesidir. SQL Injection, XSS ve geçersiz veri girişlerini engellemek için gelen verileri mutlaka doğrulamalıyız. Bu işlem için 2026 yılında endüstri standardı haline gelen Zod kütüphanesini kullanacağız.

İlk olarak Zod kütüphanesini projemize dahil edelim:

npm install zod

Veri doğrulama işlemini her rota için ayrı ayrı yazmak yerine, Express'in ara katman yazılımı (middleware) yapısını kullanarak tek bir merkezi doğrulama mekanizması kuracağız. middlewares/validate.js dosyasını oluşturalım:

// Gelen istek gövdesini (body) şemaya göre doğrulayan middleware
export const validate = (schema) => (req, res, next) => {
    try {
        schema.parse({
            body: req.body,
            query: req.query,
            params: req.params
        });
        next();
    } catch (error) {
        return res.status(400).json({
            status: 'fail',
            errors: error.errors.map(err => ({
                field: err.path[1],
                message: err.message
            }))
        });
    }
};

Şimdi, kullanıcı oluşturma işlemi için kabul edeceğimiz veri kurallarını tanımlayalım. schemas/userSchema.js dosyasını oluşturalım:

import { z } from 'zod';

export const createUserSchema = z.object({
    body: z.object({
        name: z.string({
            required_error: 'İsim alanı zorunludur.'
        }).min(3, 'İsim en az 3 karakter olmalıdır.').max(50, 'İsim en fazla 50 karakter olabilir.'),
        
        email: z.string({
            required_error: 'E-posta alanı zorunludur.'
        }).email('Geçersiz e-posta adresi formatı.')
    })
});

Oluşturduğumuz bu doğrulama katmanını routes/userRoutes.js dosyasında post rotamıza uygulayalım:

import express from 'express';
import { getUsers, createUser } from '../controllers/userController.js';
import { validate } from '../middlewares/validate.js';
import { createUserSchema } from '../schemas/userSchema.js';

const router = express.Router();

router.route('/')
    .get(getUsers)
    .post(validate(createUserSchema), createUser); // Doğrulama middleware'i eklendi

export default router;

Artık istemci

Gelişmiş Hata Yönetimi ve Global Error Handler Yapılandırması

Node.js ve Express uygulamalarında hata yönetimi, uygulamanın kararlılığı ve güvenliği için kritik bir öneme sahiptir. Try-catch bloklarını her controller içinde tekrar tekrar yazmak yerine, Express'in hata yakalama mekanizmasını kullanarak merkezi bir hata yönetim sistemi kurabiliriz. Bu yaklaşım, kod tekrarını önler ve tüm hataların istemciye aynı standart formatta dönmesini sağlar.

Özel Hata Sınıfı (AppError) Tasarımı

Uygulama genelinde fırlatacağımız hataları standartlaştırmak