Blog

Spesifikasyon Odaklı Geliştirme (SDD) Nedir ve Nasıl Uygulanır?

Ashley Goolam

Ashley Goolam

26 December 2025

Spesifikasyon Odaklı Geliştirme (SDD) Nedir ve Nasıl Uygulanır?

Kurumsal Apidog

Şirket İçi Dağıtım

SSO & RBAC

SOC 2 Uyumlu

Apidog Enterprise'ı Keşfet

Şartname Odaklı Geliştirme (SDD), yazılım şartnamelerinin geliştirmenin her aşamasına rehberlik eden tek doğru kaynak haline geldiği bir metodolojidir. Uygulamanın dokümantasyondan önce geldiği kod-öncelikli yaklaşımların aksine, SDD; detaylı şartnamelerin (örn. API sözleşmeleri, mimari planlar ve kabul kriterleri) tek bir üretim kodu satırı yazılmadan önce oluşturulmasını, doğrulanmasını ve onaylanmasını zorunlu kılar. Bu şartname-öncelikli yaklaşım, belirsizliği ortadan kaldırır, yeniden işleme ihtiyacını azaltır ve her geliştiricinin aynı sistemi birebir aynı taslağa göre oluşturmasını sağlar.

Düğme

Şartname Odaklı Geliştirme (SDD) Neden Önemlidir?

Geleneksel geliştirmede, ekipler genellikle belirsiz gereksinimlere dayanarak kodlamaya başlar ve sprint ortasında API tasarımının hatalı olduğunu, veritabanı şemasının ölçeklenmediğini veya ön ucun arka uç yanıtlarını tüketemediğini keşfeder. Şartname Odaklı Geliştirme (SDD), değişikliklerin ucuz olduğu tasarım aşamasında kritik kararları zorunlu kılarak bunu önler.

İş etkisi ölçülebilirdir: SDD kullanan projeler, sprint ortası değişikliklerinde %40 daha az, entegrasyon yeniden çalışmalarında ise %60 daha az raporlama yapmaktadır. API şartnameniz önceden kilitlenip doğrulandığında, ön uç ve arka uç ekipleri sürekli koordinasyona gerek kalmadan paralel çalışabilir. Mimari planınız akranlar tarafından incelendiğinde, ölçeklenebilirlik darboğazları koda işlenmeden önce yakalanır.

Şartname Odaklı Geliştirmenin (SDD) Temel Bileşenleri

Şartname Odaklı Geliştirme (SDD), geliştirme sözleşmenizi oluşturan dört temel yapı taşına dayanır:

1. Şartname Dokümantasyonu

Her sistem bileşeninin detaylı, belirsizliğe yer bırakmayan açıklamaları. API'ler için bu, şemalar, örnekler ve doğrulama kuralları içeren OpenAPI şartnameleri anlamına gelir.

# SDD'de Örnek API Şartnamesi
paths:
  /api/users:
    post:
      summary: Create a new user
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [email, name]
              properties:
                email:
                  type: string
                  format: email
                  example: user@example.com
                name:
                  type: string
                  minLength: 1
                  maxLength: 100
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    format: uuid
                  email:
                    type: string
                  name:
                    type: string

2. Mimari Plan

Sistem bileşenlerinin, veri akışlarının ve altyapı kararlarının görsel ve metinsel dokümantasyonu.

// SDD'de Mimari Diyagramı
graph TB
    Client --> API_Gateway
    API_Gateway --> Auth_Service
    API_Gateway --> User_Service
    API_Gateway --> Order_Service
    User_Service --> PostgreSQL[(User DB)]
    Order_Service --> MongoDB[(Order DB)]
    Order_Service --> Payment_API(Payment Gateway)

3. Görev Dağılımı

Şartnameler, net kabul kriterlerine sahip uygulanabilir görevlere ayrılır.

Görev Kimliği Açıklama Kabul Kriterleri Bağımlılıklar
API-001 POST /api/users'ı uygulayın Geçerli yük ile 201 döndürür, geçersiz e-posta ile 400 döndürür, DB'ye kaydeder DB şeması onaylandı
API-002 Kimlik doğrulama ara yazılımı ekleyin JWT tokenını doğrular, geçersiz tokenda 401 döndürür Kimlik doğrulama hizmeti şartnamesi tamamlandı
FE-001 Kullanıcı kayıt formu oluşturun Tasarım taslağıyla eşleşir, API-001'i çağırır, başarı/hata gösterir API-001 tamamlandı

4. Uygulama Yönergeleri

Kod tabanında tutarlılığı sağlayan kodlama standartları, desenleri ve kısıtlamaları.

// Uygulama yönergesi örneği
/**
 * Tüm API uç noktaları şunları yapmalıdır:
 * 1. İstek gövdesini OpenAPI şartnamesine göre doğrulamalıdır
 * 2. Standartlaştırılmış hata yanıtları döndürmelidir
 * 3. İstekleri korelasyon kimlikleriyle kaydetmelidir
 * 4. Liste uç noktaları için sayfalama desteği sağlamalıdır
 */

// Standartlaştırılmış hata yanıtı
{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "E-posta biçimi geçersiz",
    "details": { "field": "email", "value": "invalid-email" }
  }
}

Şartname Odaklı Geliştirme (SDD) İş Akışı

Şartname Odaklı Geliştirme (SDD), yapılandırılmış 5 aşamalı bir döngüyü takip eder:

Aşama 1: Şartname Oluşturma (1-3 Gün)

Aşama 2: Şartname İncelemesi (4-5 Gün)

Aşama 3: Paralel Uygulama (2-4 Haftalar)

Aşama 4: Şartname Bazlı Test Etme

Aşama 5: Şartname Bakımı

Şartname Odaklı Geliştirme (SDD) için Araçlar

Şartname Yönetimi:

Uygulama:

Düğme

Doğrulama:

Apidog, Şartname Odaklı Geliştirmeyi (SDD) Nasıl Güçlendirir?

Apidog, geleneksel bir API tasarım aracından, yapay zeka kodlama çağında SDD'yi uygulayan kapsamlı bir ekosisteme dönüştü.

1. İnsanlar ve Yapay Zeka için Tek Doğru Kaynak

Apidog; API tasarımı, mocking (sahte sunucu), test etme, hata ayıklama ve dokümantasyonu tek bir platformda birleştirir. Ancak en önemlisi, Apidog MCP Sunucusu ile API şartnamelerinizi yapay zeka ajanları (Cursor gibi) için canlı bir bilgi tabanına dönüştürür. Bu, yapay zeka asistanınız size kod yazarken yardımcı olduğunda, güncel olmayan desenleri veya halüsinasyonları değil, tam olarak onaylanmış şartnameyi referans almasını sağlar.

2. Otomatik Şartname Odaklı İş Akışları

Ajan tabanlı yapay zeka çağında Apidog, şartnameyi sadece bir referans değil, tüm kodlama yaşam döngüsünün aktif itici gücü haline getirir.

Düğme

Şartname Odaklı Geliştirme (SDD) için En İyi Uygulamalar

  1. Önce Şartnameler, Sonra Kod: Onaylanmış şartnameler olmadan asla kodlamaya başlamayın
  2. Tek Doğru Kaynak: Her yerde referans alınan tek bir şartname dosyası
  3. Otomatik Doğrulama: Her commit şartnamelere karşı test edilir
  4. Paydaş İncelemesi: Teknik olmayan paydaşlar şartnameleri onaylamalıdır
  5. Her Şeyi Sürümlendirin: Şartnameler, mimari ve yönergeler sürümlendirilir
  6. Şartnameleri Canlı Tutun: Gereksinimler değiştiğinde sadece kodu değil, şartnameleri de güncelleyin
  7. Kod Üretimi Kullanın: Şartnamelerden taslaklar, istemciler ve testler üretin
  8. Sözleşmeleri Uygulayın: Şartnameyi ihlal eden derlemeleri başarısız sayın

Sıkça Sorulan Sorular

S1: SDD geliştirmeyi yavaşlatmaz mı?

Cevap: Tam tersi olur. Peşin şartname çalışması, sprint ortası yeniden yazmaları önler ve işi paralelleştirir. Ekipler, şartnameler soruları kesin olarak yanıtladığı için gereksinimleri netleştirmek için toplantılarda daha az zaman harcar.

S2: SDD'de şartnameleri kim yazar?

Cevap: Teknik yazarlar ve mimarlar taslağını hazırlar, ancak tüm ekip inceler. Ürün sahipleri iş gereksinimlerini doğrular, geliştiriciler uygulanabilirliği sağlar ve Kalite Güvence (QA) test edilebilirliği onaylar.

S3: SDD'de değişen gereksinimleri nasıl ele alırsınız?

Cevap: Değişiklikler aynı şartname inceleme sürecinden geçer. Önce şartname güncellenir, ardından uygulama yapılır. Bu, değişiklikleri sadece yapan geliştiricinin değil, herkesin bilmesini sağlar.

S4: Apidog, REST dışı API'ler için şartnameleri test edebilir mi?

Cevap: Evet. Apidog, GraphQL, WebSockets ve gRPC şartnamelerini destekler. Sorguları, mutasyonları, abonelikleri ve akış uç noktalarını şartnamelerinize göre doğrular.

S5: Ya şartname yanlış olursa?

Cevap: Şartname inceleme süreci hataların çoğunu yakalar, ancak bir şartname hatası uygulamaya ulaşırsa, etkisi sınırlı olduğu için düzeltilmesi daha kolaydır. Önce şartnameyi düzeltin, ardından testleri ve taslakları yeniden oluşturun, sonra uygulamayı düzeltin—hepsi sürüm kontrolünde takip edilir.

Sonuç

Şartname Odaklı Geliştirme (SDD), yazılım geliştirmeyi reaktif bir süreçten öngörülebilir, yüksek kaliteli bir iş akışına dönüştürür. Şartnameleri uygulama, test etme ve doğrulama süreçlerine rehberlik eden merkezi bir yapı taşı haline getirerek ekipler, belirsizliği ortadan kaldırır, yeniden işleme ihtiyacını azaltır ve güvenle daha hızlı ürün sunar.

Temel içgörü: şartnameler, kodlama sonrasında yazdığınız dokümantasyonlar değildir—onlar, kodlama öncesinde yazdığınız sözleşmelerdir. Testler üreten, uygulamaları doğrulayan ve sapmaları otomatik olarak yakalayan yürütülebilir yapı taşları haline gelirler.

Apidog gibi araçlar, şartname ile uygulama arasındaki kritik köprüyü otomatikleştirerek SDD'yi pratik hale getirir. API testleriniz OpenAPI şartnamenizden oluşturulduğunda ve sürekli olarak ona karşı doğrulandığında, şartname sapması imkansız hale gelir. Mimari diyagramınız kodla birlikte sürüm kontrolünde yaşadığında, mimari kararlar görünür ve tartışılabilir kalır.

Küçük başlayın. Yeni bir API uç noktası seçin. Önce OpenAPI şartnamesini yazın. Apidog ile testler oluşturun. Ekip onayı alın. Ardından uygulayın. Hatalardaki ve yeniden işleme ihtiyacındaki azalmayı ölçün. Bu veriler, Şartname Odaklı Geliştirmeyi (SDD) tüm kod tabanınıza yaymak için temel oluşturacaktır.

Düğme

API Tasarım-Öncelikli Yaklaşımı Apidog'da Uygulayın

API'leri oluşturmanın ve kullanmanın daha kolay yolunu keşfedin

Ücretsiz Kaydolİndir