Az API-k tervezésének legjobb gyakorlatai a Laravelben

Ellopták innen.

Ennek a bejegyzésnek audio változata van Miguel Piedrafita Blogcast alkalmazásának köszönhetően.

Nemcsak DevOps mérnök vagyok, de a PHP-vel kezdtem a nulla földrõl is, mióta kicsi gyerek voltam, akkoriban, az ötödik osztályban. Azóta folyamatosan fejlesztem a kódomat, és rájöttem, hogy az emberek valamilyen szabványt fogadtak el a tisztább kód, a jobb megjelenítés érdekében, és mivel ezek szabványok, mindenki jobban megértheti, amit minden más fejlesztő ugyanazon a kódbázisban írt.

Mindig szerettem inkább a hátteret kódolni, mint az előlapon. Próbáltam Full Stack lenni, de ez nem tetszett nekem. Tehát visszatértem a háttérrendszer, különösen az API-k írására. Ezúttal nem fogok általában a kódolási szabványokról beszélni, de arról fogok beszélni, hogy mi az API-k ténylegesen működnek, és hogyan lehet őket könnyebben fejleszteni, a biztonságtól kezdve a tippekig, hogyan lehetne jobban végrehajtani.

Alapvetően az API olyan felület, amely olyan speciális formátumban ad vissza adatokat, amely bármilyen alkalmazás, akár Android, akár egy webalkalmazás számára érthető.

A JSON-t széles körben használják, mivel szinte mindenhol megtalálható. A másik lehetőség az XML használata, de nehez voltam néhány olyan harmadik féltől származó API-val (különösen az országomban működő fizetési szolgáltatókkal), amelyek XML-et használtak a JSON felett, és a fejlesztés teljes szar volt. Javaslom a JSON API fejlesztését, kivéve, ha valaki XML API-t kér.

Az API fejlesztésekor figyelembe kell vennie néhány dolgot, ebben a sorrendben:

  • biztonság - az OAuth, API-kulcs vagy CORS használatával történő biztosítása kötelező. Opcionálisan fojtószelepet kell használnia a kérelmek korlátozására az alkalmazásra.
  • fejlécek - győződjön meg arról, hogy alkalmazásai a megfelelő tartalomtípust küldik el. A tartalomtípus fejléce egy kis információ, amely azt mondja az adatot fogadó kliensnek: „ez az, amit én neked küldök, JSON” vagy „hogy itt XML. megfelelően értelmezzük ”, így a böngésző vagy az ügyfél tudja, hogyan kell megfelelően dekódolni.
  • kódolási szabványok és elnevezés - ez pusztán háttér. Győződjön meg arról, hogy következetesek a válaszaiban. Ragaszkodjon csak az egyik elnevezéshez és a megfelelő formázáshoz.

Szeretem kódolni a Laravel-ben az API-kat, mivel tovább akarja skálázni az Event Broadcasting vagy a hiányzó Lumen funkciók segítségével, amelyek gyors üteművé teszik, ezt megteheti anélkül, hogy a teljes projektet a semmiből újraírná. Ha alig marad meg, nyugodtan használja a Lumen-t.

Biztonság

A legnagyobb probléma, amelyet vigyáznia kell, a biztonság. Könnyű biztosítani, de ha nem csinálja megfelelően, akkor nem kívánt hozzáférést kaphat. A Laravelben érdemes lehet a Laravel Passportot használni - ez a Laravel ökoszisztéma része, támogatja a hitelesítést azon az alkalmazás-azonosítón keresztül - Az App Secret nagyon érdekes ahhoz, hogy hozzáférési jogkivonatot szerezzen, akár valakinek, akár egy szervernek a megszemélyesítésére, akár háttérként, akár előlapként. Alapvetően az alkalmazás azonosítójával és az App Secret alkalmazásával kérést fog benyújtani egy OAuth-végponthoz olyan token fogadására, amelyet vagy egy szerver generálhat (azaz API elérése egy parancsból, amely minden nap cronjobban fut), vagy egy felhasználó, aki bejelentkezett az alkalmazásába.

Alternatív megoldásként használhatja a JWT Token hitelesítést, amely szinte ugyanaz, de talán könnyebben érthető. Válaszd ki a választást, és nézd meg, melyik a legmegfelelőbb az Ön számára, mind a megvalósítás, mind az Ön igényei szerint.

fejlécek

A webes kérések csak normál beszélgetések az ügyfél és egy szerver, vagy két szerver között. Egy kérésre és válaszra támaszkodnak, kivéve, ha ez webes típusú kérés, de ez csak egy új történet. A dolgok kérésekor vagy visszaküldésekor van néhány olyan fejléc nevű információ, amelyet vigyázni kell - ezek közül néhány megmondja a szervernek, hogyan kell feldolgozni a kapott információkat, vagy hogy az ügyfél hogyan szeretné kapni a választ.

Olyan, mint az anyád azt mondja neked: "menjen, vásároljon tejet a boltból, de csak az X márkájú tejet vásárolja". Tudod, mit kell tennie, de csak egyféle tejet kell választania. Ugyanaz, mint a kérések: "Szeretnék beszerezni a felhasználói listát, de adjam meg nekem JSON-ban" vagy "Szeretnék megszerezni az összes felhasználót, de küldje el nekem 20 darabonként" (abban az esetben, ha megad egy GET paramétert) ). Ehhez van egy Accepts nevű fejléc, amely alkalmazás / json lehet arra az esetre, ha a választ JSON-ként szeretné. Nem kötelező, de egyes alkalmazások, például az AJAX esetén, ha észleli ezt a fejlécet, automatikusan dekódolja a választ az ügyfél számára anélkül, hogy ehhez hasonlót kellene tennie:

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

Egy másik fejléc, amelyet tisztában kell lennie, a Tartalomtípus, ami kissé zavaró, de ellentétes az Accepts-tel: elmondja a szervernek, hogyan kell kezelni a kapott tartalmat. Például, ha RAW-adatokat szeretne küldeni, például JSON-karakterlánccal, beállíthatja a Tartalomtípus alkalmazást / json értékre, de ha a tartalmat a $ _POST változón keresztül szeretné megkapni, állítsa x-www értékre. -form-urlencoded. Ez nemcsak a tartalom közvetlenül a $ _POST-on keresztül történő elemzésében segít, hanem HTML formában is használni kell, mert könnyen elérhető. Ha adatokat küld, például bináris formátumban, például fájlbemeneteken keresztül, akkor ellenőrizze, hogy a tartalom többrészes / űrlapadatokat küldte-e.

Laravelben ez nem lesz probléma, mivel közvetlenül hozzáférhet az adatokhoz.

Alkalmazás / json esetén:

funkció index ($ kérés kérése)
{
   $ var = $ kérés-> változó;
}

Az alkalmazás / json alkalmazásban azonban a -> all () módszer használatával nem láthatja a JSON-tartalmat:

funkció index ($ kérés kérése)
{
   $ data = $ request-> all (); // ez üres tömb, még adatokkal is rendelkezünk.
}

Ha x-www-form-urlencoded vagy multipart / form-data értékre van állítva, akkor az összes változót a -> all () gombbal láthatja.

Visszaválaszoláskor a Laravelben használhatja a beépített JSON választ, VAGY jobban ki tudja dolgozni, és használhat olyan csomagot, mint a Laravel Fractal vagy a Laravel Responder. Saját tapasztalataim alapján a Laravel Responder jobban, szemantikus módon végezte el a munkát. Hadd mutassam meg:

getUsers függvény ($ kérés kérése)
{
   válaszadó visszatérése () -> siker (Felhasználó :: összes ()) -> válasz ();
}

Ez az OK 200 állapotú és JSON formátumú összes felhasználót visszaküldi. Hűvös, igaz? Hiba esetén valami hasonlót kell tennie, amely lehetővé teszi egy kód és egy üzenet küldését:

getUsers függvény ($ kérés kérése)
{
   $ users = Felhasználó :: all ();

   if ($ felhasználók-> számlálás () === 0) {
      return responder () -> hiba ('no_users', 'Nincs felhasználó.') -> respon ();
   }
   visszatérő válaszadó () -> siker ($ felhasználók) -> válasz ();
}

Ez a csomag sokkal többet támogat, ezért forduljon tovább a dokumentumokhoz, mert könnyen integrálható transzformátorokkal és küldött egyedi adatokkal.

Kódolási szabványok

Amit szeretek látni, az emberek ragaszkodnak bizonyos szabványokhoz, amelyek megfelelnek nekik, vagy tisztaak. Íme néhány tipp, amelyek segíthetnek a tisztább kód felépítésében és az API útvonalak jobb szerkezetében.

Használjon útvonalakat / api.php fájlt az API útvonalakhoz

A Laravel külön útvonalakat / api.phpfile-t kap, amelyek eltérnek a szokásos útvonalaktól / web.php fájltól, amelyet a webes útválasztáshoz használnak. Az api.php fájlt az API útvonalainak tárolására hozták létre. Van egy fedélzeti alkalmazott köztes szoftver (amely látható az app / Http / Kernel.php fájlban, a $ middlewareGroups változóban, api alatt) és / api előtaggal, tehát az összes megadott útvonal már elérhető az / api számára

Használja az útvonalneveket

Amit szeretek csinálni, az az, hogy beállítsam a beállítást az egész API-ra, így hozzáférhetek az útvonalakhoz a nevükkel, api-vel. előtagot.

Útvonal :: get ('/ users', 'API \ UserController @ getUsers') -> név ('get.users');

Ennek az útvonalnak az URL-je elérhető lehet az útvonal használatával ('get.users'), de ellentmondásban lehet a web.php-vel.

Útvonal :: csoport (['as' => 'api.'], Function () {
   Útvonal :: get ('/ users', 'API \ UserController @ getUsers') -> név ('get.users');
});

Így lesz az útvonalon ('api.get.users').

Ha az útvonalneveket használja, akkor az írástesztnél nem kell mindenhol cserélnie az URL-t, ha az URL-hely megváltoztatását tervezi, és megtartja az útvonal nevét.

Leíró, mégis egyszerű útvonalak

Jó gyakorlat az útvonalak szakaszokra csoportosítása, például felhasználók, hozzászólások stb., És a legegyszerűbb dolgok felhasználása, amelyekre gondolhat:

Útvonal :: csoport (['as' => 'api.'], Function () {
   Útvonal :: csoport (['as' => 'account.', 'Prefix' => '/ account'], function () {
         Útvonal :: get ('/ users', 'API \ UserController @ getUsers') -> név ('get.users');
         Útvonal :: get ('/ user / {id}', 'API \ UserController @ getUser') -> név ('get.user');
         Útvonal :: post ('/ user', 'API \ UserController @ createUser') -> név ('create.user');
         // stb.
   });
});

Használja a :: get () adatgyűjtést, :: post () létrehozáshoz, :: patch () vagy :: put () szerkesztéshez és :: delete () az adatok törléséhez. Ilyen módon ugyanazt a végpontot használja, de másfajta kérésekkel más műveleteket indíthat.

A vezérlőn belül egyszerű kódolást kell használnia, és igénybe kell vennie a Request osztályokat, amint azt a Laravel továbblépése című részben kifejtettem - legjobb tippek és bevált gyakorlatok a Laravel 5.7-hez

getUsers függvény ($ kérés kérése)
{
   $ users = Felhasználó :: all ();
   visszatérő válaszadó () -> siker ($ felhasználók) -> válasz ();
}
getUser függvény ($ id, $ kérés kérése)
{
   $ felhasználó = felhasználó :: findOrFail ($ id);
   visszatérő válaszadó () -> siker ($ felhasználó) -> válasz ();
}
createUser függvény (CreateUserRequest $ kérés)
{
    $ felhasználó = felhasználó :: létrehozás ($ kérés-> minden ());
    visszatérő válaszadó () -> siker ($ felhasználó) -> válasz ();
}
// stb.

Ezenkívül ügyeljen arra, hogy minden műveletnél azonos elnevezéseket tartson, így gyorsabban találja meg azokat, és bárki beléphet a kódbázisba, és megkönnyítheti a tartalom karbantartását vagy létrehozását. Ne kötelezzen el API kulcsokat vagy érzékeny adatokat a repóba, írjon tiszta kódot, és lelkesen tanuljon másoktól.

Túl nehéz megérteni? Érj el engem!

Ha további kérdései vannak a Laravel-rel kapcsolatban, ha segítségre van szüksége a DevOps-szal kapcsolatos bármilyen információval, vagy egyszerűen csak köszönetet szeretne mondani, akkor a Twitteren @rennokki találhat meg engem!

Csatlakozzon a Slack közösséghez, és olvassa el a heti Faun témáinkat ⬇

Ha ez a bejegyzés hasznos volt, kérjük, néhányszor kattintson a taps lap gombra, hogy megmutassa a szerző támogatását! ⬇