Labākā prakse API projektēšanā Laravel

No šejienes nozagts.

Šai ziņai ir audio versija, pateicoties Migela Piedrafita lietotnei Blogcast.

Es esmu ne tikai DevOps inženieris, bet arī kopš PHE, sākot ar mazu bērnu, es esmu sācis darbu pie nulles līmeņa, sākot no dienām, kad mācījos 5. klasē. Kopš tā laika es nepārtraukti pilnveidoju savu kodu un uzzināju, ka cilvēki ir pieņēmuši kaut kādus standartus tīrākam kodam, labākai vizualizācijai, un, tā kā tie ir standarti, visi varēja labāk saprast, ko visi citi izstrādātāji ir uzrakstījuši tajā pašā kodu bāzē.

Man vienmēr ir paticis kodēt vairāk aizmugures, nevis priekšējā daļā. Es centos būt pilna kaudze, bet tas man nederēja. Tāpēc esmu atgriezies pie aizmugures, it īpaši API, rakstīšanas. Šoreiz es nerunāšu par kodēšanas standartiem kopumā, bet runāšu par to, kādi API faktiski darbojas un kā tos vieglāk attīstīt, sākot no drošības un beidzot ar padomiem, kā to labāk izdarīt.

Būtībā API ir saskarne, kas datus atgriež īpašā formātā, ko var saprast jebkura veida lietojumprogrammas - gan Android, gan tīmekļa lietotnes.

JSON tiek plaši izmantots, jo tas ir gandrīz visur. Otra iespēja ir izmantot XML, taču man bija problēmas ar dažu trešo pušu API (īpaši maksājumu pakalpojumu sniedzējiem, kas neatrodas manā valstī), kas izmantoja XML, izmantojot JSON, un izstrāde bija pilnīga kļūda. Es iesaku visu laiku attīstīt JSON API, ja vien kāds nepieprasa XML API.

Izstrādājot API, jums jāņem vērā dažas lietas, šajā konkrētajā secībā:

  • drošība - tā nodrošināšana, izmantojot OAuth, API atslēgu vai CORS, ir obligāta. Pēc izvēles jums vajadzētu izmantot droseļvārstu, lai ierobežotu pieprasījumus savā lietotnē.
  • galvenes - pārliecinieties, vai jūsu lietotnes sūta pareizo satura veidu. Satura tipa galvene ir nedaudz informācijas, kas klientam, kurš saņem datus, saka: “šī lieta, ko es jums sūtu, ir JSON” vai “šeit ir XML. pareizi parsēt ”, tāpēc pārlūks vai jūsu klients zina, kā to pareizi atšifrēt.
  • kodēšanas standarti un nosaukšana - tas ir tikai pamatslānis. Pārliecinieties, vai esat atbildīgs konsekventi. Pieturieties tikai pie viena nosaukšanas veida un pareiza formatējuma.

Man patīk kodēt API Laravel, jo jūs vēlaties paplašināt mērogu ar notikumu apraidi vai citām trūkstošajām Lumen funkcijām, kas to padara ātri degošu. To varat izdarīt, nepārrakstot visu projektu no nulles. Ja jūs paliksit tikai minimāls, nekautrējieties izmantot Lumen.

Drošība

Lielākā problēma, par kuru jums vajadzētu rūpēties, ir drošība. To ir viegli nodrošināt, taču, ja to nedarīsit pareizi, iespējams, iegūsit nevēlamu piekļuvi. Laravel, iespējams, vēlēsities izmantot Laravel Passport - tā pieder Laravel ekosistēmai, atbalsta autentifikāciju, izmantojot šo lietotnes ID - App Secret ir ļoti noderīga, lai iegūtu piekļuves pilnvaru, lai uzdotos kādam citam vai serverim, neatkarīgi no tā, vai tas ir aizmugures vai priekšpusē. Pamatā jūs ar savu lietotnes ID un lietotnes noslēpumu pieprasīsit OAuth beigu punktam, lai saņemtu marķieri, kuru var ģenerēt serveris (ti, piekļūt API no komandas, kura katru dienu darbojas mērķauditorijas atlasei), vai arī lietotājs, kurš ir pieteicies jūsu lietotnē.

Alternatīvi, iespējams, vēlēsities izmantot JWT Token autentifikāciju, kas darbojas gandrīz tāpat, bet varbūt to ir vieglāk saprast. Izvēlieties savu izvēli un noskaidrojiet, kurš no tiem jums ir piemērots gan ieviešanā, gan jūsu vajadzībām.

Galvenes

Web pieprasījumi ir tikai normālas sarunas starp klientu un serveri vai starp diviem serveriem. Viņi paļaujas uz pieprasījumu un atbildi, ja vien tas nav tīmekļa kabatas veida pieprasījums, bet tas ir tikai cits stāsts. Pieprasot vai nosūtot atpakaļ lietas, ir mazliet informācijas, ko sauc par galvenēm, par kurām ir jārūpējas - daži no tiem pasaka serverim, kā jāapstrādā saņemtā informācija vai kā klients vēlas saņemt atbildi.

Tas ir tāpat kā jūsu mamma jums saka: “ejiet, nopērciet pienu no veikala, bet pērciet tikai no X zīmola piena”. Jūs zināt, ko darīt, bet jums tas jāizvēlas tikai no viena piena veida. Tas ir tāds pats kā pieprasījumi: “Es vēlos iegūt lietotāju sarakstu, bet dodiet tos JSON formātā” vai “Es vēlos iegūt visus lietotājus, bet sūtīt man pa 20 gabaliem” (gadījumā, ja jūs norādāt GET parametru ). Šim nolūkam ir virsraksts ar nosaukumu Accepts, kas var būt lietojumprogramma / json, ja vēlaties, lai atbilde būtu JSON. Tas nav obligāti, taču dažām lietotnēm, piemēram, AJAX, ja tā atrod šo galveni, tā automātiski atkodē klienta atbildi, neveicot kaut ko līdzīgu:

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

Vēl viena galvene, kas jums jāzina, ir satura tips, kas ir nedaudz mulsinošs, taču tas ir pretstatā akceptēšanai: tas pasaka serverim, kā rīkoties ar saņemto saturu. Piemēram, ja vēlaties sūtīt RAW datus, piemēram, JSON virkni, jūs varat iestatīt satura tipu uz lietojumprogrammu / json, bet, ja vēlaties saņemt saturu caur mainīgo $ _POST, jums tas jāiestata uz x-www -formu-urlenkodu. Tas palīdzēs jums ne tikai parsēt saturu tieši caur $ _POST, bet arī to vajadzētu izmantot HTML formātās, jo tas ir viegli pieejams. Ja sūtāt tādus datus kā bināri, piemēram, izmantojot failu ievadi, pārliecinieties, vai esat nosūtījis satura daudzdaļīgus / formas datus.

Laravel tas nebūs problēma, jo datiem varat piekļūt tieši.

Lietojumprogrammai / json:

funkciju indekss (pieprasīt USD pieprasījumu)
{
   $ var = $ pieprasījums-> mainīgs;
}

Tomēr lietojumprogrammā / json JSON saturu nevar izmantot, izmantojot metodi -> all ().

funkciju indekss (pieprasīt USD pieprasījumu)
{
   $ dati = $ pieprasījums-> visi (); // tas ir tukšs masīvs, pat mums ir dati.
}

Ja iestatīts uz x-www-form-urlencoded vai multipart / form-data, visus mainīgos var redzēt, izmantojot -> all ().

Atbildot atpakaļ, Laravel varat izmantot iebūvēto JSON atbildi VAI varat to labāk izstrādāt un izmantot tādu pakotni kā Laravel Fractal vai Laravel Responder. Pēc manas pieredzes Laravel Responder paveica darbu labāk, semantiskā veidā. Ļaujiet man jums parādīt:

funkcija getUsers (pieprasīt USD pieprasījumu)
{
   atpakaļatbildētājs () -> veiksme (Lietotājs :: visi ()) -> atbildēt ();
}

Tas atgriezīs visus lietotājus ar statusu OK 200 un formatētu kā JSON. Forši, vai ne? Lai nerastos kļūdas, jums jādara kaut kas līdzīgs, kas ļauj nosūtīt kodu un ziņojumu:

funkcija getUsers (pieprasīt USD pieprasījumu)
{
   $ lietotāji = lietotājs :: visi ();

   if ($ lietotāju-> skaits () === 0) {
      atpakaļatbildētājs () -> kļūda ('no_users', 'Nav lietotāju.') -> respon ();
   }
   atpakaļatbildētājs () -> panākumi ($ lietotāji) -> reaģēt ();
}

Šī pakete atbalsta daudz vairāk, tāpēc dodieties uz dokumentiem, jo ​​to var viegli integrēt ar transformatoriem un nosūtītajiem pielāgotajiem datiem.

Kodēšanas standarti

Man patīk redzēt, ka cilvēki ievēro dažus standartus, kas viņiem ir piemēroti, vai arī ir tīri. Šeit ir daži padomi, kas varētu palīdzēt izveidot tīrāku kodu un labāk strukturēt API maršrutus.

API maršrutiem izmantojiet maršrutus / api.php failu

Laravel nāk ar atsevišķu maršruta / api.php failu, kas atkāpjas no parastā maršruta / web.php faila, kas tiek izmantots tīmekļa maršrutēšanai. api.php fails ir izveidots, lai saglabātu jūsu API maršrutus. Tam ir iebūvēta starpprogrammatūra (ko var redzēt lietotnē / Http / Kernel.php, mainīgajā $ middlewareGroups mainīgajā sadaļā api) un prefikss / api, tāpēc visi definētie maršruti jau ir pieejami / api

Izmantojiet maršrutu nosaukumus

Kas man patīk darīt, ir iestatīt kā iestatījumu visam API, lai es ar api varētu piekļūt maršrutiem pēc viņu nosaukuma. priedēklis.

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

Šī maršruta URL var tikt izmantots, izmantojot maršrutu ('get.users'), taču tas var būt pretrunā ar web.php.

Maršruts :: grupa (['kā' => 'api.'], Funkcija () {
   Maršruts :: get ('/ users', 'API \ UserController @ getUsers') -> name ('get.users');
});

Tādā veidā jums tas būs pieejams maršrutā ('api.get.users').

Ja izmantojat maršruta nosaukumus, rakstīšanas pārbaudēs jums nevajadzēs visur aizstāt URL, ja plānojat mainīt URL atrašanās vietu un saglabāt maršruta nosaukumu.

Aprakstoši, tomēr vienkārši maršruti

Laba prakse ir sagrupēt maršrutus sadaļās, piemēram, lietotājiem, ziņām utt., Un izmantot vienkāršākās lietas, kuras varat iedomāties:

Maršruts :: grupa (['kā' => 'api.'], Funkcija () {
   Maršruts :: grupa (['as' => 'konts.', 'Prefikss' => '/ konts'], funkcija () {
         Maršruts :: get ('/ users', 'API \ UserController @ getUsers') -> name ('get.users');
         Maršruts :: get ('/ user / {id}', 'API \ UserController @ getUser') -> name ('get.user');
         Maršruts :: pasts ('/ user', 'API \ UserController @ createUser') -> name ('create.user');
         // utt.
   });
});

Izmantojiet :: get () datu iegūšanai, :: post () izveidošanai, :: patch () vai :: put () rediģēšanai un :: delete () datu dzēšanai. Līdzīgi kā jūs izmantojat to pašu parametru, bet ar dažāda veida pieprasījumiem jūs varēsit izraisīt citas darbības.

Kontroliera iekšpusē jums vajadzētu izmantot vienkāršu kodēšanu un izmantot pieprasījumu klases, kā es paskaidroju sadaļā Laravel tālāk - labākie padomi un labā prakse Laravel 5.7

funkcija getUsers (pieprasīt USD pieprasījumu)
{
   $ lietotāji = lietotājs :: visi ();
   atpakaļatbildētājs () -> panākumi ($ lietotāji) -> reaģēt ();
}
funkcija getUser ($ id, Request $ pieprasījums)
{
   $ lietotājs = lietotājs :: findOrFail ($ id);
   atpakaļatbildētājs () -> panākumi ($ lietotājs) -> atbildēt ();
}
funkcija createUser (pieprasījums CreateUserRequest $)
{
    $ lietotājs = lietotājs :: izveidot ($ pieprasījums-> viss ());
    atpakaļatbildētājs () -> panākumi ($ lietotājs) -> atbildēt ();
}
// utt.

Pārliecinieties arī, vai visām darbībām pieturaties ar vieniem nosaukumiem, lai tos ātrāk atrastu, un ikviens var ienākt kodu bāzē un atvieglot satura uzturēšanu vai izveidi. Neizņemiet repocijā API atslēgas vai sensitīvus datus, rakstiet tīru kodu un nekautrējieties mācīties no citiem.

Pārāk grūti saprast? Sasniedz mani!

Ja jums ir vairāk jautājumu par Laravel, ja jums nepieciešama palīdzība ar jebkuru informāciju, kas saistīta ar DevOps, vai vienkārši vēlaties pateikt Paldies!, Jūs varat atrast mani vietnē Twitter @rennokki!

Pievienojieties mūsu kopienai Slack un lasiet mūsu iknedēļas Faun tēmas ⬇

Ja šī ziņa bija noderīga, lūdzu, pāris reizes noklikšķiniet uz zemāk esošās pogas , lai parādītu savu atbalstu autoram! ⬇