درک سرور و عیب‌یابی برنامهدرس ۱۴ از ۲۰

عیب‌یابی Node.js در ویندوز؛ از breakpoint تا خطاهای اتصال

۴۰ دقیقه آموزش متنی

در این درس ۵ بخش

وقتی برنامه نتیجهٔ غلط می‌دهد، نصب دوبارهٔ Node.js معمولاً اولین آزمایش خوبی نیست. ابتدا مسئله را کوچک کنید: چه دستوری اجرا شد، از کدام پوشه، با چه نسخه‌ای و انتظار چه بود؟ سپس مشخص کنید شکست پیش از شروع برنامه رخ داده، هنگام بارگذاری ماژول بوده یا در زمان رسیدگی به درخواست. در این درس هم خطای منطقی قابل مشاهده با debugger داریم و هم خطاهای معمول محیط و شبکه. از دادهٔ ساختگی استفاده می‌کنیم تا گزارش خطا حاوی اطلاعات شخصی نباشد.

یک خطای منطقی که با حدس پنهان می‌ماند

فایل debug-total.mjs را بسازید. مقدارهای ورودی عمداً متن هستند؛ درست مانند بسیاری از ورودی‌های فرم. خروجی اشتباه، برنامه را لزوماً متوقف نمی‌کند. پیش از اصلاح کد، می‌خواهیم نوع متغیر را در لحظهٔ اجرا ببینیم.

const price = '80000';
const shipping = '20000';
const total = price + shipping;
console.log(total); // 8000020000

در VS Code پوشهٔ دارای همین فایل را باز کنید. کنار خط const total در حاشیهٔ شمارهٔ خط کلیک کنید تا breakpoint ثبت شود. از Command Palette با Ctrl+Shift+P گزینهٔ Debug: Create JavaScript Debug Terminal را انتخاب کنید و در آن node .\debug-total.mjs را اجرا کنید. هنگام توقف، نشانگر را روی price ببرید و نوع و مقدار را ببینید. در بخش Watch عبارت typeof price را اضافه کنید. لازم نیست افزونهٔ ناشناس نصب یا تنظیم فایروال عوض شود.

با Step Over از محاسبه عبور کنید و total را بررسی کنید. جمع دو رشته در این مثال الحاق انجام داده است. پاسخ فوری Number(price) + Number(shipping) برای همین داده خروجی ۱۰۰۰۰۰ می‌دهد؛ اما برای ورودی واقعی هنوز قرارداد، محدوده و خالی‌نبودن لازم است. debugger علت را نشان می‌دهد و جای طراحی اعتبارسنجی را نمی‌گیرد. پس از اصلاح، breakpoint را بردارید و دوباره بدون توقف اجرا کنید تا به نتیجهٔ ابزار وابسته نمانید.

راه جایگزین؛ تنظیم اجرای قابل تکرار

اگر از JavaScript Debug Terminal استفاده نمی‌کنید، فایل .vscode/launch.json را با محتوای زیر در همان پوشه بسازید و در Run and Debug پیکربندی را با F5 اجرا کنید. این راه، برنامه را خود VS Code راه می‌اندازد؛ هم‌زمان همان فایل را در ترمینال معمولی اجرا نکنید، به‌خصوص اگر بعداً یک سرور باشد.

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug local total",
      "program": "${workspaceFolder}/debug-total.mjs",
      "console": "integratedTerminal",
      "skipFiles": ["<node_internals>/**"]
    }
  ]
}

در اتصال به یک برنامهٔ از قبل روشن، دستور node --inspect-brk=127.0.0.1:9229 .\debug-total.mjs راه دیگری است؛ این دستور تا اتصال debugger، اجرای کد را نگه می‌دارد. inspector را روی 0.0.0.0 باز نکنید و پورت آن را عمومی نکنید. قابلیت بازرسی اجرای برنامه، دسترسی قدرتمندی است. برای مسیر اصلی این دوره همان اجرای داخلی VS Code کافی است و نیازی به اتصال از موبایل یا دستگاه دیگر نداریم.

نشانه را به لایهٔ خطا وصل کنید

اگر PowerShell می‌گوید node شناخته نشد، هنوز کد برنامه اجرا نشده است: پنجرهٔ ترمینال تازه باز کنید و Get-Command node و where.exe node را با درس نصب مقایسه کنید. اگر خطا MODULE_NOT_FOUND یا ERR_MODULE_NOT_FOUND است، نام فایل، مسیر import و پسوند را بررسی کنید؛ بستهٔ builtin با پیشوند node: را از npm نصب نکنید. اگر npm.ps1 با سیاست اجرای اسکریپت مسدود است، از npm.cmd استفاده کنید و سیاست دستگاه را برای حل این تمرین خاموش نکنید.

برای EADDRINUSE ابتدا ترمینال‌های خودتان را بررسی کنید: ممکن است همان سرور دوبار اجرا شده باشد. در ترمینال مالک نمونهٔ اضافی Ctrl+C بزنید یا پورت تمرین را در کد و نشانی کلاینت هماهنگ تغییر دهید. دستور توقف اجباری همهٔ node.exeها راه تشخیص نیست و می‌تواند برنامهٔ دیگری را ببندد. دیدن یک PID نیز به‌تنهایی مجوز بستن فرایند ناشناس نیست. در محیط کاری، سرویس‌های دیگر را با مسئول همان سیستم هماهنگ کنید.

پاسخ ۴۰۴ با شکست fetch یکی نیست

سرور درس قبل را روشن کنید و فایل check-fetch.mjs زیر را در ترمینال دوم اجرا کنید. fetch در Node.js موجود است و برای این مثال بستهٔ node-fetch نصب نمی‌کنیم. ابتدا وضعیت پاسخ را مستقل می‌بینیم و سپس تصمیم می‌گیریم پاسخ ناموفق را به خطای قراردادی تبدیل کنیم.

try {
  const response = await fetch('http://127.0.0.1:3100/missing', {
    signal: AbortSignal.timeout(3000)
  });
  console.log('HTTP status:', response.status);
  if (!response.ok) throw new Error(`HTTP ${response.status}`);
  console.log(await response.json());
} catch (error) {
  console.error('Request failed:', error.message);
  process.exitCode = 1;
}

با سرور روشن، ابتدا HTTP status: 404 و سپس پیام خطای HTTP 404 دیده می‌شود؛ این throw را خودمان پس از بررسی ok ایجاد کرده‌ایم. حالا سرور را با Ctrl+C متوقف و دوباره فایل را اجرا کنید. این بار پاسخ HTTP دریافت نشده و شکست اتصال رخ می‌دهد؛ متن دقیق پیام می‌تواند با نسخه و محیط فرق کند. محدودیت سه‌ثانیه‌ای برای کلاینت این تمرین است و جای محدودکردن زمان کارهای سرور یا کنترل حجم پاسخ را نمی‌گیرد.

تمرین و پاسخ تشریحی

گزارش عیب‌یابی چهارستونی بنویسید: نشانه، لایه، آزمایش بعدی و نتیجه. حالت‌های عنوان متنی در جمع، مسیر ناشناخته، سرور خاموش و ماژول با نام اشتباه را پوشش دهید. پاسخ راهنما: نوع داده را با breakpoint ببینید؛ ۴۰۴ را با وضعیت پاسخ تشخیص دهید؛ در شکست اتصال ابتدا زنده‌بودن سرور و پورت را بررسی کنید؛ خطای ماژول را با مسیر واقعی فایل مقایسه کنید. معیار تحویل، اصلاحی است که علت را هدف بگیرد و پس از آن دوباره همان ورودی قبلی با موفقیت آزمایش شود.

VS Code، عیب‌یابی Node.js: https://code.visualstudio.com/docs/nodejs/nodejs-debugging
Node.js، خطاهای رایج سیستم: https://nodejs.org/api/errors.html#common-system-errors
MDN، رفتار fetch و بررسی response.ok: https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch

تألیف و مثال‌های اختصاصی: تحریریه درس‌آوند.

ورود برای ثبت پیشرفت

متن درس‌های عمومی را بدون ورود بخوانید.

آموزش رایگان Node.js در ویندوز؛ از نصب تا ساخت API