Node.js REST API-larini yozish uchun 10 ta eng yaxshi amaliyot

Ushbu maqolada biz Node.js REST API-larini yozish bo'yicha eng yaxshi amaliyotlarni, shu jumladan yo'nalishlaringizni nomlash, autentifikatsiya, qora qutini sinovdan o'tkazish va ushbu manbalar uchun tegishli kesh sarlavhalarini ishlatish kabi mavzularni qamrab olamiz.

Node.js uchun eng mashhur foydalanish holatlaridan biri bu RESTful API-larni yozib yozishdir. Shunday bo'lsa-da, mijozlarimizga Trace-da o'zlarining ilovalarida muammolarni topishda yordam beradigan bo'lsak, bizning Node.js kuzatuv vositamiz, biz ishlab chiquvchilar REST API-larida juda ko'p muammolarga duch kelmoqdamiz.

RisingStack-da foydalanadigan eng yaxshi tajribalar sizga yordam berishi mumkin deb umid qilaman:

# 1: HTTP usullari va API marshrutlaridan foydalaning

Tasavvur qiling-a, siz Node.js RESTful API-ni foydalanuvchilarni yaratish, yangilash, olish yoki yo'q qilish uchun yaratmoqdasiz. Ushbu operatsiyalarni bajarish uchun HTTP allaqachon tegishli asboblar to'plamiga ega: POST, PUT, GET, PATCH yoki DELETE.

Eng yaxshi tajriba sifatida, sizning API yo'nalishlaringiz har doim nomlarni resurs identifikatorlari sifatida ishlatishi kerak. Foydalanuvchi resurslari haqida gap ketganda, marshrutlash quyidagicha ko'rinishi mumkin:

  • Yangi foydalanuvchi yaratish uchun POST / foydalanuvchi yoki PUT / foydalanuvchi: / id,
  • Foydalanuvchilar ro'yxatini olish uchun GET / foydalanuvchi,
  • Foydalanuvchini olish uchun GET / user /: id,
  • Mavjud foydalanuvchi yozuvini o'zgartirish uchun PATCH / user /: id,
  • Foydalanuvchini o'chirish uchun DELETE / user /: id.

# 2: HTTP holat kodlaridan to'g'ri foydalaning

Agar so'rovni bajarishda biror narsa noto'g'ri bo'lsa, buning uchun to'g'ri status kodini kiritishingiz kerak:

  • 2xx, agar hammasi yaxshi bo'lsa,
  • 3xx, agar manba boshqa joyga ko'chirilgan bo'lsa,
  • 4xx, agar mijoz xatosi sababli so'rov bajarilmasa (masalan, mavjud bo'lmagan manbani so'rash),
  • 5xx, agar API tomonida biron bir narsa noto'g'ri bo'lsa (istisno ro'y bergan kabi).

Agar siz Express-dan foydalanayotgan bo'lsangiz, status kodini sozlash res.status (500) .send kabi osondir ({error: 'Ichki serverda xatolik yuz berdi'}). Xuddi shunday Restify: res.status (201) da.

To'liq ro'yxat uchun HTTP holat kodlari ro'yxatini tekshiring

# 3: Metadata yuborish uchun HTTP sarlavhalaridan foydalaning

Siz yubormoqchi bo'lgan yuk hajmi haqida metadata qo'shish uchun HTTP sarlavhalaridan foydalaning. Ushbu kabi sarlavhalar quyidagilar haqida ma'lumot bo'lishi mumkin.

  • sahifani joylashtirish,
  • stavka cheklovi,
  • yoki autentifikatsiya.

HTTP standartlashtirilgan sarlavhalar ro'yxati bilan bu erda tanishishingiz mumkin.

Agar sarlavhalaringizda biron bir metadata o'rnatishingiz kerak bo'lsa, ularni X bilan qo'shib qo'yish eng yaxshi usul edi. Masalan, agar siz CSRF tokenlaridan foydalanayotgan bo'lsangiz, ularni X-Csrf deb nomlashning odatiy (lekin nostandart) usuli edi. -Token. Ammo RFC 6648 bilan ular eskirgan. Yangi API-lar boshqa dasturlarga zid kelishi mumkin bo'lgan nom nomlaridan foydalanmaslik uchun barcha kuchlarini sarflashlari kerak. Masalan, OpenStack sarlavhalarini OpenStack-ga qo'shadi:

OpenStack-Identity-Account-ID
OpenStack-Networking-Xost-ism
OpenStack-Object-Storage-Policy

E'tibor bering, HTTP standarti sarlavhalarda biron bir o'lchov chegarasini belgilamaydi; ammo, Node.js (ushbu maqolani yozish paytida) amaliy sabablarga ko'ra sarlavhalar ob'ektiga 80KB o'lchamdagi cheklov qo'yadi.

"HTTP sarlavhalarining (shu jumladan holat qatori) umumiy hajmining HTTP_MAX_HEADER_SIZE dan oshishiga yo'l qo'ymang. "Tekshirish bu erda joylashtiruvchilarni xizmatni rad etish hujumlaridan himoya qilish uchun qilingan, bu erda buzg'unchi bizga buferni bufer qilishni davom ettiradigan hech qachon tugamaydigan sarlavha bilan ta'minlaydi."
Node.js HTTP tahlil qiluvchisidan

# 4: Node.js REST API uchun to'g'ri ramkani tanlang

Sizning foydalanishingiz uchun mos keladigan ramkani tanlash juda muhimdir.

Express, Koa yoki Hapi

Express, Koa va Hapi brauzer dasturlarini yaratishda ishlatilishi mumkin va shu tariqa ular shablon va ko'rsatishni qo'llab-quvvatlaydi - atigi bir necha xususiyatlarni nomlash uchun. Agar sizning ilovangiz foydalanuvchi tomonini ham ko'rsatishi kerak bo'lsa, ularga murojaat qilish mantiqiy.

Qayta tiklash

Boshqa tomondan, Restify sizning e'tiboringizga REST xizmatlarini yaratishda yordam beradi. Bu sizga "qat'iy" API xizmatlarini yaratishga imkon beradigan va saqlanadigan. Restify shuningdek, barcha ishlov beruvchilaringiz uchun avtomatik DTrace-ni qo'llab-quvvatlash bilan birga keladi.

Restify npm yoki Netflix kabi yirik dasturlarda ishlab chiqarishda qo'llaniladi.

# 5: Sizning Node.js REST API-laringizni sinovdan o'tkazing

REST API-laringizni sinab ko'rishning eng yaxshi usullaridan biri bu qora qutilarga o'xshab qarashdir.

Qora quti sinovi - bu sinov usuli bo'lib, unda dasturning funktsional imkoniyatlari uning ichki tuzilmalari va ishlanmalarisiz tekshiriladi. Shunday qilib, qaramliklarning hech biri masxara qilinmaydi yoki qoqilmaydi, lekin tizim umuman sinovdan o'tkaziladi.

Node.js REST API-larini sinovdan o'tkazishda sizga yordam beradigan modullardan biri bu eng zo'r.

Oddiy sinov holati, foydalanuvchi sinov usulidagi mocha yordamida foydalanuvchi tomonidan qaytarilganligini tekshiradi, quyidagicha bajarilishi mumkin:

const request = required ('supertest')
 
tasvirlash ('GET / foydalanuvchi /: id', funktsiya () {
  u ('foydalanuvchini qaytaradi', funktsiya () {
    // yangi mocha versiyalari ham va'dalarni qabul qiladi
    qaytish so'rovi (ilova)
      .get ('/ user')
      .set ('Qabul qilish', 'dastur / json')
      .expect (200, {
        id: '1',
        nomi: "Jon Math"
      }, bajarildi)
  })
})

Siz so'rashingiz mumkin: ma'lumotlar REST API-ni xizmat ko'rsatadigan ma'lumotlar bazasiga qanday joylashadi?

Umuman olganda, testlaringizni tizimning holati haqida iloji boricha kamroq taxminlar qiladigan tarzda yozish yaxshi yondashuv. Shunday bo'lsa-da, ba'zi stsenariylarda siz tizimning holatini aniq bilishingiz kerak bo'lgan joyda o'zingizni topishingiz mumkin, shunda siz o'zingizni tasdiqlashingiz va yuqori sinov qamroviga erishishingiz mumkin.

Shunday qilib, sizning ehtiyojlaringizga qarab, ma'lumotlar bazasini quyidagi yo'llar bilan test ma'lumotlari bilan to'ldirishingiz mumkin:

  • ishlab chiqarish ma'lumotlari to'plamida qora quti sinov stsenariylarini ishga tushiring,
  • Sinov ishlari boshlanishidan oldin ma'lumotlar bazasini tayyorlangan ma'lumotlar bilan to'ldiring.

Albatta, qora qutini sinovdan o'tkazish bu birlik sinovini o'tkazish shart emas degani emas, siz hali ham API uchun birlik testlarini yozishingiz kerak.

# 6: JWT-ga asoslangan holda, fuqaroligi bo'lmagan autentifikatsiyani bajaring

Sizning REST API-laringiz fuqaroligi bo'lmasligi kerak, shuning uchun sizning autentifikatsiya qatlamingiz. Buning uchun JWT (JSON Web Token) juda mos keladi.

JWT uch qismdan iborat:

  • Token turi va xesh algoritmini o'z ichiga olgan sarlavha
  • Da'volarni o'z ichiga olgan yuk
  • Imzo (JWT yuk yukini shifrlamaydi, shunchaki imzolang!)

Arizangizga JWT-ga asoslangan autentifikatsiyani qo'shish juda oson:

const koa = zarur ('koa')
const jwt = zarur ('koa-jwt')
const app = koa ()
app.use (jwt ({
  sir: "juda maxfiy"
}))
// Himoyalangan o'rta dastur
app.use (funktsiya * () {
  // tokenning mazmuni this.state.user-da mavjud bo'ladi
  this.body = {
    sir: '42'
  }
})

Shundan so'ng, API so'nggi nuqtalari JWT bilan himoyalangan. Himoyalangan so'nggi nuqtalarga kirish uchun siz avtorizatsiya sarlavhasi maydonida tokenni taqdim etishingiz kerak.

curl --header "Avtorizatsiya: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwI
iwibmFtZSI6IkpvaG4gRG9lIiwiYWRtaW4iOnRydWV9.TJVA95OrM7E2cBab30
RMHrHDcEfxjoYZgeFONFh7HgQ "my-website.com

Bir narsani payqashingiz mumkinki, JWT moduli ma'lumotlar bazasi qatlamiga bog'liq emas. Bu shunday, chunki JWT tokenlarining barchasi mustaqil ravishda tekshirilishi mumkin va ularda jonli qadriyatlar uchun vaqt ham bo'lishi mumkin.

Bundan tashqari, har doim sizning barcha API so'nggi nuqtalariga faqat HTTPS-dan foydalanib xavfsiz ulanish orqali kirishga ishonch hosil qilishingiz kerak.

Oldingi maqolada biz veb-autentifikatsiya usullarini batafsil bayon qildik - men buni tekshirishni maslahat beraman!

№ 7: Shartli so'rovlardan foydalaning

Shartli so'rovlar bu HTTP sarlavhalariga qarab har xil bajariladigan HTTP so'rovlari. Ushbu sarlavhalarni old shartlar deb hisoblashingiz mumkin: agar ular bajarilsa, so'rovlar boshqacha tarzda amalga oshiriladi.

Ushbu sarlavhalar serverda saqlangan manbaning bir xil manbaning berilgan versiyasiga mos kelishini tekshirishga harakat qiladi. Shuning uchun ushbu sarlavhalar quyidagilar bo'lishi mumkin:

  • oxirgi modifikatsiyaning vaqt belgisi,
  • yoki har bir versiyada farq qiladigan ob'ekt yorlig'i.

Ushbu sarlavhalar:

  • So'nggi o'zgartirilgan (manba qachon oxirgi o'zgartirilganligini ko'rsatish uchun),
  • Etag (tashkilot yorlig'ini ko'rsatish uchun),
  • If-Modified-since (So'nggi o'zgartirilgan sarlavhada ishlatiladi),
  • If-None-Match (Etag sarlavhasi bilan foydalaniladi),

Bir misolni ko'rib chiqaylik!

Quyidagi mijozda doc manbasining oldingi versiyalari mavjud emas, shuning uchun manba yuborilganda na-Modified-beri va na-None-Match sarlavhasi qo'llanilmadi. Keyin, server to'g'ri o'rnatilgan Etag va Last Modified sarlavhalari bilan javob beradi.

MDN shartli so'rov hujjatlaridan

Mijoz bir xil manba so'rashga harakat qilganida, agar-Modified-beri va If-None-Match sarlavhalarini o'rnatishi mumkin - chunki hozirda uning versiyasi mavjud. Agar javob bir xil bo'lsa, server shunchaki 304 - Modified holatiga javob beradi va manbani qayta jo'natmaydi.

MDN shartli so'rov hujjatlaridan

# 8: Qabul qilish stavkasini cheklash

Stavkalarni cheklash bu iste'molchi API-ga qancha so'rov yuborishini boshqarish uchun ishlatiladi.

API foydalanuvchilariga qancha so'rov qoldirganliklarini aytish uchun quyidagi sarlavhalarni o'rnating:

  • X-Rate-Limit-Limit, ma'lum vaqt oralig'ida ruxsat etilgan so'rovlar soni
  • X-Rate-Limit-qoldiq, bir xil intervalda qolgan so'rovlar soni,
  • X-Rate-Limit-Reset, stavka limiti qayta tiklanadigan vaqt.

Ko'pgina HTTP ramkalari uni qutidan tashqarida qo'llab-quvvatlaydi (yoki plaginlari bilan). Misol uchun, agar siz Koa foydalanayotgan bo'lsangiz, koa-ratelimit to'plami mavjud.

Shuni esda tutingki, vaqt oynasi turli xil API provayderlariga qarab farq qilishi mumkin - masalan, GitHub buning uchun bir soat, Twitter 15 daqiqa vaqt sarflaydi.

# 9: To'g'ri API hujjatini yarating

Boshqalar siz ulardan foydalanishi uchun, ulardan foyda olishlari uchun APIlarni yozasiz. Node.js REST API uchun API hujjat bilan ta'minlash juda muhimdir.

Quyidagi ochiq manbali loyihalar API uchun hujjatlar yaratishda sizga yordam berishi mumkin:

  • API Blueprint
  • Qaldirg'och

Shu bilan bir qatorda, agar siz mezbonlik qiladigan mahsulotlardan foydalanmoqchi bo'lsangiz, siz Apiary-ga borishingiz mumkin.

# 10: API-larning kelajagini o'tkazib yubormang

So'nggi yillarda API uchun ikkita asosiy so'rovlar paydo bo'ldi - Facebookdan GraphQL va Netflix-dan Falcor. Ammo nega biz ularga muhtojmiz?

Quyidagi RESTful manba so'rovini tasavvur qiling:

/ org / 1 / space / 2 / docs / 1 / birgalikda ishlaysizmi?
o'z ichiga = elektron pochta va sahifa = 1 va chegara = 10

Bu osonlikcha qo'lingizdan chiqib ketishi mumkin - chunki siz har doim barcha modellaringiz uchun bir xil javob formatini olishni xohlaysiz. Bu erda GraphQL va Falcor yordam berishi mumkin.

GraphQL haqida

GraphQL - bu API uchun so'rovlar tili va mavjud ma'lumotlar bilan ushbu so'rovlarni bajarish uchun ish vaqti. GraphQL sizning API-dagi ma'lumotlarning to'liq va tushunarli tavsifini beradi, mijozlarga aniq nima kerakligini so'rash imkoniyatini beradi va boshqa hech narsa talab qilmaydi, vaqt o'tishi bilan API rivojlanishini osonlashtiradi va ishlab chiquvchilarning kuchli vositalarini yoqadi. - Bu erda ko'proq o'qing.

Falcor haqida

Falcor - bu Netflix UI-larni quvvatlaydigan innovatsion ma'lumotlar platformasi. Falcor sizning barcha tugallangan ma'lumotlaringizni Node serveringizda bitta Virtual JSON ob'ekti sifatida modellashtirishga imkon beradi. Mijozda siz masofaviy JSON ob'ekti bilan tanishish, sozlash va qo'ng'iroq qilish kabi tanish JavaScript operatsiyalaridan foydalangan holda ishlaysiz. Agar o'z ma'lumotlaringizni bilsangiz, o'zingizning API-ni bilasiz. - Bu erda ko'proq o'qing.

Ilhom uchun ajoyib REST APIlari

Agar siz Node.js REST API-ni ishlab chiqmoqchi yoki eski versiyasining yangi versiyasini yaratmoqchi bo'lsangiz, biz tekshirib ko'rishga arziydigan to'rtta haqiqiy hayot namunalarini to'pladik:

  • GitHub API
  • Twilio API
  • Stripe API
  • DigitalOcean API

Umid qilamanki, endi siz Node.js.-dan foydalanib qanday API yozilishi kerakligini yaxshiroq tushunasiz. Agar biron bir narsani o'tkazib yuborsangiz, iltimos, menga izohlarda xabar bering!

Dastlab blog.risingstack.com saytida 2017 yil 21 fevralda e'lon qilingan.