30 Saniyede Temiz Mimari ile Tam Laravel API, Testler Dahil

<p>İlk gerçek iş mantığına gelmeden önce on iki dosya. Bu dosyaları yazmaktan yoruldum, bu yüzden bir jeneratör yazdım. MIT lisanslı, tek başıma bakımını yapıyorum ve bu hafta v3.6'yı çıkardım.</p>

<h2>
    <a name="one-command" href="#one-command"></a>
    Tek komut
</h2>

<div class="highlight js-code-highlight">
    <pre class="highlight shell"><code>composer require <span class="nt">--dev</span> nameless/laravel-api-generator

<p>Çıktı:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight plaintext"><code>app/

├── DTO/PostDTO.php
├── Enums/Status.php
├── Http/
│ ├── Controllers/PostController.php
│ ├── Requests/PostRequest.php
│ └── Resources/PostResource.php
├── Models/Post.php
├── Policies/PostPolicy.php
└── Services/PostService.php
database/
├── factories/PostFactory.php
├── migrations/xxxx_create_posts_table.php
└── seeders/PostSeeder.php
tests/
├── Feature/PostControllerTest.php
└── Unit/PostServiceTest.php
routes/api.php ← apiResource registered

<h2>
    <a name="the-vs-code-extension-same-engine-no-terminal-needed" href="#the-vs-code-extension-same-engine-no-terminal-needed"></a>
    VS Code uzantısı: aynı motor, terminale ihtiyaç yok
</h2>

<p>Eğer yazmaktansa tıklamayı tercih ediyorsanız, ücretsiz <a href="https://marketplace.visualstudio.com/items?itemName=Nameless0l.laravel-api-generator" target="_blank" rel="noopener noreferrer">VS Code uzantısı</a>, aynı <code>make:fullapi</code> komutunu çalıştırır, böylece dosyalar aynı olur. Bir varlık tanımını bir formda (alanlar, enumlar, ilişkiler, seçenekler) yapıyorsunuz ve canlı bir önizleme, herhangi bir şey yazılmadan önce tam kodu gösteriyor. Ya da formu atlayabilir ve mevcut veritabanınızdan, bir YAML şemasından, bir Mermaid diyagramından veya bir OpenAPI/Swagger spesifikasyonundan içe aktarabilirsiniz.</p>

<p>Her zaman ilk tanıttığım buton <strong>Açık API Belgeleri</strong>: Scramble'nın kurulu olduğunu kontrol eder (ve yoksa kurmak için teklif eder), çalışan bir Laravel sunucusunu bulur veya <code>php artisan serve</code>'u kendisi başlatır, portu tespit eder ve yeni API'nizin etkileşimli belgelerini tarayıcıda açar. Migration ve seeding de tek tıklamayla yapılabilir ve eğer <code>.env</code> dosyası yoksa, uzantı bunu <code>.env.example</code>'dan oluşturmayı önerir. Boş bir Laravel projesinden tarayıcıda gezinilebilir, belgelenmiş, test edilmiş bir API'ye tek bir terminal açmadan geçebilirsiniz.</p>

<h2>
    <a name="the-part-i-actually-care-about-the-architecture" href="#the-part-i-actually-care-about-the-architecture"></a>
    Gerçekten önemsediğim kısım: mimari
</h2>

<p>Pek çok araç bir model ve migration üretebiliyor. Benim istediğim, her ciddi projede elle inşa ettiğim katmanlamaydı. Üretilen controller ince:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="k">public</span> <span class="k">function</span> <span class="n">store</span><span class="p">(</span><span class="kt">PostRequest</span> <span class="nv">$request</span><span class="p">)</span>

{
$dto = PostDTO::fromRequest($request);
$post = $this->service->create($dto);

<span class="k">return</span> <span class="k">new</span> <span class="nc">PostResource</span><span class="p">(</span><span class="nv">$post</span><span class="p">);</span>

}

<p>Validation, form request içinde, iş mantığı <code>PostService</code> içinde, ve veriler katmanlar arasında tipli readonly <code>PostDTO</code> olarak geçer. Proje büyüdüğünde, yeni mantık eklemek için doğru yer zaten mevcut. Bu, işin bütün noktası.</p>

<h2>
    <a name="models-your-ide-can-read" href="#models-your-ide-can-read"></a>
    IDE'nizin okuyabileceği modeller
</h2>

<p>Her üretilen model, gerçek bir PHPDoc bloğu ile birlikte gelir:<br/></p>

<div class="highlight js-code-highlight">
    <pre class="highlight php"><code><span class="cd">/ 

• @property int $id

• @property string $title

• @property string $content

• @property Status $status

• @property \Illuminate\Support\Carbon|null $published_at

• @property-read \Illuminate\Database\Eloquent\Collection $comments
  */
  class Post extends Model
  

  Böylece $post->title VS Code ve PhpStorm’da otomatik tamamlanır, ide-helper’ı kurmaya gerek kalmaz. Jeneratör, her alanı ve ilişkileri oluşturma aşamasında zaten bilmektedir; docblock yazımı hiçbir maliyet getirmemektedir.

  
  enum(draft,published)‘in ürettiği
  

  O bir alan tanımı beş tutarlı parçayı oluşturdu:

  • App\Enums\Status, yerel bir desteklenen enum
  • modeldeki cast
  • Rule::enum(Status::class) her iki form isteğinde
  • fake()->randomElement(Status::cases()) fabrika içinde
  • $table->enum('status', [...]) migration içinde

  v3.6’dan önce paket enumları stringlere eşlemekteydi. Tüm zinciri bağlamak beklediğimden daha uzun sürdü, çoğunlukla fabrika nedeniyle.

  
  Testler yazıldı, oluşturulmadı
  

  Bu benim sınırım. Çoğu jeneratör boş test sınıfları bırakıyor. Burada php artisan test çalıştırdığınızda, index, store, validation hataları, update, delete gerçek doğrulamalarla kapsanmıştır.

  it('creates a post', function () {
   $payload = Post::factory()->raw();
  $this->postJson('/api/posts', $payload)
  ->assertCreated();
  $this->assertDatabaseHas('posts', ['title' => $payload['title']]);
  });
  

  Bu, --pest bayrağından gelen Pest stilidir. Onu kullanmadan PHPUnit sınıfları ile aynı kapsama sahip oluyorsunuz.

  
  Belgeler, Postman, kimlik doğrulama
  

  --postman proje kökünde içe aktarılmaya hazır bir koleksiyon yazar. Controllerlar, Scramble‘nın bunlardan OpenAPI belgeleri oluşturabilmesi için notasyon olmadan yazılmıştır. --auth Sanctum’u oluşturarak (kayıt, giriş, çıkış, kaynaklar üzerinde middleware) şablonlar yaratır.

  Ayrıca, var olan bir veritabanını tam API’lere tersine mühendislik yaparak dönüştüren --from-database modu da bulunmaktadır, ancak bu kendi makalesini gerektiriyor.

  
  Sıfır kilitlenme
  

  Paket --dev ile yüklenir ve üretilen kodun bunun üzerine bağımlılığı yoktur. Hiçbir temel sınıf, runtime yardımcıları, hiçbir şey use yok. Üretim yaptıktan sonra jeneratörü kaldırabilirsiniz ve uygulama bunu fark etmez. Eğer üretilen stil hoşunuza gitmezse, 24 şablonu yayınlamak için php artisan vendor:publish --tag=api-generator-stubs komutunu çalıştırabilir ve istediğiniz gibi düzenleyebilirsiniz.

  
  Nerede durur
  

  Sadece temiz bir REST altyapısını oluşturur ve ardından sahneden çıkar. Alan mantığınız, garip sorgularınız, kenar durumlarınız: hala sizin işiniz. Fark, bunları zaten var olan bir servis katmanında yazmanızdır ve temel testler zaten geçer.

  
  Bağlantılar
  

  composer require --dev nameless/laravel-api-generator
  php artisan make:fullapi Product --fields="name:string,price:decimal,stock:integer" --pest
  php artisan test
  

  Eğer denerseniz ve bir şey bozulursa, bir sorun açın. Kullanıcıların bildirdiği şema kenar durumları, son sürümlerin çoğunu yönlendirdi ve ben sizin hikayenizi tahmin etmektense duymayı tercih ederim.

Kaynak: Orijinal Makale