اجرای یک برنامه فینچ

یک برنامه فینچ به دو فایل نیاز دارد: app.dart (تنظیمات برنامه) و یک نقطه ورود — معمولاً bin/main.dart برای production یا lib/serve.dart برای توسعه با نظارت بر فایل.

app.dart — تنظیمات برنامه

app.dart نمونه FinchApp را می‌سازد، مسیرها را ثبت می‌کند، و main() را تعریف می‌کند. این ساختار استاندارد بر اساس پروژه مثال فینچ است:

// lib/app.dart
import 'package:finch/finch_app.dart';
import 'package:finch/finch_tools.dart';
import 'package:finch/finch_route.dart';
import 'package:finch/finch_console.dart';
import 'route/web_route.dart';

FinchConfigs configs = FinchConfigs(
  port: (env['DOMAIN_PORT'] ?? '8080').toInt(def: 8080),
  domain: env['DOMAIN'] ?? 'localhost',
  publicDir: pathTo(env['PUBLIC_DIR'] ?? './public'),
  widgetsPath: pathTo(env['WIDGETS_PATH'] ?? './lib/widgets'),
  widgetsType: env['WIDGETS_TYPE'] ?? 'j2.html',
  languagePath: pathTo(env['LANGUAGE_PATH'] ?? './lib/languages'),
  enableLocalDebugger: (env['ENABLE_LOCAL_DEBUGGER'] ?? false).toString().toBool,
);

final app = FinchApp(configs: configs);

void main([List<String>? args]) async {
  app.addRouting(getWebRoute);

  app.start(args).then((value) {
    Console.p('Server started: http://localhost:${value.port}');
  });
}

تابع مسیر

مسیرها در تابعی تعریف می‌شوند که یک Request دریافت کرده و Future<List<FinchRoute>> برمی‌گرداند:

// lib/route/web_route.dart
import 'package:finch/finch_route.dart';
import '../controllers/home_controller.dart';

final homeController = HomeController();

Future<List<FinchRoute>> getWebRoute(Request rq) async {
  return [
    FinchRoute(
      key: 'root',
      path: '/',
      methods: Methods.ONLY_GET,
      index: homeController.index,
    ),
    FinchRoute(
      key: 'root.api',
      path: 'api/hello',
      methods: Methods.ONLY_GET,
      index: homeController.hello,
    ),
  ];
}

مسیرهای Inline (میان‌بر)

برای مسیرهای ساده یا سریع، FinchApp متدهای میان‌بر دارد. callback ی که index دریافت می‌کند Request را به عنوان پارامتر می‌گیرد:

app
  ..get(
    path: '/ping',
    index: (rq) async => rq.renderString(text: 'pong'),
  )
  ..post(
    path: '/echo',
    index: (rq) async {
      var body = rq.get<String>('message', def: '');
      return rq.renderString(text: body);
    },
  )
  ..postGet(
    path: '/form',
    index: (rq) async => rq.renderString(text: 'GET or POST'),
  );

توسعه: serve.dart با نظارت بر فایل

در طول توسعه، از lib/serve.dart استفاده کنید. این فایل main() از app.dart را اجرا کرده و فایل‌های widget و زبان را برای تغییرات رصد می‌کند و بدون راه‌اندازی مجدد کامل سرور، source map های دارت را مجدداً تولید می‌کند:

finch serve -p lib/serve.dart
# یا
dart run lib/serve.dart

Production: کامپایل به باینری

برای کامپایل به یک باینری native مستقل:

finch build -a lib/app.dart -o ./build/app
./build/app

یا از Dockerfile / docker-compose ارائه‌شده استفاده کنید. به Docker مراجعه کنید.

Cron Jobs

وظایف زمان‌بندی‌شده را با app.registerCron() ثبت کنید:

app.registerCron(
  FinchCron(
    schedule: FinchCron.evryDay(2),   // هر ۲ روز
    onCron: (index, cron) async {
      // اجرای وظیفه پاک‌سازی
    },
    delayFirstMoment: true,
  ).start(),
);

// عبارت cron استاندارد
app.registerCron(
  FinchCron(
    schedule: '0 * * * *',  // هر ساعت
    onCron: (index, cron) async {
      // اجرای وظیفه ساعتی
    },
  ).start(),
);

ارسال آرگومان‌ها

همیشه args از main را به app.start() منتقل کنید. این امکان دستوراتی مانند migrate و دستورات سفارشی را فراهم می‌کند:

void main([List<String>? args]) async {
  app.addRouting(getWebRoute);
  app.start(args);
}

dart run lib/app.dart migrate --init