‏راهنمای مهاجرت از H3 نسخه ۱ به ۲

تیم H3 (یه فریم‌ورک سبک HTTP برای جاوااسکریپت) برای نسخه ۲ یه راهنمای مهاجرت نوشته. نسخه ۲ هنوز بتاست و از کانال nightly قابل تست‌ه. خودشون هم می‌گن این راهنما ممکنه باز تغییر کنه. نسخه جدید فقط ESM هست و Node.js 20.19 به بالا می‌خواد. اگه پروژه‌ت CommonJS باشه، هنوز می‌تونی require("h3") بنویسی، چون نسخه‌های جدید Node از require(esm) پشتیبانی می‌کنن. Bun و Deno هم جواب می‌دن.

بزرگ‌ترین تغییر اینه که H3 از پایه روی اشیای استاندارد وب (URL، Headers، Request و Response) بازنویسی شده. روی Node یه لایه سازگاری به اسم srvx کار رو انجام می‌ده و روی بقیه runtimeها از APIهای خود وب استفاده می‌شه. event.web اسمش شده event.req و دسترسی به event.node.{req,res} فقط وقتی روی Node اجرا می‌کنی هست.

توابع send کنار رفتن و حالا همیشه باید جواب رو return کنی یا خطا رو throw کنی. مثلاً send(event, value) می‌شه return value، sendStream جاشو به برگردوندن مستقیم stream داده و sendNoContent هم می‌شه return noContent(). H3 خودش تشخیص می‌ده چیزی که برگردوندی متن‌ه، JSON‌ه، stream‌ه یا یه Response کامل.

روتر حالا بخشی از هسته H3 شده و به‌جای createApp() و createRouter() فقط new H3() می‌نویسی. موتور تطبیق مسیرها هم عوض شده و رفته روی rou3، پس ممکنه رفتار بعضی الگوها یه کم فرق کنه. یه نکته مهم: middlewareای که با app.use("/path", handler) اضافه می‌کنی دیگه فقط خود /path رو می‌گیره، نه زیرمسیرهاشو. برای رفتار قبلی باید /path/** بنویسی. امضای router.add هم عوض شده و حالا اول method می‌گیره بعد path.

برای خوندن body هم بیشتر وقت‌ها می‌تونی از متدهای خود وب مثل event.req.json() و event.req.formData() استفاده کنی. اگه درخواست body نداشته باشه، دیگه خطا نمی‌ده و مقدار خالی برمی‌گردونه. چون دیگه از destr استفاده نمی‌شه، تیم H3 تأکید می‌کنه که داده ورودی کاربر رو خودت فیلتر کنی تا جلوی prototype poisoning (یعنی دستکاری prototype اشیا از طریق JSON ورودی) گرفته بشه. مقدار هدرها هم حالا همیشه یه string ساده‌ست.

یه تغییر امنیتی هم هست: getRequestProtocol و getRequestURL دیگه به‌صورت پیش‌فرض به هدر x-forwarded-proto اعتماد نمی‌کنن. اگه اپت پشت یه سرور واسط یا CDN مطمئن اجرا می‌شه، باید با { xForwardedProto: true } روشنش کنی. کلی ابزار دیگه هم اسمشون عوض شده؛ مثلاً createError شده HTTPError و defineEventHandler شده defineHandler.

نکات کلیدی:

• H3 v2 فقط ESM هست و Node.js 20.19 به بالا می‌خواد.
• کل فریم‌ورک روی Request، Response، Headers و URL استاندارد وب بازنویسی شده.
• همه توابع send* حذف شدن و جواب باید با return برگرده.
• createApp و createRouter جاشونو به new H3() دادن.
• app.use("/path") دیگه زیرمسیرها رو نمی‌گیره و باید /path/** بنویسی.
• هدر x-forwarded-proto فقط با گزینه xForwardedProto: true قبول می‌شه.