Mermaid diyagramınız, bir Laravel API üreticisi için geçerli bir girdi.

Veri modelleri diyagramlarda tasarlanır ve koda dönüştürülür, fakat bu iki süreç birbirinden hızla uzaklaşabilir. README’deki diyagramda Post belongsTo Category yazarken, kod bu durumu yansıtmayabilir; gören fark etmez, ta ki bir migration hatası verene dek.

Benim laravel-api-generator için bulduğum çözüm: diyagramı girdi olarak kullanmak. İki format işliyor: YAML ve Mermaid.

YAML

# api-schema.yaml
options:
  pest: true
  postman: true

entities:
  Category:
    fields:
      name: string unique
    relations:
      posts: hasMany Post

  Post:
    fields:
      title: string
      content: text
      status: enum(draft,published) default=draft
      published_at: datetime nullable

php artisan make:fullapi --schema=api-schema.yaml

Eksik olan noktaya dikkat edin: Post, belongsTo Category tanımını yapmıyor ve nereye ait olduğunu belirtmek için category_id alanı yok. Generator, ters ilişkiyi ve yurt dışı anahtar sütununu sentezliyor. Bir tarafı belirtirsiniz, iş arkadaşınıza açıkladığınız gibi, hem iki taraf da kodda mevcuttur.

enum satırı, destekli enum sınıfını, model caster’ını, Rule::enum validasyonunu ve rastgele durumlar seçen bir factory oluşturur. Bu zincir hakkında daha fazla ayrıntıyı part 1‘de yazdım.

Bunlardan en çok kullandığım, çünkü GitHub’da PR’da görünür:

Mermaid

php artisan make:fullapi --mermaid=docs/erd.mmd

Hem erDiagram hem de classDiagram çalışır. Kardinaliteler, doğru Eloquent ilişkilerine bağlanır; UK işaretleri, benzersiz alanlara dönüşür, bir deleted_at sütunu, soft delete’leri etkinleştirir. Markdown koruma ve yorumlar kaldırıldığı için, bir AI sohbetinden doğrudan yapıştırılmış bir diyagram çalışır. Diyagramı pull request’te gözden geçirin, birleştirin, üretilsin. Uzaklaşma durumu yok, çünkü kaçış yok.

VS Code eklentisi, aynı Mermaid girdisini terminal olmadan alır ve ters görünümü de çizer: editörde etkileşimli bir varlık diyagramı (yakınlaştır, gezin) gösterir. Diyagram girer, API çıkar ve tuval, gerçek anlamda ne olduğunu gösterir.

Özel birincil anahtarlar yayılır

Country:
  fields:
    code: string primary
    name: string
  relations:
    cities: hasMany City

Bu, v3.6’daki en uzun süren isteklerdendi. City, country_code kolonu alıyor ve bu kolon anahtar gibi yazılıyor; ->references('code') migration’da, exists:countries,code validasyonda geçerli, ve model $primaryKey, $incrementing ve $keyType tanımlar. Oluşturulan testler, getKey() kullanıyor, böylece aynı test seti, herhangi bir anahtar türüyle geçiyor. Polimorfik ilişkiler (morphTo, morphOne, morphMany) de şemalarda destekleniyor.

30. Gün

Her scaffold, 1. günde iyi çalışıyor ve 30. günde siliniyor, çünkü yeniden oluşturmak, manuel işinizi siler. Bu nedenle, burada evrilme yolu yeniden üretim değil. Yamanın yolu:

php artisan make:fullapi Post --add-fields="excerpt:text,seo_title:string"

Bu, artı bir Schema::table migration’ı yazıyor ve bir down() ile birlikte, $fillable, castlar, PHPDoc, validasyon kuralları, factory ve kaynakları mevcut konumda patlatıyor. Özel yöntemleriniz etkilenmiyor. Halihazırda var olan alanlar atlanıyor. DTO ve testler, kasıtlı olarak yalnız bırakılıyor ve manuel takipler olarak raporlanıyor, çünkü sıradışılıklar, yararlılıktan daha tehlikeli görünüyordu.

Pratik Notlar

Geliştirme bağımlılığı, MIT; oluşturulan kodun pakete referansı yok. CI içinde ve AI kodlama araçları ile çalışır; tüm API’yi tanımlayan bir YAML dosyası, “on iki dosya oluştur” yerine bir ajanın hedef alması için çok daha iyi bir hedef. Daha önce bahsedilen eklenti aynı zamanda canlı önizleme ile bir form oluşturucu da ekler, bir veritabanından veya bir OpenAPI spesifikasyonundan içe aktarma yapar ve bir tıkla migrate, seed ve belgeleri oluşturur.

Schema formatının neyi desteklemesi gerektiği hakkında fikirleriniz varsa, sorunlar açıktır. Benimki, bunun inşası sırasında üç kez değişti.