Debugging

فینچ یک debugger داخلی دارد که صفحه‌های خطای دقیق را در محیط توسعه نمایش می‌دهد.

فعال‌سازی debugger

دو تنظیم مورد نیاز است:

// در lib/app.dart
FinchConfigs(
  enableLocalDebugger: true,   // تنظیم 1: فعال‌سازی debugger
)

// در bin/finch.dart
FinchApp.run(
  app: App(),
  isLocalDebug: true,          // تنظیم 2: اجرا در حالت debug محلی
)

هر دو تنظیم باید true باشند تا صفحه‌های خطای debug نمایش داده شوند.

چگونگی محاسبه isLocalDebug

معمولاً isLocalDebug از یک متغیر محیطی خوانده می‌شود:

FinchApp.run(
  app: App(),
  isLocalDebug: env.get('APP_ENV') == 'local',
)

به این ترتیب می‌توانید با استقرار APP_ENV=production، debugger را غیرفعال کنید.

متغیر قالب

در قالب‌های Jinja، isLocalDebug در دسترس است:

{% if isLocalDebug %}
  <div class="debug-bar">
    محیط: توسعه | نسخه: {{ appVersion }}
  </div>
{% endif %}

پنل Terminal

وقتی برنامه با finch serve اجرا شود (نه یک dart run ساده)، CLI یک سرور WebSocket روی --terminalPort (پیش‌فرض 8282) باز می‌کند که stdout/stderr پردازش در حال اجرا را استریم می‌کند. تب Terminal در نوار debug به‌صورت خودکار به این پورت متصل می‌شود، بنابراین می‌توانید لاگ‌های سرور و خروجی کنسول را بدون جابه‌جایی به پنجره ترمینال مشاهده کنید و از مرورگر دستور به پردازش در حال اجرا ارسال کنید.

# استفاده از یک ترمینال‌پورت سفارشی
finch serve --terminalPort 9000

این قابلیت فقط از طریق finch serve کار می‌کند، چون این همان پردازشی است که app را اجرا کرده و FINCH_TERMINAL_PORT را در محیط آن قرار می‌دهد. اجرای مستقیم app با dart run باعث می‌شود تب Terminal بدون اتصال بماند.

پنل DartDevTools

finch serve همچنین app را با --enable-vm-service=8181/0.0.0.0 --disable-service-auth-codes اجرا می‌کند و سرویس VM دارت را روی تمام رابط‌ها (نه فقط localhost) bind می‌کند تا از داخل یک کانتینر Docker نیز در دسترس باشد. نوار debug یک تب DevTools را جاسازی می‌کند که به این سرویس VM روی پورت 8181 متصل می‌شود و نماهای حافظه، عملکرد و لاگ برای app در حال اجرا را مستقیماً در مرورگر در اختیار شما قرار می‌دهد.

اگر فینچ را در Docker اجرا می‌کنید، مطمئن شوید پورت‌های 8181 و 8282 نیز در کنار پورت app منتشر (publish) شده‌اند — به Docker for Finch مراجعه کنید.

صفحه خطا

هنگامی که debugger فعال است:

• خطاهای مدیریت‌نشده stack trace کامل را در مرورگر نمایش می‌دهند
• خطاهای 404 و 500 صفحه‌های زیبا و اطلاعات‌دهنده نمایش می‌دهند
• اطلاعات درخواست (headers، params، body) قابل مشاهده هستند

در حالت production (isLocalDebug: false):

• صفحه‌های خطای عمومی برای کاربران نمایش داده می‌شود
• stack trace ها در console لاگ می‌شوند نه در browser