آموزشهونو (Hono)

درس ۶ از ۳۳، برنامه‌نویسی و علوم کامپیوتر، حدود ۳۱ دقیقه خواندن

مسیریابی در هونو

جواب کوتاه

طبق سند رسمی هونو، مسیریابی هونو انعطاف‌پذیر و ساده‌ست: هر مسیر، یه روش HTTP و یه نشانی داره، و با تابع‌هایی مثل app.get، app.post، app.put و app.delete تعریف می‌شه. app.all برای همه‌ی روش‌هاست و app.on برای چند روش یا چند نشانی. پارامتر نشانی، با دونقطه نوشته می‌شه، مثل /user/:name، و با c.req.param خونده می‌شه؛ علامت سوال آخرش، اختیاریش می‌کنه، و با یه عبارت منظم توی آکولاد، مثلا فقط عدد قبول می‌کنه. ستاره، هر چیزی رو می‌گیره. برای مرتب کردن، مسیرهای هر بخش رو توی یه نمونه‌ی جدای Hono می‌نویسید و با app.route، زیر یه نشانی، به app اصلی وصل می‌کنید؛ و basePath، یه پیشوند مشترک می‌ذاره. مهم: طبق سند رسمی، کنترل‌کننده‌ها به ترتیب ثبت اجرا می‌شن، و اولین کنترل‌کننده‌ای که جواب داد، کار رو تموم می‌کنه.

دیوار نامه‌های اداره‌ی پست

توی یه اداره‌ی پست، یه دیوار پر از خونه‌های کوچیک هست؛ هر خونه، مال یه محله. کارمند پست، هر نامه رو برمی‌داره، نشانیش رو می‌خونه، و توی خونه‌ی درست می‌ذاره. نامه‌های سفارشی، یه دسته‌ی جدا دارن، حتی اگه به یه محله برن. و نامه‌ای که نشانیش با هیچ خونه‌ای جور نیست، توی یه سبد جدا می‌ره: «نشانی پیدا نشد».

مسیریاب هونو، همین کارمنده. هر درخواست، یه نشانی داره و یه روش، مثل یه نامه با یه نوع تمبر. مسیریاب، این دو رو می‌خونه و درخواست رو به کنترل‌کننده‌ی درست می‌فرسته. توی درس قبل چند مسیر ساده ساختیم؛ این درس، کل مسیریابی هونو رو، از روی سند رسمی، باز می‌کنه.

مسیریابی یعنی چی

مسیریابی (Routing)، یعنی تعیین اینکه هر درخواست، با چه روشی و به چه نشانی‌ای، به کدوم کنترل‌کننده برسه. سند رسمی هونو، مسیریابیش رو با دو کلمه توصیف می‌کنه: انعطاف‌پذیر و ساده. و توی درس دوم دیدیم که طبق همون سند، مسیریاب‌ها، مهم‌ترین ویژگی هونوئن.

مسیر (Route)، یه جفت روش و نشانیه، به‌اضافه‌ی کنترل‌کننده‌ای که جوابش رو می‌ده. مثلا «GET /books، فهرست کتاب‌ها رو برگردون». یه API، در واقع، فهرستی از همین مسیرهاست؛ همون فهرست شش‌خطی‌ای که توی درس REST، روی کاغذ، نوشتیم.

روش و نشانی، با هم

یه نکته‌ی کلیدی که توی مثال آرش درس قبل دیدیم: یه مسیر، با روش و نشانی با هم شناخته می‌شه، نه فقط نشانی. یعنی GET /books و POST /books، دو مسیر کاملا جدان، با دو کنترل‌کننده‌ی جدا؛ یکی فهرست می‌ده، یکی کتاب تازه می‌سازه.

اگه برای یه نشانی، فقط GET تعریف کرده باشید، و یه درخواست POST به همون نشانی بیاد، هونو کنترل‌کننده‌ای پیدا نمی‌کنه و جواب «پیدا نشد» می‌ده. مثل نامه‌ی سفارشی، که حتی با نشانی درست، باید توی دسته‌ی خودش بره.

تابع هر روش

طبق سند رسمی، برای هر روش HTTP، یه تابع روی app هست؛ و مثال سند، همه رو کنار هم روی نشانی / نشون می‌ده:

  • app.get: برای خوندن.
  • app.post: برای ساختن.
  • app.put: برای جایگزینی.
  • app.delete: برای پاک کردن.
  • app.patch: برای تغییر بخشی؛ که توی درس REST دیدیم.

هر کدوم، نشانی و کنترل‌کننده می‌گیره؛ دقیقا مثل app.get که توی درس قبل نوشتیم.

app.all: همه‌ی روش‌ها

طبق سند رسمی، app.all یه مسیر برای هر روش HTTP می‌سازه. مثال سند: app.all روی /hello، که به هر روشی، GET یا POST یا هر چی، یه جواب می‌ده. این، برای جاهایی به کار میاد که روش مهم نیست؛ مثلا یه نشانی برای بررسی اینکه سرور زنده‌ست.

ولی توی یه API به سبک REST، کم پیش میاد. چون همون‌طور که توی درس REST گفتیم، روش، معنی داره: GET نباید چیزی رو عوض کنه، و DELETE باید پاک کنه. یه مسیر که به همه‌ی روش‌ها یه‌جور جواب می‌ده، معمولا نشونه‌ی یه طراحی شلخته‌ست.

app.on: چند روش

طبق سند رسمی، app.on اجازه می‌ده یه مسیر رو برای یه روش دلخواه، یا چند روش با هم، تعریف کنید. مثال سند: app.on(['PUT', 'DELETE'], '/post', ...)، که یه کنترل‌کننده برای هر دو روش PUT و DELETE به نشانی /post می‌سازه.

سند رسمی، با app.on، حتی روش‌های سفارشی رو هم نشون می‌ده؛ روش‌هایی که توی فهرست استاندارد نیستن ولی بعضی سیستم‌ها، مثل کش‌ها، به کار می‌برن. برای کارهای روزمره، تابع‌های جدای هر روش، خواناترن؛ app.on رو برای وقت‌هایی نگه دارید که واقعا یه کنترل‌کننده، برای چند روش، یه کار رو می‌کنه.

app.on: چند نشانی

app.on یه کار دیگه هم می‌کنه: طبق سند رسمی، می‌شه به جای یه نشانی، فهرستی از نشانی‌ها داد. مثال سند: یه مسیر GET برای سه نشانی /hello، /ja/hello و /en/hello، که همه یه جواب می‌دن.

این، برای وقتیه که چند نشانی، باید دقیقا یه کار رو بکنن؛ مثلا یه نشانی قدیمی که هنوز برنامه‌های قدیمی صداش می‌زنن، و یه نشانی تازه. به جای اینکه کنترل‌کننده رو دو بار بنویسید، یه بار، با دو نشانی.

ستاره: هر چیزی

طبق سند رسمی، ستاره (Wildcard) توی نشانی، یعنی «هر چیزی اینجا». مثال سند: /wild/*/card، که هم /wild/a/card رو می‌گیره، هم /wild/xyz/card رو. ستاره، یه جور جوکره: هر تیکه‌ای می‌تونه جاش بشینه.

کاربرد رایجش، مسیرهای جایگزینه؛ مثلا یه app.get('*') آخر همه‌ی مسیرها، که هر درخواستی که به هیچ مسیر دیگه‌ای نخورد رو بگیره. همون نمونه‌ای که توی راهنمای Bun ـی سند رسمی، برای فایل ایستای جایگزین، دیدیم. چند بخش بعد، می‌بینیم چرا جای این مسیر، باید آخر باشه.

پارامتر نشانی

توی درس REST دیدیم که هر کتاب، نشانی خودش رو داره، مثل /books/42. ولی نمی‌شه برای هر کتاب، یه مسیر جدا نوشت. طبق سند رسمی، پارامتر نشانی (Path Parameter) راه‌حلشه: یه دونقطه و یه اسم، توی نشانی. مثال سند: /user/:name، که هم /user/sara رو می‌گیره، هم /user/ali رو.

توی کنترل‌کننده، طبق همون سند، با c.req.param('name')، مقدارش رو می‌خونید. یعنی برای /user/sara، name برابر sara ـه. یه نکته‌ی مهم: هر چیزی که از پارامتر می‌خونید، یه متنه، حتی اگه شبیه عدد باشه؛ و ورودیه، پس باید بررسی بشه. ایستگاه چهارم، کامل یادش می‌ده.

همه‌ی پارامترها، یه‌جا

یه مسیر می‌تونه چند پارامتر داشته باشه. مثال سند رسمی: /posts/:id/comment/:comment_id، یعنی نظر شماره‌ی فلان، از پست شماره‌ی فلان. طبق همون سند، می‌تونید همه‌ی پارامترها رو یه‌جا بگیرید: c.req.param() بی اسم، یه شیء برمی‌گردونه، با id و comment_id.

این، همون منبع‌های تودرتوی درس REST ـه: /books/42/reviews/7، یعنی نظر ۷ از کتاب ۴۲. با تایپ‌اسکریپت، ویرایشگر، اسم پارامترها رو از خود نشانی می‌فهمه؛ پس اگه اسم یکیشون رو اشتباه بنویسید، پیش از اجرا خطا می‌گیرید.

پارامتر اختیاری

طبق سند رسمی، با گذاشتن یه علامت سوال آخر اسم پارامتر، اختیاریش می‌کنید. مثال سند: /api/animal/:type?، که هم /api/animal رو می‌گیره، هم /api/animal/cat رو. اگه پارامتر نیومده باشه، مقدارش خالیه؛ و کنترل‌کننده باید این حالت رو هم در نظر بگیره.

این، برای جاهایی خوبه که یه نشانی، با و بی جزئیات، یه کار مشابه می‌کنه؛ مثلا فهرست همه‌ی حیوون‌ها، یا فقط یه نوع خاص. ولی با احتیاط به کارش ببرید؛ توی سبک REST، معمولا /animals و /animals/:type، دو مسیر جدا، روشن‌ترن.

محدود کردن پارامتر با عبارت منظم

گاهی می‌خواید یه پارامتر، فقط شکل خاصی رو قبول کنه؛ مثلا فقط عدد. طبق سند رسمی، می‌تونید بعد از اسم پارامتر، یه عبارت منظم، توی آکولاد، بذارید. مثال سند: /post/:date{[0-9]+}/:title{[a-z]+}، که date فقط رقم، و title فقط حروف کوچیک انگلیسی قبول می‌کنه.

عبارت منظم (Regular Expression)، یه زبون کوچیک برای توصیف الگوی متنه؛ [0-9]+ یعنی «یه یا چند رقم». اگه نشانی با این الگو جور نباشه، اصلا با این مسیر تطبیق پیدا نمی‌کنه، و مثلا به «پیدا نشد» می‌رسه. این، یه لایه‌ی اول بررسیه؛ ولی جای بررسی کامل ورودی، که ایستگاه چهارم یاد می‌ده، رو نمی‌گیره.

پارامتری که خط مورب داره

پارامتر نشانی، به‌طور عادی، تا خط مورب بعدی رو می‌گیره؛ یعنی یه تیکه از نشانی. ولی طبق سند رسمی، با یه عبارت منظم، می‌شه پارامتری ساخت که خط مورب رو هم شامل بشه. مثال سند: /posts/:filename{.+\.png}، که هر نشانی که با png تموم بشه، با هر چند تیکه، رو می‌گیره.

این، برای کار با مسیر فایل‌ها، که خودشون پوشه‌پوشه‌ان، به کار میاد. کم پیش میاد لازمش داشته باشید؛ ولی خوبه بدونید که مسیریاب هونو، این انعطاف رو داره.

زنجیر روش‌ها روی یه نشانی

طبق سند رسمی، می‌شه چند روش رو، برای یه نشانی، پشت سر هم، زنجیر کرد. مثال سند: app.get روی /endpoint، و بلافاصله بعدش، .post و .delete، بی تکرار نشانی؛ هر کدوم با کنترل‌کننده‌ی خودش.

این شیوه، کد رو برای یه منبع، کنار هم و خوانا نگه می‌داره: همه‌ی کارهایی که روی /books/:id می‌شه کرد، یعنی خوندن، تغییر و پاک کردن، یه‌جا. بعضی‌ها این شیوه رو ترجیح می‌دن، بعضی‌ها مسیرهای جدا رو؛ هر دو یه کار می‌کنن. فقط توی یه پروژه، یکی رو ثابت نگه دارید.

API کتاب درس REST، با هونو

حالا API کتابی که توی درس REST روی کاغذ طراحی کردیم، با هونو، این شکلی می‌شه:

  • app.get('/books'): فهرست کتاب‌ها.
  • app.get('/books/:id'): یه کتاب؛ id از c.req.param.
  • app.post('/books'): کتاب تازه؛ بدنه از c.req.json، و c.status(201).
  • app.patch('/books/:id'): تغییر بخشی از یه کتاب.
  • app.delete('/books/:id'): پاک کردن؛ و کد ۲۰۴.

پنج خط تعریف، برای پنج کار؛ و هر کس REST بلد باشه، با دیدنشون، می‌فهمه API چی کار می‌کنه. داده رو، فعلا، توی یه آرایه‌ی ساده توی حافظه نگه دارید؛ ایستگاه داده، به دیتابیس می‌بردش.

گروه کردن مسیرها

وقتی API بزرگ می‌شه، گذاشتن همه‌ی مسیرها توی یه فایل، شلوغ می‌شه. طبق سند رسمی، می‌تونید مسیرها رو با یه نمونه‌ی جدای Hono گروه کنید، و با تابع route، به app اصلی اضافه‌شون کنید.

یعنی مسیرهای کتاب، توی یه app کوچیک به اسم book؛ مسیرهای کاربر، توی یه app دیگه به اسم user؛ و app اصلی، فقط این‌ها رو کنار هم می‌ذاره. هر گروه، می‌تونه توی فایل خودش باشه؛ مثل همون تقسیم کامپوننت‌ها به فایل‌های جدا، توی مسیر ری‌اکت.

مثال گروه، از سند رسمی

مثال سند رسمی: یه نمونه‌ی Hono به اسم book می‌سازید. روش، سه مسیر تعریف می‌کنید: book.get('/')، book.get('/:id') و book.post('/'). بعد، توی app اصلی، می‌نویسید app.route('/book', book).

نتیجه، طبق کامنت‌های خود سند: book.get('/') می‌شه GET /book؛ book.get('/:id') می‌شه GET /book/:id؛ و book.post('/') می‌شه POST /book. یعنی نشانی‌های داخل گروه، نسبی‌ان؛ و route، پیشوند /book رو به همه‌شون اضافه می‌کنه. اگه یه روز بخواید /book رو به /books عوض کنید، فقط یه خط عوض می‌شه.

گروه، بی تغییر نشانی پایه

طبق سند رسمی، می‌شه چند گروه رو، بی اینکه نشانی پایه عوض بشه، کنار هم گذاشت. مثال سند: گروه book، مسیرهاش رو با نشانی کامل، مثل /book، تعریف می‌کنه؛ و app اصلی، با app.route('/', book)، بی پیشوند، اضافه‌ش می‌کنه.

یعنی دو شیوه هست: یا گروه، نشانی‌های نسبی داره و route پیشوند رو می‌ده؛ یا گروه، نشانی‌های کامل داره و route با / وصلش می‌کنه. اولی، جابه‌جا کردن گروه رو ساده‌تر می‌کنه؛ دومی، با نگاه به فایل گروه، نشانی‌ها رو کامل نشون می‌ده. توی یه پروژه، یکی رو انتخاب کنید و ثابت بمونید.

basePath: پیشوند مشترک

طبق سند رسمی، با basePath، یه نشانی پایه برای یه نمونه‌ی Hono تعیین می‌کنید. مثال سند: new Hono().basePath('/api')؛ و بعد، api.get('/book')، می‌شه GET /api/book. همون سند، توی مثال گروه بی تغییر پایه هم، گروه user رو با basePath('/user') ساخته.

کاربرد رایجش، گذاشتن پیشوند /api جلوی همه‌ی مسیرهای یه API ـه؛ یا پیشوند نسخه، مثل /v1، تا اگه یه روز نسخه‌ی تازه‌ای از API ساختید، برنامه‌های قدیمی، با نسخه‌ی قدیمی، کار کنن. یادتون هست که API، یه قرارداده؛ پیشوند نسخه، راه عوض کردن قرارداد، بی شکستن برنامه‌های دیگه‌ست.

ترتیب، مهمه

یه قاعده‌ی مهم از سند رسمی: کنترل‌کننده‌ها یا میان‌افزارها، به ترتیب ثبت اجرا می‌شن. مثال سند: اول app.get('/book/a') با جواب a، و بعد app.get('/book/:slug') با جواب common. نتیجه: GET /book/a، جواب a می‌گیره؛ و GET /book/b، جواب common.

یعنی برای /book/a، هر دو مسیر جورن، چون :slug هر چیزی رو می‌گیره؛ ولی چون /book/a زودتر ثبت شده، اون برنده‌ست. این، مثل صف یه باجه‌ست: هر کی زودتر اومده، زودتر جواب می‌گیره.

اولین جواب، کار رو تموم می‌کنه

سند رسمی ادامه می‌ده: وقتی یه کنترل‌کننده اجرا شد، کار متوقف می‌شه. مثالش: اول app.get('*') با جواب common، و بعد app.get('/foo') با جواب foo. نتیجه: GET /foo، جواب common می‌گیره؛ و سند صاف می‌گه foo هیچ‌وقت اجرا نمی‌شه.

این، یه دام خیلی رایجه: یه مسیر کلی، مثل ستاره، که زودتر ثبت شده، همه‌ی درخواست‌ها رو قورت می‌ده، و مسیرهای خاص‌تر بعدی، هیچ‌وقت نوبتشون نمی‌شه. و چون خطایی هم نمی‌ده، پیدا کردنش سخته. قاعده‌ی ساده: مسیرهای خاص، بالا؛ مسیرهای کلی، پایین.

میان‌افزار، بالای کنترل‌کننده

طبق سند رسمی، اگه میان‌افزاری دارید که می‌خواید اجرا بشه، کدش رو بالای کنترل‌کننده بنویسید. مثال سند: اول app.use(logger())، یعنی یه میان‌افزار ثبت درخواست، و بعد app.get('/foo'). این‌طوری، هر درخواست به /foo، اول از ثبت‌کننده رد می‌شه.

اگه برعکس بنویسید، یعنی کنترل‌کننده اول و میان‌افزار بعد، کنترل‌کننده جواب می‌ده و کار تموم می‌شه، و میان‌افزار، برای اون مسیر، هیچ‌وقت اجرا نمی‌شه. ایستگاه سوم، که درباره‌ی میان‌افزاره، این ترتیب رو کامل به کار می‌بره.

جایگزین، پایین همه

و برعکس: طبق سند رسمی، اگه می‌خواید یه کنترل‌کننده‌ی «جایگزین» داشته باشید، که هر چیزی که مسیر دیگه‌ای نداشت رو بگیره، کدش رو زیر بقیه‌ی کنترل‌کننده‌ها بنویسید. مثال سند: اول app.get('/bar')، بعد app.get('*') با جواب fallback. نتیجه: GET /bar جواب bar می‌گیره، و GET /foo، که مسیری نداره، جواب fallback.

پس قاعده‌ی کامل ترتیب، از بالا به پایین: میان‌افزارها؛ بعد مسیرهای خاص، مثل /book/a؛ بعد مسیرهای با پارامتر، مثل /book/:slug؛ و آخر، جایگزین‌ها، مثل ستاره. اگه این ترتیب رو نگه دارید، تقریبا هیچ‌وقت به دام اولویت نمی‌افتید.

ترتیب وصل کردن گروه‌ها

سند رسمی، یه هشدار هم درباره‌ی گروه‌ها داره: اشتباه توی ترتیب گروه‌بندی، سخت دیده می‌شه. توضیحش اینه که تابع route، مسیرهای ذخیره‌شده‌ی گروه دوم رو، همون لحظه، برمی‌داره و به مسیرهای خودش اضافه می‌کنه. مثال سند: سه app، به اسم app، two و three.

اگه اول مسیر hi رو به three اضافه کنید، بعد three رو به two وصل کنید، و بعد two رو به app، درخواست GET /two/three/hi جواب hi می‌گیره. ولی اگه ترتیب رو عوض کنید، مثلا اول two رو به app وصل کنید و بعد three رو به two، طبق سند، جواب ۴۰۴ می‌گیرید. قاعده: اول گروه رو کامل کنید، بعد وصلش کنید.

وقتی هیچ مسیری جور نیست

وقتی یه درخواست، با هیچ مسیری جور نمی‌شه، هونو جواب «پیدا نشد» با کد ۴۰۴ می‌ده؛ همون که توی درس قبل دیدیم. طبق سند رسمی App، با app.notFound، می‌تونید این جواب رو عوض کنید؛ مثلا به یه JSON با یه پیام روشن، تا با بقیه‌ی جواب‌های API یه‌شکل باشه.

و یادتون باشه، طبق همون سند، notFound فقط از app اصلی، یعنی بالاترین سطح، صدا زده می‌شه؛ نه از گروه‌ها. پس جواب ۴۰۴ ـی کل API، یه جا تعریف می‌شه. ایستگاه سوم، توی درس مدیریت خطا، این جواب رو کامل می‌سازه.

اسم‌گذاری مسیرها

مسیریابی خوب، فقط فنی نیست؛ اسم‌گذاری هم هست. همون رسم‌های درس REST، اینجا قاعده‌ان: اسم منبع، جمع و انگلیسی، با حروف کوچیک؛ مثل /books، /users، /order-items. شناسه، به شکل پارامتر، بعد از اسم: /books/:id. و توی نشانی، هیچ فعلی؛ کار رو روش می‌گه.

یه چیز دیگه: اسم پارامترها رو هم معنادار بذارید. :id برای شناسه‌ی همون منبع خوبه؛ ولی وقتی دو شناسه توی یه نشانی هست، مثل /books/:bookId/reviews/:reviewId، اسم کامل، از قاطی شدن جلوگیری می‌کنه؛ مثل همون comment_id توی مثال سند رسمی.

مسیریاب، زیر کاپوت

همه‌ی این مسیرها، پشت صحنه، به یکی از مسیریاب‌هایی سپرده می‌شن که توی درس دوم، از سند رسمی، دیدیم. پیش‌فرض هونو، SmartRouter ـه، که بین RegExpRouter و TrieRouter، سریع‌ترین رو برای مسیرهای شما انتخاب می‌کنه. سند می‌گه RegExpRouter همه‌ی الگوها رو پشتیبانی نمی‌کنه، ولی TrieRouter چرا؛ پس هر الگویی که توی این درس دیدید، کار می‌کنه.

یعنی لازم نیست هیچ‌وقت نگران سرعت مسیریابی باشید؛ چه ده مسیر داشته باشید، چه صد تا. تمرکزتون رو بذارید روی اینکه مسیرها روشن، درست مرتب و قابل فهم باشن؛ سرعت، با هونوئه.

مسیریابی با نام میزبان

سند رسمی هونو، یه امکان کمتر شناخته‌شده هم داره: مسیریابی بر اساس نام میزبان (Hostname)، یعنی همون بخش اول نشانی، مثل www1.example.com. با یه تابع به اسم getPath، که موقع ساختن نمونه‌ی Hono می‌دید، تعیین می‌کنید مسیریاب، چه چیزی رو به‌عنوان مسیر ببینه؛ مثلا نام میزبان به‌اضافه‌ی نشانی.

همون سند می‌گه با همین روش، حتی می‌شه بر اساس سرآیند host، یا مثلا سرآیندی که نوع مرورگر رو می‌گه، مسیر رو عوض کرد. این، برای جاهایی به کار میاد که یه سرور، به چند دامنه جواب می‌ده. برای API های این مسیر، لازمش نداریم؛ ولی خوبه بدونید که مسیریاب هونو، فقط به نشانی محدود نیست.

کد وضعیت هر مسیر

هر مسیری که می‌نویسید، باید کد وضعیت درست برگردونه؛ همون‌طور که توی درس REST، از روی سند MDN، دیدیم. یه یادآوری کوتاه، برای پنج مسیر کتاب: GET فهرست، ۲۰۰. GET یه کتاب، ۲۰۰، یا اگه پیدا نشد، با c.notFound، ۴۰۴. POST، با c.status(201)، ۲۰۱. PATCH، ۲۰۰ با کتاب تازه. DELETE، ۲۰۴، یعنی موفق بی محتوا.

یه عادت خوب: کنار هر مسیر، یه کامنت کوتاه بنویسید، که چه کدهایی برمی‌گردونه. این، همون قرارداد API ـه، توی خود کد؛ و ایستگاه چهارم، با ابزار مستند کردن خودکار، از همین کد، یه راهنمای کامل برای برنامه‌نویس‌های دیگه می‌سازه.

تست مسیرها با app.request

با این همه مسیر، امتحان دستی با curl، کم‌کم خسته‌کننده می‌شه. یادتون هست که طبق سند رسمی App، تابع app.request، یه درخواست به app می‌فرسته، بی سرور واقعی؟ یعنی می‌شه برای هر مسیر، یه تست نوشت: «اگه GET /books/1 بزنم، کد ۲۰۰ بگیرم؛ اگه GET /books/999، کد ۴۰۴».

مخصوصا برای قاعده‌ی ترتیب، که این درس دیدیم، تست خیلی به‌دردبخوره: اگه یه روز، یکی یه مسیر ستاره رو جای اشتباه گذاشت، تست، همون لحظه، خطا می‌ده؛ پیش از اینکه کاربری ببینه. ایستگاه هفتم، کل این روش رو یاد می‌ده.

جواب کوتاه

اگه کسی پرسید «مسیریابی هونو چطوره»:

هر مسیر یه روش و یه نشانیه، با app.get، app.post، app.put، app.patch یا app.delete. پارامتر با دونقطه، مثل /books/:id، و با c.req.param خونده می‌شه؛ با علامت سوال اختیاری، با عبارت منظم توی آکولاد محدود. مسیرهای هر بخش، توی یه نمونه‌ی جدای Hono، با app.route وصل می‌شن. و ترتیب ثبت، ترتیب اجراست: اولین جواب، کار رو تموم می‌کنه.

چند باور رایج

  • «GET /books و POST /books یه مسیرن.» روش، بخشی از مسیره.
  • «پارامتر نشانی، عدده.» همیشه متنه؛ و ورودیه.
  • «ترتیب نوشتن مسیرها مهم نیست.» اولین جواب، کار رو تموم می‌کنه.
  • «عبارت منظم توی مسیر، جای بررسی ورودیه.» فقط لایه‌ی اوله.
  • «گروه رو هر وقت خواستیم وصل کنیم.» اول کامل، بعد وصل.

یه مثال

کیان، یه API برای دستور پخت‌ها ساخته بود، و برای اینکه هیچ درخواستی بی جواب نمونه، اولین خط بعد از ساختن app، یه app.get('*') گذاشته بود، با یه پیام «خوش اومدید». بعد، مسیرهای /recipes و /recipes/:id رو نوشت. ولی هر نشانی‌ای که امتحان می‌کرد، فقط همون پیام خوش‌آمد رو می‌گرفت؛ و هیچ خطایی هم نبود.

یه ساعت گشت، تا توی سند رسمی، بخش اولویت مسیر رو خوند: اولین کنترل‌کننده‌ای که جواب بده، کار رو تموم می‌کنه. ستاره رو برد آخر فایل، و همه‌ی مسیرها کار کردن. از اون روز، یه کامنت بالای فایلش داره: خاص بالا، کلی پایین.

تمرین امروز

امروز، API کتاب درس REST رو با هونو بسازید.

  1. توی پروژه‌ی my-app، یه آرایه‌ی چند کتاب، توی حافظه، بسازید.
  2. پنج مسیر GET /books، GET /books/:id، POST /books، PATCH /books/:id و DELETE /books/:id رو بنویسید.
  3. مسیرهای کتاب رو توی یه نمونه‌ی جدای Hono بذارید و با app.route('/books', ...) وصلشون کنید.
  4. پارامتر id رو با یه عبارت منظم، به فقط رقم محدود کنید؛ /books/abc رو امتحان کنید.
  5. یه app.get('*') جایگزین، یه بار بالا و یه بار پایین بذارید، و فرقش رو با curl ببینید.

درس بعدی این مسیر، Context رو کامل باز می‌کنه: خوندن بدنه، سرآیند و پرسش، و ساختن جواب.

جمع‌بندی. آنچه از این درس با خودتان می‌برید.

  • هر مسیر: روش و نشانی؛ با app.get، app.post و بقیه.
  • پارامتر با دونقطه، مثل /books/:id؛ خوندن با c.req.param.
  • اختیاری با علامت سوال؛ محدود با عبارت منظم توی آکولاد؛ ستاره برای هر چیزی.
  • گروه کردن: نمونه‌ی جدای Hono، و app.route؛ پیشوند با basePath.
  • ترتیب ثبت، ترتیب اجراست؛ اولین جواب، کار رو تموم می‌کنه.

خودتون رو بسنجید

۱۵ پرسش، هر بار تازه از میان ۳۰ پرسش این درس. آخرش فقط کارنامه رو می‌بینید: چند تا درست، چند تا نادرست.

خودتون رو بسنجید

۱۵ پرسش

  • هر بار پرسش‌ها و ترتیب گزینه‌ها عوض می‌شه.
  • تا آخر نمی‌گیم کدوم جواب درست بوده؛ می‌تونید برگردید و جوابتون رو عوض کنید.
  • آخرش کارنامه می‌گیرید: چند تا درست، چند تا نادرست.
  • اگه وسطش بستید، دوباره که باز کنید از همون‌جا ادامه می‌دید.

فصل‌های این درس