Claude Code ile Go API iskeleti: tutarlı handler ve servisler

Kalıplar erken sabitlenmediğinde Go API'leri neden karışır

Go API'leri genellikle temiz başlar: birkaç uç nokta, bir ya da iki kişi ve her şey herkesin kafasında. Sonra API büyür, özellikler aceleyle çıkarılır ve küçük farklılıklar sızar. Her biri zararsız gibi görünür, ama birlikte gelecekteki her değişikliği yavaşlatırlar.

Sık görülen bir örnek: bir handler JSON'u bir struct'a çözer ve yardımcı bir mesajla 400 döner, başka birisi 422 ile farklı bir yapı döndürür, üçüncüsü hataları farklı formatta loglar. Bunların hiçbiri derlemeyi bozmaz. Her seferinde sürekli karar verme ve küçük yeniden yazmalar yaratır.

Sorunu şu yerlerde hissedersiniz:

• Uç noktalar arasında farklı hata gövdeleri, bu yüzden istemciler özel durumlar yazmak zorunda kalır.
• Servisler bazen ham veritabanı hatası döndürür bazen “kullanıcı dostu” olanı.
• İsim sürüklenmesi (CreateUser, AddUser, RegisterUser) aramayı zorlaştırır.
• Doğrulama farklı yerlere taşınır; aynı hatalar tekrar tekrar gelir.

Burada "iskeletleme" yeni iş için tekrarlanabilir bir şablon anlamına gelir: kod nereye gider, her katman ne yapar ve yanıtlar nasıl görünür. Çok kod üretmekten çok, tutarlı bir şekil sabitlemektir.

Claude gibi araçlar yeni uç noktaları hızlıca iskeletleyebilir, ama kalıp bir kural olarak ele alındığında işe yararlar. Kuralları siz belirlersiniz, her diff'i incelersiniz ve testleri çalıştırırsınız. Model standart parçaları doldurur; mimarinizi yeniden tanımlama hakkı yoktur.

Bir katman ayrımı seçin: handler, servis ve veri erişimi

Her istek aynı yolu izlediğinde bir Go API büyümeye kolay adapte olur. Uç noktaları üretmeye başlamadan önce bir katman ayrımı seçin ve ona sadık kalın.

Sorumluluklar, basit tutulmuş şekilde

Handler'ın işi yalnızca HTTP olmalı: isteği okumak, servisi çağırmak ve yanıtı yazmak. İş kuralları, SQL veya "sadece bu özel durum" mantığı burada olmamalı.

Servis kullanım senaryosunun sahibi olmalı: iş kuralları, kararlar ve repository'ler veya dış çağrılar arası orkestrasyon. HTTP ile ilgili durum kodları, başlıklar veya hataların nasıl render edildiğini bilmemeli.

Veri erişimi (repository/store) kalıcılık detaylarının sahibi olmalı. Servis niyetini SQL/sorgu/transaction'lara çevirir. Temel veri bütünlüğü dışında iş kurallarını uygulamamalı ve API yanıtlarını şekillendirmemeli.

Uygulanabilir bir ayrım kontrol listesi:

• Handler: girdiyi ayrıştır, servisi çağır, hataları HTTP'ye eşle, JSON yaz
• Servis: iş kurallarını uygula, repo'ları çağır, domain sonuçları veya tipli hatalar döndür
• Veri erişimi: sorguları çalıştır, satırları struct'lara eşle, saklama hataları döndür
• Paylaşılan: ortak hata tipleri ve yanıt yardımcıları
• Hiçbir katman başka birini atlamaz (handler asla doğrudan repo'yu çağırmaz)

Doğrulama için bir kural

Bir kural seçin ve bükmeyin.

Basit bir yaklaşım:

• Handler'lar şekil doğrulaması yapar (zorunlu alanlar, temel format)
• Servisler anlam doğrulaması yapar (izinler, invariantlar, durum)

Örnek: handler email alanının var olduğunu ve bir e-posta gibi göründüğünü kontrol eder. Servis, e-postanın izinli olup olmadığını ve zaten kullanımda olup olmadığını kontrol eder.

Katmanlar arasında ne taşınır

Servislerin domain tipleri mi yoksa DTO'lar mı döndürdüğüne erken karar verin.

Temiz bir varsayılan: handler'lar istek/yanıt DTO'larını kullanır, servisler domain tiplerini kullanır ve handler domain'i yanıta eşler. Bu, HTTP sözleşmesi değişse bile servisi stabil tutar.

Eşleştirme ağır geliyorsa bile tutarlı kalın: servis bir domain tipi artı tipli hata döndürsün ve JSON şekillendirme handler'da kalsın.

Standart bir hata yanıtı ve durum kodu haritası tanımlayın

Üretilen uç noktaların aynı kişi tarafından yazılmış gibi hissettirmesini istiyorsanız, hata yanıtlarını erken kilitleyin. Üretim, çıktı formatının pazarlık konusu olmadığı durumlarda en iyi çalışır: tek bir JSON şekli, tek bir durum-kodu haritası ve neyin açığa çıkarılacağı için bir kural.

Tüm başarısızlıklarda döndürülecek tek bir hata zarfı ile başlayın. Küçük ve öngörülebilir tutun:

{
  "code": "validation_failed",
  "message": "One or more fields are invalid.",
  "details": {
    "fields": {
      "email": "must be a valid email address",
      "age": "must be greater than 0"
    }
  },
  "request_id": "req_01HR..."
}

code makineler için (istikrarlı ve öngörülebilir), message insanlar için (kısa ve güvenli) olsun. Yapılandırılmış verileri details içine koyun. Doğrulama için basit bir details.fields haritası üretmesi kolay ve istemcilerin girişlerin yanında göstermesi kolaydır.

Sonra, bir durum kodu haritası yazın ve ona sadık kalın. Her uç noktada daha az tartışma olması iyidir. Eğer hem 400 hem 422 istiyorsanız, ayrımı açık hale getirin:

• bad_json -→ 400 Bad Request (bozuk JSON)
• validation_failed -→ 422 Unprocessable Content (doğru biçimli JSON, geçersiz alanlar)
• not_found -→ 404 Not Found
• conflict -→ 409 Conflict (çakışan anahtar, sürüm uyuşmazlığı)
• unauthorized -→ 401 Unauthorized
• forbidden -→ 403 Forbidden
• internal -→ 500 Internal Server Error

Ne kaydedeceğinize ve neyi döndüreceğinize karar verin. İyi bir kural: istemciler güvenli bir mesaj ve bir request ID alır; loglar tam hata ve dahili bağlamı (SQL, upstream yükleri, kullanıcı ID'leri) içerir ve bunlar asla sızdırılmaz.

Son olarak request_id'yi standardize edin. Gelen bir ID başlığı varsa kabul edin (örneğin bir API gateway'den), yoksa kenarda (middleware) bir tane oluşturun. Bunu context'e ekleyin, loglara iliştirin ve her hata yanıtında döndürün.

Klasör düzeni ve isimlendirme: üretimi öngörülebilir kılan

Iskeletlemenin tutarlı kalmasını istiyorsanız, klasör düzeniniz sıkıcı ve tekrarlanabilir olmalı. Üreticiler görebildikleri kalıpları takip eder; dosyalar dağınık veya isimler özellik başına değişkense sapma olur.

Bir isimlendirme kuralı seçin ve bükmeyin. Her şey için tek bir kelime seçin ve koruyun: handler, service, repo, request, response. Eğer rota POST /users ise dosya ve tip adlarını users ve create etrafında adlandırın (bazen register, bazen addUser yapmayın).

Katmanlara uyan basit bir düzen:

internal/
  httpapi/
    handlers/
    users_handler.go
  services/
    users_service.go
  data/
    users_repo.go
  apitypes/
    users_types.go

Paylaşılan tiplerin nerede duracağına karar verin; projelerin çoğu burada karışır. Yararlı bir kural:

• API istek/yanıt tipleri internal/apitypes içinde (JSON ve doğrulama ihtiyaçlarına göre).
• Domain tipleri servis katmanına daha yakın olsun (iş kurallarına göre).

Bir tip JSON etiketlerine sahipse ve istemciler için tasarlandıysa, onu API tipi olarak değerlendirin.

Handler bağımlılıklarını minimal tutun ve bunu açık hale getirin:

• Handler'lar sadece: routing/http, context, apitypes ve services import etsin
• Servisler import etsin: domain tipleri ve veri erişimi
• Veri erişimi import etsin: veritabanı sürücüsü ve sorgu yardımcıları
• Hiçbir handler doğrudan veritabanı paketini import etmesin

Depo köküne kısa bir kalıp dokümanı yazın (düz Markdown yeterli). Klasör ağacını, isimlendirme kurallarını ve küçük bir örnek akışı (handler → service → repo ve her parçanın hangi dosyada olduğu) ekleyin. Bu, jeneratöre yapıştırdığınız kesin referanstır, böylece her yeni uç nokta her seferinde aynı yapıyı takip eder.

Deseni belirleyen bir referans endpoint oluşturun

On endpoint'i üretmeden önce bir endpoint oluşturun veya var olanı refaktörleyin ki elinizde güvenilir bir altın standart olsun. Bu, “Yeni kod bunun gibi olmalı” diyebileceğiniz dosyadır. Sıfırdan yazabilir veya var olanı refaktör ederek eşleştirebilirsiniz.

Handler'ı ince tutun. Çok yardımcı olan bir hareket: handler ile servis arasında bir interface koyun, böylece handler bir somut yapıya değil bir kontrata bağımlı olur.

Referans endpoint'te gelecekte üretilen kodun hata yaşayabileceği yerler için küçük yorumlar ekleyin. Kararları açıklayın (400 ile 422 neden ayrıldı, neden create 201 döndürür, neden dahili hataları genel bir mesajla gizliyorsunuz). Kodu sadece tekrarlayan şekilde açıklayan yorumları atlayın.

Referans endpoint çalıştıktan sonra yardımcıları çıkarın ki her yeni endpoint'in sapma şansı azalır. En yeniden kullanılabilir yardımcılar genellikle şunlardır:

• JSON bağlama ve bozuk gövdeleri ele alma
• Girdi doğrulama ve alan hatalarını döndürme
• JSON yanıtlarını tutarlı yazma
• Domain hatalarını HTTP durum kodlarına eşleme

İnce handler + interface pratikte şöyle görünebilir:

type UserService interface {
	CreateUser(ctx context.Context, in CreateUserInput) (User, error)
}

func (h *Handler) CreateUser(w http.ResponseWriter, r *http.Request) {
	var in CreateUserRequest
	if err := BindJSON(r, &in); err != nil {
		WriteError(w, ErrBadJSON) // 400: malformed JSON
		return
	}
	if err := Validate(in); err != nil {
		WriteError(w, err) // 422: validation details
		return
	}
	user, err := h.svc.CreateUser(r.Context(), in.ToInput())
	if err != nil {
		WriteError(w, err)
		return
	}
	WriteJSON(w, http.StatusCreated, user)
}

Birkaç testle (hatta hata eşlemesi için küçük bir tablo testiyle) bunu kilitleyin. Üretim, taklit edilecek tek temiz hedef olduğunda en iyi çalışır.

Adım adım: Claude'dan kalıpla eşleşen yeni bir endpoint üretmesini sağlayın

Tutarlılık yapıştırdığınız içerikle ve yasakladığınız şeylerle başlar. Yeni bir endpoint için iki şey verin:

1. Referans endpoint ("mükemmel" örnek)
2. Paketleri, fonksiyonları ve yardımcıları adlandıran kısa bir desen notu

1) Önce bağlam verin (referans + kurallar)

Handler, servis metodu, istek/yanıt tiplerini ve endpoint'in kullandığı yardımcıları dahil edin. Sonra sözleşmeyi açıkça belirtin:

• Route + method (örnek: POST /v1/widgets)
• İstek JSON alanları (zorunlu vs opsiyonel)
• Yanıt JSON şekli
• Hata durumları ve durum kodları
• Geri almayı beklediğiniz dosyalar (ve sadece o dosyalar)

Paket yolları, isimlendirme ve yardımcı fonksiyonlar (WriteJSON, BindJSON, WriteError, validator) konusunda eşleşmesi gerekenleri açıkça belirtin.

2) İstediğiniz biçimde çıktı isteyin

Sıkı bir istem, modelin “yardımcı” refaktörlerini önler. Örnek bir istek:

Using the reference endpoint below and the pattern notes, generate a new endpoint.
Contract:
- Route: POST /v1/widgets
- Request: {"name": string, "color": string}
- Response: {"id": string, "name": string, "color": string, "createdAt": string}
- Errors: invalid JSON -> 400; validation -> 422; duplicate name -> 409; unexpected -> 500
Output ONLY these files:
1) internal/http/handlers/widgets_create.go
2) internal/service/widgets.go (add method only)
3) internal/types/widgets.go (add types only)
Do not change: router setup, existing error format, existing helpers, or unrelated files.
Must use: package paths and helper functions exactly as in the reference.

Test istiyorsanız bunları açıkça isteyin (ve test dosyası adını belirtin). Aksi takdirde model testleri atlayabilir veya hayali bir test kurulumuyla oluşturabilir.

Üretimden sonra hızlı bir diff kontrolü yapın. Eğer paylaşılan yardımcıları, router kaydını veya standart hata yanıtını değiştirdiyse çıktıyı reddedin ve "değiştirme" kurallarını daha sıkı yeniden belirtin.

Tekrar kullanılabilir bir istem şablonu

Çıktı, girdi kadar tutarlı olur. Aynı istem şablonunu her seferinde yeniden kullanmak ve depo bağlamından küçük bir içerik kesitini yapıştırmak "neredeyse doğru" kod üretimini engellemenin en hızlı yoludur.

İstem şablonu

Aşağıyı kopyalayıp yerleri doldurun:

You are editing an existing Go HTTP API.

CONTEXT
- Folder tree (only the relevant parts):
  <paste a small tree: internal/http, internal/service, internal/repo, etc>
- Key types and patterns:
  - Handler signature style: <example>
  - Service interface style: <example>
  - Request/response DTOs live in: <package>
- Standard error response JSON:
  {
    "error": {
      "code": "invalid_argument",
      "message": "...",
      "details": {"field": "reason"}
    }
  }
- Status code map:
  invalid_json -> 400
  invalid_argument -> 422
  not_found -> 404
  conflict -> 409
  internal -> 500

TASK
Add a new endpoint: <METHOD> <PATH>
- Handler name: <Name>
- Service method: <Name>
- Request JSON example:
  {"name":"Acme"}
- Success response JSON example:
  {"id":"123","name":"Acme"}

CONSTRAINTS
- No new dependencies.
- Keep functions small and single-purpose.
- Match existing naming, folder layout, and error style exactly.
- Do not refactor unrelated files.

ACCEPTANCE CHECKS
- Code builds.
- Existing tests pass (add tests only if the repo already uses them for handlers/services).
- Run gofmt on changed files.

FINAL INSTRUCTION
Before writing code, list any assumptions you must make. If an assumption is risky, ask a short question instead.

Bu, üç şeyi zorunlu kılar: bir bağlam bloğu (ne var), bir kısıt bloğu (ne yapılmamalı) ve somut JSON örnekleri (şekillerin kaymaması için). Son talimat bir güvenlik ağıdır: model emin değilse kod yazmadan önce soru sormalıdır.

Gerçekçi örnek: stili bozmadan bir Create endpoint eklemek

Örneğin bir “Create project” endpoint'i eklemek istiyorsunuz. Amaç basit: bir isim kabul et, birkaç kural uygula, kaydet ve yeni bir ID döndür. Zor olan kısım handler–servis–repo ayrımını ve zaten kullandığınız hata JSON'unu korumak.

Tutarlı bir akış şöyle görünür:

• Handler: JSON bağla, temel alan doğrulaması yap, servisi çağır
• Servis: iş kurallarını uygula (benzersizlik gibi), repo'yu çağır, domain sonucu döndür
• Repo: Postgres'e yaz, üretilen ID'yi döndür

Handler'ın kabul ettiği istek örneği:

{ "name": "Roadmap", "owner_id": "u_123" }

Başarılıysa 201 Created döndürün. ID her zaman tek bir yerden gelsin. Örneğin Postgres'in üretmesine izin verin ve repo bunun döndürmesini sağlayın:

{ "id": "p_456", "name": "Roadmap", "owner_id": "u_123", "created_at": "2026-01-09T12:34:56Z" }

İki gerçekçi hata yolu:

Validation başarısızsa (isim eksik veya çok kısa), standart şeklinizi ve seçtiğiniz durum kodunu kullanarak alan düzeyinde hata döndürün:

{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid request", "details": { "name": "must be at least 3 characters" } } }

İsim sahibine göre benzersizse ve servis mevcut bir proje bulursa 409 Conflict döndürün:

{ "error": { "code": "PROJECT_NAME_TAKEN", "message": "Project name already exists", "details": { "name": "Roadmap" } } }

Handler "bu istek doğru şekilde şekillenmiş mi?" kontrolünü yaparken, servis "bu izinli mi?" sorusunun sahibi olsun. Bu ayrım üretilen endpoint'leri öngörülebilir kılar.

Tutarlılığı bozan yaygın hatalar (ve nasıl önlenir)

Jeneratörün doğaçlama yapmasına izin vermek en hızlı tutarlılığı kaybettirendir.

Yaygın bir sapma yeni bir hata şeklidir. Bir endpoint {error: "..."} döndürür, başka biri {message: "..."}, üçüncüsü nested bir obje ekler. Bunu tek bir hata zarfı ve tek bir durum kodu haritası tutarak ve yeni endpoint'lerin bunları import yoluyla yeniden kullanmasını zorunlu kılarak düzeltin. Eğer jeneratör yeni bir alan öneriyorsa, bunu bir API değişikliği isteği gibi ele alın.

Bir diğer sapma handler şişmesi. Küçük başlar: doğrula, sonra izin kontrolü, sonra DB sorgusu, sonra iş kurallarında dallanma. Kısa süre içinde her handler farklı görünür. Bir kural koyun: handler'lar HTTP'yi tipli girdilere ve çıktılara çevirir; servisler kararların sahibi; veri erişimi sorguların sahibi.

İsim uyumsuzlukları da zamanla birikir. Eğer bir endpoint CreateUserRequest kullanırken diğeri NewUserPayload kullanıyorsa tipleri bulmak ve aracı kod yazmak zaman alır. Bir isimlendirme şeması seçin ve güçlü bir neden olmadıkça yeni adları reddedin.

Ham veritabanı hatalarını istemcilere asla döndürmeyin. İçeriği sızdırmanın yanı sıra, tutarsız mesajlar ve durum kodları yaratır. Dahili hataları sarın, sebebi loglayın ve stabil bir kamu hata kodu döndürün.

Pratik korunma önlemleri:

• Yeni endpoint'lerin mevcut hata tipleri ve yardımcılarını yeniden kullanmasını zorunlu kılın.
• Handler'ları iş kurallarından ve veritabanı erişiminden uzak tutun.
• İstek ve yanıt struct'ları için tek bir isimlendirme kuralı uygulayın.
• Dahili hataları kamu hata kodlarına eşleyin, ham hataları asla döndürmeyin.
• Yeni bağımlılıklar sadece net, yazılı bir gerekçeyle eklensin.

Aynı şekle sahip iki endpoint'i fark edemiyorsanız, istemi sıkılaştırın ve merge etmeden önce yeniden üretin.

Merge öncesi hızlı kontrol listesi

Herhangi bir üretileni merge etmeden önce önce yapı kontrolü yapın. Şekil doğruysa mantık hatalarını bulmak daha kolay olur.

Yapı kontrolleri:

• Handler akışı tutarlı mı: giriş bağla, doğrula, servisi çağır, domain hatalarını HTTP'ye eşle, yanıtı yaz
• Servis kodu sadece iş kuralları içeriyor mu: doğrudan HTTP veya JSON işi yok
• Başarı yanıtları ev stiliyle eşleşiyor mu (her yerde ortak bir zarfta mı yoksa doğrudan JSON mı)
• Hata yanıtları uniform mu: aynı JSON alanları, aynı kodlar, aynı request_id davranışı
• İsimlendirme ve yerleştirme sıkıcı mı: dosya adları, fonksiyon adları ve rota adları mevcut uç noktalarla eşleşiyor ve gofmt uygulanmış

Davranış kontrolleri:

• Testleri çalıştırın ve yeni handler/servis dalı için en az bir küçük test ekleyin
• Doğrulama hatalarının benzer endpoint'lerle aynı kodu ve durumu döndürdüğünü onaylayın
• Bilinen bir servis hatasını (örn. not found veya conflict) tetikleyin ve HTTP durumu ile JSON şeklini kontrol edin
• Yanlış kopyala-yapıştır kalıntılarını tarayın: yanlış rota yolu, yanlış log mesajı, hatalı DTO isimleri
• Sunucuyu yerel olarak derleyip çalıştırın, bağlantı ve importların doğru olduğundan emin olun

Sonraki adımlar: kalıbı standardize edin, sonra güvenli şekilde üretimi ölçekleyin

Kalıbınızı tercih değil bir paylaşılmış sözleşme olarak ele alın. "Nasıl endpoint yapıyoruz" dokümanını kodun yanına koyun ve bir referans endpoint tutun. İlk olarak küçük partiler halinde üretin: farklı kenar durumlarına dokunan 2–3 endpoint (basit bir okuma, doğrulama içeren create, bulunamadı vakasıyla update). Dur ve inceleyin. İncelemelerde aynı stil sapması bulunuyorsa temel dokümanı ve referans endpoint'i güncelleyin, sonra daha fazlasını üretin.

Yineleyebileceğiniz bir döngü:

• Temeli yazın: dosya adları, fonksiyon adları, istek/yanıt struct'ları, hata kodları ve doğrulamanın nerede olduğu
• Bir endpoint'i "altın" tutun ve kalıp değiştiğinde önce onu güncelleyin
• Küme halinde birkaç endpoint üretin, tutarlılık için inceleyin, sonra istemi ve kalıp dokümanını ayarlayın
• Eski endpoint'leri parça parça refactor edin ve davranış değişirse rollback yolu tutun
• Bir hafta boyunca bir metrik takip edin: bir endpoint ekleme süresi, merge sonrası hata oranı veya inceleme süresi

Daha sıkı bir build–review döngüsü isterseniz, sohbet destekli iş akışıyla iskeletleyip iterasyon yapmanızı sağlayan bir platform (ör. Koder.ai (koder.ai)) iş akışınızı hızlandırabilir; ancak araç, temel kurallar sizde olduğu sürece ikincildir.