# backend

> Comprehensive backend development guide covering API design, security, database patterns, and performance optimization. Use this skill for all server-side tasks including Node.js, Python, and database operations.

- Author: Xenit(Mehmet)
- Repository: xenitV1/skillport
- Version: 20251222163325
- Stars: 6
- Forks: 0
- Last Updated: 2026-02-07
- Source: https://github.com/xenitV1/skillport
- Web: https://mule.run/skillshub/@@xenitV1/skillport~backend:20251222163325

---

---
name: backend
description: Comprehensive backend development guide covering API design, security, database patterns, and performance optimization. Use this skill for all server-side tasks including Node.js, Python, and database operations.
metadata:
  skillport:
    category: backend
    tags:
      - server
      - api
      - database
      - security
      - performance
---

# 🖥️ Backend Development Guide (v2.0)

> **Antigravity Backend Standartları**
> Bu doküman, "Production-Ready" backend geliştirme süreçleri için teknik standartları belirler.

---

# 📋 İçindekiler

1. [Teknoloji Stack'i](#1-teknoloji-stacki)
2. [Sokratik Gerçeklik Kontrolü (Backend)](#2-sokratik-gerçeklik-kontrolü-backend)
3. [Project Structure](#3-project-structure)
4. [API Design Best Practices](#4-api-design-best-practices)
5. [Input Validation (Zod)](#5-input-validation-zod)
6. [Security Best Practices](#6-security-best-practices)
7. [Database Patterns](#7-database-patterns)
8. [Performance & Caching](#8-performance--caching)
9. [Error Handling](#9-error-handling)
10. [Logging & Monitoring](#10-logging--monitoring)
11. [Checklist](#11-checklist)

---

# 1. Teknoloji Stack'i

Projede aksi belirtilmedikçe varsayılan stack:

*   **Runtime:** Node.js (Latest LTS) veya Python 3.10+
*   **Framework:** Express/Fastify (Node) veya FastAPI (Python)
*   **Language:** TypeScript (Strict Mode)
*   **Database:** PostgreSQL (Supabase)
*   **ORM:** Prisma veya Drizzle
*   **Validation:** Zod (TS) veya Pydantic (Python)

---

# 2. Sokratik Gerçeklik Kontrolü (Backend)

Kod yazmaya başlamadan önce kendine sor:

1.  **"Bu endpoint gerçekten gerekli mi?"** (Yoksa mevcut bir endpoint genişletilebilir mi?)
2.  **"Veri güvenliğini nasıl sağlıyorum?"** (Auth check var mı? Input validasyonu tam mı?)
3.  **"N+1 sorunu yaratıyor muyum?"** (Database sorgusu döngü içinde mi?)
4.  **"Hata durumunda ne dönecek?"** (500 mü yoksa anlamlı bir 400 hatası mı?)
5.  **"Bu kod scale eder mi?"** (1 milyon istek gelirse ne olur?)

---

# 3. Project Structure

Domain-Driven Design (DDD) prensiplerine yakın, modüler yapı:

```
src/
├── api/                    # API Route Handlers
│   ├── auth/
│   ├── users/
│   └── posts/
├── core/                   # Çekirdek modüller
│   ├── config.ts           # Env variables
│   ├── database.ts         # DB connection
│   └── logger.ts           # Logging setup
├── middlewares/            # Express/Fastify middlewares
├── services/               # İş mantığı (Business Logic)
├── models/                 # DB Models (ORM schemas)
├── utils/                  # Yardımcı fonksiyonlar
├── schemas/                # Zod/Pydantic validation schemas
└── types/                  # TypeScript types
```

---

# 4. API Design Best Practices

## 4.1 RESTful Prensipleri
*   **Resource Odaklı:** `/getUsers` ❌ -> `/users` ✅
*   **HTTP Metotları:**
    *   `GET`: Veri oku
    *   `POST`: Veri yarat
    *   `PUT/PATCH`: Veri güncelle
    *   `DELETE`: Veri sil
*   **Plural Naming:** `/user` yerine `/users`
*   **Nesting:** `/users/1/posts` (Mantıklı ilişki varsa)

## 4.2 Response Format Standardı

Tüm endpoint'ler standart bir JSON yapısı dönmelidir:

```json
// Başarılı (200 OK)
{
  "success": true,
  "data": { ... },
  "meta": { "page": 1, "limit": 20 } // Opsiyonel
}

// Hata (4xx/5xx)
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": [...] // Opsiyonel
  }
}
```

---

# 5. Input Validation (Zod)

Kullanıcıdan gelen HİÇBİR veriye güvenme. Her şeyi validate et.

```typescript
import { z } from 'zod';

const UserCreateSchema = z.object({
  email: z.string().email(),
  password: z.string().min(8),
  role: z.enum(['admin', 'user']).default('user'),
  age: z.number().int().min(18).optional()
});

// Kullanımı
const result = UserCreateSchema.safeParse(req.body);
if (!result.success) {
  // Return 400 Bad Request
}
```

---

# 6. Security Best Practices

1.  **Authentication:** JWT veya Session-based auth kullan. Asla plain-text şifre saklama (bcrypt/argon2 kullan).
2.  **Authorization:** Role-based Access Control (RBAC) uygula. `isAdmin` kontrolü yap.
3.  **Rate Limiting:** DDoS ve brute-force saldırılarına karşı IP bazlı limit koy (redis-rate-limiter).
4.  **Helmet:** HTTP başlıklarını güvenli hale getir (`helmet` paketi).
5.  **CORS:** Sadece güvenilen domainlere izin ver. `*` kullanma.
6.  **SQL Injection:** ORM kullanarak injection'ı engelle. Raw SQL yazıyorsan parametreli query kullan.

---

# 7. Database Patterns

## 7.1 Repository Pattern
Veritabanı erişimini iş mantığından ayır.

```typescript
// service.ts (İş mantığı)
class UserService {
  constructor(private userRepo: UserRepository) {}
  
  async register(data) {
    // Validasyon, hashing vs.
    return this.userRepo.create(data);
  }
}

// repository.ts (Veri erişimi)
class UserRepository {
  async create(data) {
    return db.user.create({ data });
  }
}
```

## 7.2 Transaction Yönetimi
Birden fazla tabloyu etkileyen işlemleri mutlaka transaction içine al.

```typescript
await db.$transaction(async (tx) => {
  const user = await tx.user.create({ ... });
  await tx.profile.create({ userId: user.id, ... });
});
```

---

# 8. Performance & Caching

## 8.1 Database Indexing
Sık sorgulanan kolonlara (özellikle `WHERE` ve `JOIN` koşullarına) index ekle.

## 8.2 Caching (Redis)
*   **Read-Heavy Data:** Sık okunan ama az değişen verileri (örn: kategoriler, ayarlar) Redis'te cache'le.
*   **Cache Invalidation:** Veri değiştiğinde cache'i temizle veya güncelle.
*   **TTL (Time-To-Live):** Her cache verisine mutlaka bir ömür biç.

```typescript
// Örnek Cache Pattern
const cacheKey = `user:${id}`;
let user = await redis.get(cacheKey);

if (!user) {
  user = await db.user.findUnique({ where: { id } });
  await redis.set(cacheKey, JSON.stringify(user), 'EX', 3600); // 1 saat
}
```

---

# 9. Error Handling

Global bir Error Handling mekanizması kur. `try-catch` bloklarını her yerde tekrar etme.

1.  **AppError Class:** Özel hata sınıfı oluştur (statusCode, message, isOperational).
2.  **Global Middleware:** Tüm hataları yakalayan son bir middleware yaz.
3.  **Operational vs Programming:** 
    *   Operational (Kullanıcı hatası, Network hatası) -> Yönet ve mesaj dön.
    *   Programming (Bug) -> Logla ve süreci öldür (veya restart et).

---

# 10. Logging & Monitoring

*   **Structured Logging:** JSON formatında log üret (Pino veya Winston).
*   **Levels:** Error, Warn, Info, Debug, Trace seviyelerini doğru kullan.
*   **Context:** Log'a request ID, user ID gibi bağlam bilgilerini ekle.
*   **Sensitive Data:** Şifre, token gibi verileri asla loglama!

---

# 11. Checklist

Kodunu commitlemeden önce kontrol et:

- [ ] Tüm inputlar validate ediliyor mu? (Zod/Pydantic)
- [ ] Yetki kontrolü (Authz) var mı?
- [ ] Hassas veriler (Password) hashleniyor mu?
- [ ] N+1 sorgusu var mı?
- [ ] Hata yakalama (Try-Catch) düzgün çalışıyor mu?
- [ ] Console.log'lar temizlendi mi?
- [ ] Tip tanımları (Types) eksiksiz mi?
- [ ] Environment variable'lar config dosyasından mı geliyor?