Էջերի դասակարգում

Էջավորումը կարող է լինել խաբուսիկորեն բարդ թեմա։ Հեշտ է ընկնել թակարդների մեջ և չհետևել լավագույն պրակտիկաներին։ Այս էջը կօգնի ձեզ ճիշտ անել էջավորումը։ Այսինքն, եթե կարդաք և հասկանաք այս էջը, կարծում ենք՝ ձեր հաճախորդը կլինի ավելի դիմացկուն և ապագայի համար ապահովագրված, և ձեր կյանքը կհեշտանա հետագայում։

Եթե այս ուղեցույցից միայն մեկ բան հիշեք, դա պետք է լինի այն, որ չպետք է ինքնուրույն կազմեք ձեր էջավորման URL-ները։

JSON:API մոդուլի յուրաքանչյուր էջավորված պատասխանում արդեն կա հղում դեպի հավաքածուի հաջորդ էջը, որը կարող եք օգտագործել։ Պետք է հետևեք այդ հղմանը։

Այս փաստաթղթի սկզբում մենք կուսումնասիրենք API-ի կարևոր առանձնահատկությունները և ինչպես ճիշտ իրականացնել էջավորումը։ Փաստաթղթի վերջում կգտնեք պատասխաններ հաճախ տրվող հարցերի և թակարդների մասին։

Ինչպե՞ս

JSON:API մոդուլի յուրաքանչյուր էջավորված պատասխանում անմիջապես ընդգրկված են էջավորման հղումները։ Եկեք դիտենք մի փոքր օրինակ՝

{
  "data": [
    {"type": "sample--type", "id": "abcd-uuid-here"},
    {"type": "sample--type", "id": "efgh-uuid-here"}
  ],
  "links": {
    "self": "<collection_url>?page[offset]=3&page[limit]=3",
    "next": "<collection_url>?page[offset]=6&page[limit]=3",
    "prev": "<collection_url>?page[offset]=0&page[limit]=3"
  }
}

Արեք մի քանի նկատառում՝

• links բանալիի տակ կա 3 էջավորման հղում՝
  • self: սա ներկայիս էջի URL-ն է։
  • next: սա հաջորդ էջի URL-ն է։
  • prev: սա նախորդ էջի URL-ն է։
• Կա page[limit] արժեքով 3, բայց միայն 2 ռեսուրս (?!).

Էջավորման հղումների առկայությունն կամ բացակայությունը շատ կարևոր է։ Պետք է իմանաք՝

1. Եթե next հղումը գոյություն ունի, կան հավելյալ էջեր։
2. Եթե next հղումը չկա, դուք գտնվում եք վերջին էջում։
3. Եթե prev հղումը գոյություն ունի, դուք առաջին էջում չեք։
4. Եթե next և prev հղումները գոյություն չունեն, միայն մեկ էջ կա։

Չնայած էջի սահմանաչափը 3 է, կա միայն 2 ռեսուրս։ Դա այն պատճառով է, որ որոշ էակներ անվտանգության նկատառումներով հեռացվել են։ Կարող ենք համոզվել, որ պատճառը դա է, այլ ոչ թե ռեսուրսների անբավարարությունը, քանի որ տեսնում ենք next հղումը։ Եթե ցանկանում եք ավելին իմանալ այս մասին, ավելին բացատրվում է ստորև։

Լավ, հիմա, երբ որոշ կարևոր փաստեր պարզեցինք, մտածենք՝ ինչպես պետք է կառուցենք մեր հաճախորդային կոդը։ Կտեսնենք պարզեցված JavaScript օրինակ։ 🧐

Պատկերացրեք, որ ցանկանում եք ցուցադրել կայքի ամենանոր բովանդակությունը, և ունենք որոշ «պրեմիում» բովանդակություն, որը կարող են դիտել միայն վճարովի բաժանորդները։ Եվ ուզում եք «վերին 5»-ի կոմպոնենտ, սակայն եթե կա ավելի շատ բովանդակություն, օգտվողը պետք է կարողանա սեղմել «հաջորդ էջ» հղումը, որպեսզի տեսնի հաջորդ 5 նորագույն բովանդակությունը։

Պարզունակ իրագործումը կարող է այսպիսին լինել՝

const baseUrl = 'http://example.com';
const path = '/jsonapi/node/content';
const pager = 'page[limit]=5';
const filter = `filter[field_premium][value]=${user.isSubscriber()}`;

fetch(`${baseUrl}${path}?${pager}&${filter}`)
  .then(resp => {
    return resp.ok ? resp.json() : Promise.reject(resp.statusText);
  })
  .then(document => listComponent.setContent(document.data))
  .catch(console.log);

Սակայն, նույնիսկ անտեսելով սխալների վատ կառավարումը, արդեն գիտենք, որ սա կայուն իրագործում չէ։

Ինչպես տեսանք վերևում, չենք կարող վստահ լինել, որ պատասխանում կլինի 5 տարր։ Եթե դրանցից 2-ը անհասանելի են (օրինակ՝ չհրապարակված են), ապա մեր «վերին 5»-ի կոմպոնենտում կլինի միայն 3 տարր։

Կա նաև ավելորդ filter։ Սերվերը արդեն պետք է հեռացնի այն բովանդակությունը, որն օգտվողին հասանելի չէ։ Եթե ոչ, ապա մեր հավելվածում կարող է լինել մուտքի շրջանցման ռիսկ, քանի որ չարամիտ օգտվողը կարող է հեշտությամբ փոխել հարցումը և տեսնել «պրեմիում» բովանդակությունը։ Միշտ համոզվեք, որ մուտքի վերահսկողությունը կատարվում է սերվերի վրա. մի վստահեք հարցումներին, որ դրանք կանեն ձեր փոխարեն։

Ահա՝ ինչպես պետք է լինի՝

const listQuota = 5;
const content = [];
const baseUrl = 'http://example.com';
const path = '/jsonapi/node/content';
const pager = `page[limit]=${listQuota}`;

const getAndSetContent = (link) => {
  fetch(link)
  .then(resp => {
    return resp.ok ? resp.json() : Promise.reject(resp.statusText);
  })
  .then(document => {
    content.push(...document.data);
    listContent.setContent(content.slice(0, listQuota));

    const hasNextPage = document.links.hasOwnProperty("next");
    if (content.length <= listQuota && hasNextPage) {
      getAndSetContent(document.links.next);
    }

    if (content.length > listQuota || hasNextPage) {
      const nextPageLink = hasNextPage
        ? document.links.next
        : null;
      listComponent.showNextPageLink(nextPageLink);
    }
  })
  .catch(console.log);
}

getAndSetContent(`${baseUrl}${path}?${pager}`)

Առաջին հերթին, նկատեք, որ filter-ը բացակայում է։ Դա այն պատճառով է, որ ենթադրում ենք, որ մուտքի ստուգումները կատարվում են սերվերի կողմից, այլ ոչ թե filter-ի։ Սա միակ ապահով տարբերակն է։ Կարող էինք այն ավելացնել որպես արտադրողականության օպտիմալացում, սակայն հավանաբար դա անհրաժեշտ չէ։

Այնուհետև, քանի որ գիտենք, որ սերվերը պարզապես հանում է այն ռեսուրսները, որոնք օգտվողի համար հասանելի չեն, մենք իրոք պետք է ստուգենք՝ քանի ռեսուրս կա իրականում պատասխանում։

«Պարզունակ» իրագործման մեջ ենթադրում էինք, որ յուրաքանչյուր պատասխանում կլինի 5 տարր։ Այս օրինակում սահմանում ենք «քվոտա»՝ 5 ռեսուրսի համար։ Հարցումներից հետո ստուգում ենք՝ արդյոք հասել ենք քվոտային, թե ոչ։ Նաև ստուգում ենք՝ արդյոք սերվերը դեռ ունի հավելյալ էջեր (կիմանանք, եթե կա next հղում)։

Եթե չենք հասել քվոտային և դեռ չենք վերջին էջում, նոր հարցում ենք անում՝ օգտագործելով next հղումը, որը վերցրել ենք փաստաթղթից։ Կարևոր է նկատել, որ մենք չենք կառուցել նոր URL ձեռքով հաջորդ էջի համար։ Պարզապես պետք չէ հեծանիվ հայտնագործել, քանի որ JSON:API սերվերը դա արդեն արել է մեզ համար։

Մեկ այլ հետաքրքիր բան․ քանի որ fetch-ը ասինքրոն է, կարող ենք առաջին հարցման պարունակությունը ավելացնել մեր կոմպոնենտում դեռ մինչև բոլոր հարցումների ավարտը։ Երբ երկրորդ հարցումն ավարտվի, պարզապես նորից թարմացնում ենք կոմպոնենտը՝ ավելացնելով նոր արդյունքները։

Վերջում, ապահովում ենք, որ մեր երևակայական listComponent-ը իմանա՝ ցույց տալ «հաջորդ էջ» հղումը, թե ոչ։ Այն պետք է ցույց տա հղումը միայն եթե արդեն ունենք լրացուցիչ բովանդակություն կամ սերվերը ունի լրացուցիչ էջեր։

Առաջին դեպքը կարող է լինել, եթե առաջին հարցման մեջ ստանում ենք միայն 4 տարր, երկրորդում՝ 5, բայց չկա next հղում։ Այդ դեպքում կունենանք ընդհանուր 9 տարր, սակայն մեր listComponent-ը ցույց կտա միայն առաջին 5-ը։ Ուստի մենք դեռ ցանկանում ենք ցույց տալ «հաջորդ էջ» հղումը, բայց չենք ուզում, որ կոմպոնենտը անի լրացուցիչ հարցումներ։ Դրա համար nextPageLink-ը դնում ենք null։

Երկրորդ դեպքում՝ երբ կան next հղումներ, մենք փոխանցում ենք այդ հղումը կոմպոնենտին, որպեսզի վերջինս կարողանա այն օգտագործել հաջորդ հարցման համար։ Չենք ուզում այդ հարցումն անել, եթե օգտվողը երբեք չի սեղմում «հաջորդ էջ» հղումը, չէ՞։

Վերջին պարբերությունները շատ կարևոր գաղափար են ցույց տալիս... «Հաջորդ էջ» հղումները ձեր HTML-ում պարտադիր չէ, որ համընկնեն API-ի էջերի հետ։ Իրականում, եթե համընկնում են, դա կարող է ցույց տալ, որ դուք սխալ եք անում։

Ինչո՞ւ ... ?

... չեմ կարող էջի սահմանաչափը սահմանել 50-ից մեծ արժեքով?

Նախ, կարդացեք վերը տրված օրինակը։ Հասկացեք, որ JSON:API-ն պետք է յուրաքանչյուր էակի համար առանձին մուտքի ստուգում կատարի։ Երկրորդ, իմացեք, որ JSON:API մոդուլը փորձում է լինել «զրոյական կարգավորման»։ Չպետք է որևէ բան տեղադրեք կամ կարգավորեք մոդուլն օգտագործելու համար։

Սրա պատճառը ձեր հավելվածը DDoS հարձակմանից պաշտպանելն է։ Եթե չարամիտ API հաճախորդը սահմաներ էջի սահմանաչափ 200,000 ռեսուրս, JSON:API մոդուլը ստիպված կլիներ յուրաքանչյուրի համար մուտքի ստուգում անել։ Սա արագ կհանգեցներ հիշողության սպառման և դանդաղ պատասխանների։ Սերվերը պետք է սահմանի առավելագույնը։ 50-ը ընտրվել է որպես կլոր թիվ։

Խնդրում ենք հասկանալ, որ այս որոշման շուրջ եղել են երկար քննարկումներ, և անհրաժեշտ է եղել գտնել հավասարակշռություն՝ սպասարկման բեռի, ողջամիտ լռելյայնների և frontend-ի արտադրողականության միջև։ Չնայած JSON:API մոդուլի պահպանողները հասկանում են, որ սա իդեալական չէ բոլոր դեպքերի համար, վստահ են, որ եթե ձեր հաճախորդը հետևի այս փաստաթղթում տրված խորհուրդներին, դա պետք է ձեզ վրա քիչ կամ ընդհանրապես ազդեցություն չունենա։

Եթե դեռ ցանկանում եք ավելի բարձր սահմանաչափ, կարող եք օգտագործել JSON:API Page Limit մոդուլը։

... ինչու՞ պատասխանում չկա X ռեսուրսի քանակը, եթե հարցման մեջ նշել եմ այդ սահմանը

JSON:API մոդուլը թույլ է տալիս նշել էջի սահմանաչափը, ինչը հաճախ շփոթում է՝ կարծելով, որ այդքան ռեսուրս պարտադիր կլինի պատասխանում։ Օրինակ՝ կարող եք իմանալ, որ բավականաչափ ռեսուրսներ կան, որպեսզի «լցնեն» պատասխանը, բայց պատասխանում չկա այնքան ռեսուրս, որքան սպասում էիք։

Վերը նշվածների նման պատճառներով, JSON:API-ն տվյալների բազայում հարցում է կատարում միայն page[limit] հարցման պարամետրով նշված տարրերի համար։ Դա պարզապես առավելագույնն է։ Եթե հարցման արդյունքի որոշ ռեսուրսների մուտքը արգելված է, դրանք հանվում են պատասխանից։ Այդ դեպքում կտեսնեք ավելի քիչ ռեսուրս, քան սպասում էիք։

Սա շատ սովորական է, երբ հարցում եք կատարում էակների նկատմամբ, որոնք կարող են չհրապարակված լինել (օրինակ՝ node-եր), և այդ էակները դեռ չեն զտվել filter պարամետրով։

Հոդվածը վերցված է Drupal փաստաթղթերից։