Laravel'de API tasarımı için en iyi yöntemler

Buradan çalındı.

Bu yazının Miguel Piedrafita’nın Blogcast uygulaması sayesinde sesli bir sürümü var.

Ben sadece bir DevOps Mühendisi değilim, aynı zamanda 5. sınıftayken küçük bir çocuk olduğum için PHP ile sıfırdan başladım. O zamandan beri kodumu sürekli geliştirdim ve insanların daha temiz kod için bir tür standartlar benimsediğini, daha iyi görselleştirme olduğunu ve standart olduklarından herkesin diğer geliştiricilerin aynı kod tabanında yazdıklarını daha iyi anlayabildiğini öğrendim.

Ben her zaman ön uçtan ziyade arka uçta kod yazmayı sevdim. Full Stack olmaya çalıştım, ama bana uygun değildi. Bu yüzden arka uç yazmaya, özellikle API'lere geri döndüm. Bu kez, genel olarak kodlama standartları hakkında konuşmayacağım, ancak güvenlikten daha iyi yapmanın ipuçlarına kadar hangi API'lerin gerçekten çalıştığı ve bunların nasıl daha kolay geliştirileceği hakkında konuşacağım.

Temel olarak, bir API, verileri bir Android uygulaması veya bir web uygulaması gibi herhangi bir uygulamanın anlayabileceği özel bir biçimde döndüren bir arayüzdür.

JSON, neredeyse her yerde olduğu için yaygın olarak kullanılmaktadır. Diğer seçenek ise XML kullanmak, ancak JSON üzerinden XML kullanan bazı üçüncü parti API'lerde (özellikle ülkemdeki ödeme sağlayıcıları) sorun yaşadım ve bu gelişme tam bir sorun oldu. Biri XML API istemiyorsa, sürekli olarak JSON API'leri geliştirmenizi öneririm.

Bir API geliştirirken, bu belirli sırayla bazı şeyleri dikkate almanız gerekir:

  • güvenlik - OAuth, bir API anahtarı veya CORS kullanarak güvenlik altına alınması şarttır. İsteğe bağlı olarak, isteklerinizi uygulamanızla sınırlandırmak için bir azaltıcı kullanıyor olmalısınız.
  • başlıklar - uygulamalarınızın doğru içerik türünü gönderdiğinden emin olun. Bir içerik türü başlığı, müşteriye veriyi aldığını söyleyen bilgidir: “size gönderdiğim bu şey JSON” veya “buradakiler XML. düzgün bir şekilde ayrıştırın ”, böylece tarayıcı veya müşteriniz düzgün bir şekilde nasıl çözüleceğini bilir.
  • kodlama standartları ve adlandırma - bu tamamen arka uç. Yanıtlarınızda tutarlı olduğunuzdan emin olun. Sadece bir tür isimlendirme ve uygun biçimlendirme yapın.

Etkinlik Yayıncılığı veya cayır cayır yanan hızlı yapan diğer eksik Lümen özellikleri ile daha fazla ölçeklendirmek istediğiniz için Laravel'deki API'leri kodlamayı çok seviyorum, tüm projeyi sıfırdan yazmadan yapabilirsiniz. Çıplak kalmaya devam ederseniz, Lumen kullanmaktan çekinmeyin.

Güvenlik

Dikkat etmeniz gereken en büyük sorun güvenlik. Koruması kolaydır, ancak düzgün şekilde yapmazsanız, istenmeyen erişime sahip olabilirsiniz. Laravel'de, Laravel Passport'u kullanmak isteyebilirsiniz - bu, Laravel ekosistemine aittir, erişim belirteci almak için birisinin veya bir sunucunun arka uç veya ön uçlarını taklit etmek için bu Uygulama Kimliği - Uygulama Gizli özelliği aracılığıyla kimlik doğrulamasını destekler. Temel olarak, Uygulama Kimliği ve Uygulama Gizliliğiniz ile bir sunucu tarafından oluşturulabilecek bir jeton almak için bir OAuth bitiş noktasına talepte bulunacaksınız (yani, her gün bir cronjob'da çalışan bir komuttan bir API'ye erişme) veya uygulamanıza giriş yapan kullanıcı.

Alternatif olarak, neredeyse aynı şekilde çalışan bir JWT Token kimlik doğrulaması kullanmak isteyebilirsiniz, ancak anlaşılması daha kolaydır. Seçiminizi seçin ve hem uygulamada hem de ihtiyaçlarınızda hangisinin size daha uygun olduğunu görün.

Başlıkları

Web istekleri yalnızca bir istemci ile bir sunucu arasındaki veya iki sunucu arasındaki normal görüşmelerdir. Bir websocket türü bir istek olmadığı sürece, bir talebe ve cevaba dayanırlar, ancak bu başka bir hikaye. Bir şeyleri talep ederken veya geri gönderirken, ilgilenilmesi gereken Başlıklar adında bir miktar bilgi vardır - bazıları sunucuya, alınan bilginin nasıl işleneceğini veya müşterinin yanıtı nasıl almak istediğini söyler.

Annenin size dediği gibi: “mağazadan biraz süt al, sadece X markalı sütün al”. Ne yapacağını biliyorsun, ama sadece bir tür süt seçmelisin. Taleplerin aynısı: “kullanıcıların listesini almak istiyorum, fakat onları JSON'da ver” ya da “Tüm kullanıcıları almak istiyorum, ancak beni 20'lik parçalara gönder” (GET parametresi belirtmeniz durumunda) ). Bunun için, JSON olarak yanıt istemeniz durumunda Accept adında bir başlık var. Bu bir zorunluluk değildir, ancak AJAX gibi bazı uygulamalar için, bu başlığı algılarsa, böyle bir şey yapmak zorunda kalmadan, istemcinin yanıtını otomatik olarak çözer:

var veri = JSON.parse (response.data);

Bilmeniz gereken bir diğer başlık, biraz kafa karıştırıcı olan Content-Type'dir, ancak Kabuller’in tam tersi: sunucuya aldığı içeriği nasıl kullanacağını bildirir. Örneğin, bir JSON dizesi gibi RAW verileri göndermek istiyorsanız, Content-Type'ı uygulama / json olarak ayarlayabilirsiniz, ancak içeriği $ _POST değişkeni üzerinden almak istiyorsanız, x-www olarak ayarlamanız gerekir. biçim-urlencoded. Bu, içeriği yalnızca $ _POST ile doğrudan ayrıştırmakla kalmaz, aynı zamanda kolayca erişilebildiği için HTML formlarında kullanılmalıdır. İkili gibi, örneğin dosya girişleri aracılığıyla veri gönderiyorsanız, içerik çok parçalı / form verilerini gönderdiğinizden emin olun.

Laravel'de verilere doğrudan erişebildiğiniz için bu bir problem olmayacak.

/ Json başvurusu için:

İşlev dizini (İstek $ isteği)
{
   $ var = $ request-> değişken;
}

Ancak, / json uygulamasında JSON içeriğinin -> all () yöntemini kullandığını göremezsiniz:

İşlev dizini (İstek $ isteği)
{
   $ data = $ request-> all (); // bu boş bir dizi, hatta verilerimiz var.
}

X-www-form-urlencoded veya multipart / form-data olarak ayarlanmışsa, -> all () kullanarak tüm değişkenleri görebilirsiniz.

Geri cevap verirken, Laravel'de yerleşik JSON yanıtını kullanabilir VEYA daha iyi çalışabilir ve Laravel Fractal veya Laravel Yanıtlayıcı gibi bir paket kullanabilirsiniz. Kendi tecrübelerime göre, Laravel Responder işi daha anlamsal bir şekilde daha iyi yaptı. Sana göstereyim:

getUsers işlevi ($ request)
{
   yanıt ver () -> success (Kullanıcı :: all ()) -> response ();
}

Bu durum OK 200 statüsüne sahip ve JSON olarak formatlanmış tüm kullanıcıları iade edecektir. Harika değil mi? Hatalar için, bir kod ve mesaj göndermenizi sağlayan böyle bir şey yapmanız gerekir:

getUsers işlevi ($ request)
{
   $ users = Kullanıcı :: all ();

   if ($ users-> count () === 0) {
      return responder () -> error ('no_users', 'Kullanıcı yok.') -> response ();
   }
   yanıtı döndür () -> başarı ($ kullanıcı sayısı) -> yanıt ();
}

Bu paket çok daha fazlasını destekliyor, bu nedenle dokümanlara yönlendirilir, çünkü transformatörlerle ve gönderilen özel verilerle kolayca entegre edilebilir.

Kodlama standartları

Görmeyi sevdiğim insanlar kendilerine uyan veya temiz olan bazı standartlara sadık kalarak insanlar. İşte size daha temiz kod oluşturmanıza ve API rotalarınızı daha iyi yapılandırmanıza yardımcı olabilecek bazı ipuçları.

API yolları için routes / api.php dosyasını kullanın

Laravel, web yönlendirmesinde kullanılan normal rotalar / web.php dosyasından korunan ayrı bir rota / api.phpfile dosyası ile birlikte gelir. api.php dosyası, API rotalarınızı depolamak için oluşturulur. Üzerinde yerleşik bir ara katman yazılımı (app / Http / Kernel.php içinde, $ middlewareGroups değişkeninde, api altında görülebilir) ve / api önekine sahiptir, bu nedenle tanımlanan tüm yollar zaten / api için kullanılabilir

Rota adlarını kullanın

Yapmayı sevdiğim şey, tüm API için bir ayar olarak ayarlamak, böylece rotalara kendi ismiyle api ile erişebiliyorum. önek.

Route :: get ('/ users', 'API \ UserController @ getUsers') -> name ('get.users');

Bu rotanın URL’si rotayı ('get.users') kullanıyor olabilir, ancak web.php ile çakışabilir.

Güzergah :: group (['as' => 'api.'], Function () {
   Route :: get ('/ users', 'API \ UserController @ getUsers') -> name ('get.users');
});

Bu yolla, rotanız üzerinde olacaktır ('api.get.users').

Rota adlarını kullanırsanız, yazma testleriniz varsa, URL konumunu değiştirmeyi ve rota adını korumayı planlıyorsanız URL'yi her yerde değiştirmeniz gerekmez.

Açıklayıcı, henüz basit rotalar

İyi bir uygulama, yolları kullanıcılar, postalar vb. Gibi bölümlere ayırmak ve aklınıza gelebilecek en basit şeyleri kullanmaktır:

Güzergah :: group (['as' => 'api.'], Function () {
   Route :: group (['as' => 'hesap.', 'Önek' => '/ hesap'], işlev () {
         Route :: get ('/ users', 'API \ UserController @ getUsers') -> name ('get.users');
         Route :: get ('/ user / {id}', 'API \ UserController @ getUser') -> name ('get.user');
         Route :: post ('/ user', 'API \ UserController @ createUser') -> name ('create.user');
         // vb.
   });
});

Veri almak için :: get (), oluşturma için :: post (), düzenleme için :: patch () veya :: put () ve verileri silmek için :: delete () kullanın. Bunun gibi, aynı son noktayı kullanmanız yeterlidir, ancak farklı isteklerde başka eylemleri tetikleyebileceksiniz.

Kontrol cihazınızın içinde, basit kodlama kullanıyor olmalı ve Laravel'i daha ileri itmek bölümünde açıkladığım gibi Request sınıflarından faydalanmalısınız - Laravel 5.7 için en iyi ipuçları ve iyi uygulamalar

getUsers işlevi ($ request)
{
   $ users = Kullanıcı :: all ();
   yanıtı döndür () -> başarı ($ kullanıcı sayısı) -> yanıt ();
}
getUser işlevi ($ id, $ request)
{
   $ user = Kullanıcı :: findOrFail ($ id);
   yanıtı döndür () -> başarı ($ kullanıcı) -> yanıt ();
}
createUser işlevi (CreateUserRequest $ request)
{
    $ user = Kullanıcı :: create ($ request-> all ());
    yanıtı döndür () -> başarı ($ kullanıcı) -> yanıt ();
}
// vb.

Ayrıca, tüm eylemler için aynı adlara bağlı kaldığınızdan emin olun, böylece daha hızlı bulabilirsiniz ve kod koduna herkes girebilir ve içerik oluşturmayı veya oluşturmayı kolaylaştırabilir. Depoya API anahtarları veya hassas veriler vermeyin, temiz kod yazın ve diğerlerinden bilgi edinmek için istekli olun.

Anlamak çok mu zor? Bana ulaş!

Eğer Laravel hakkında daha fazla sorunuz varsa, DevOps ile ilgili herhangi bir konuda yardıma ihtiyacınız varsa veya sadece bir Teşekkür!

Topluluğumuza katılın Slack ve haftalık Faun konularımızı okuyun ⬇

Bu yayın yardımcı olduysa, yazara desteğinizi göstermek için lütfen birkaç kez aşağıdaki p düğmesine tıklayın! ⬇