مسیریابی

مسیرها در فینچ با استفاده از اشیاء FinchRoute که درون یک تابع مسیریابی جمع‌آوری شده‌اند، تعریف می‌شوند. تابع مسیریابی با app.addRouting() ثبت شده و برای هر درخواست ورودی فراخوانی می‌شود.

تابع مسیریابی

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,
    ),
  ];
}

در app.dart ثبت کنید:

app.addRouting(getWebRoute);

پارامترهای FinchRoute

پارامتر	نوع	توضیح
`key`	`String`	شناسه منحصربه‌فرد مسیر. برای تولید URL استفاده می‌شود (`$e.routeUrl('key')`)
`path`	`String`	بخش مسیر URL. از `{param}` و wildcard `*` پشتیبانی می‌کند
`methods`	`List<String>`	متدهای HTTP مجاز. از ثابت‌های `Methods` استفاده کنید
`index`	`Future<String> Function()?`	تابع handler (بدون پارامتر `rq`؛ از `Context.rq` یا متد controller استفاده کنید)
`controller`	`Controller?`	نمونه controller. `index()` آن هنگامی که `index` تنظیم نشده فراخوانی می‌شود
`children`	`List<FinchRoute>`	مسیرهای فرزند تودرتو. مسیر نسبت به مسیر والد است
`extraPath`	`List<String>`	مسیرهای اضافی که به همین مسیر map می‌شوند
`auth`	`AuthController?`	نگهبان احراز هویت برای این مسیر
`permissions`	`List<String>`	رشته‌های دسترسی که پس از auth بررسی می‌شوند
`middlewares`	`List<Middleware>`	زنجیره middleware که قبل از handler اجرا می‌شود
`hosts`	`List<String>`	محدود کردن به hostnames خاص (`['*']` = همه)
`ports`	`List<int>`	محدود کردن به پورت‌های خاص (`[]` = همه)
`params`	`Map<String, dynamic>`	پارامترهای پیش‌فرض قالب
`excludePaths`	`List<String>`	زیرمسیرهایی که از این مسیر مستثنا شده‌اند
`apiDoc`	`Future<ApiDoc>? Function()?`	مستندات API برای Swagger

متدهای HTTP

// ثابت‌های دسترسی از کلاس Methods:
Methods.ONLY_GET    // ['GET']
Methods.ONLY_POST   // ['POST']
Methods.ONLY_PUT    // ['PUT']
Methods.ONLY_DELETE // ['DELETE']
Methods.GET_POST    // ['POST', 'GET']
Methods.ALL         // تمام متدهای HTTP استاندارد

// یا یک لیست سفارشی:
methods: [Methods.GET, Methods.POST, Methods.DELETE]

پارامترهای مسیر

از دستور {name} برای ضبط بخش‌های URL استفاده کنید. آن‌ها را در controller با rq.getParam('name') بخوانید:

FinchRoute(
  key: 'users.show',
  path: 'users/{id}',
  methods: Methods.ONLY_GET,
  index: userController.show,
),

// در UserController:
Future<String> show() async {
  var id = rq.getParam('id');
  return rq.renderData(data: {'id': id});
}

مسیرهای تودرتو (children)

مسیرهای فرزند نسبت به مسیر والد هستند:

FinchRoute(
  key: 'example',
  path: 'example',
  index: homeController.redirectToRoot,
  children: [
    FinchRoute(
      key: 'example.form.get',
      path: 'form',
      methods: Methods.ONLY_GET,
      index: homeController.exampleForm,
    ),
    FinchRoute(
      key: 'example.panel',
      path: 'panel',
      methods: Methods.ALL,
      auth: authController,
      permissions: ['admin'],
      index: homeController.exampleAuth,
    ),
  ],
),

مسیرهای اضافی

extraPath پیشوندهای URL اضافی را به همان مسیر map می‌کند:

FinchRoute(
  key: 'root.mysql',
  path: 'example/mysql',
  extraPath: ['api/example/mysql'],
  methods: Methods.GET_POST,
  index: homeController.exampleMysql,
),

فیلتر host و port

یک مسیر را به hostها یا پورت‌های خاص محدود کنید:

FinchRoute(
  key: 'root.localhost',
  path: 'example/host',
  hosts: ['localhost'],
  ports: [80, 8085],
  index: homeController.renderLocalhost,
  methods: Methods.ALL,
),

نگهبان احراز هویت

برای محافظت از یک مسیر یک AuthController ضمیمه کنید. اگر auth() مقدار false برگرداند، درخواست قبل از رسیدن به handler رد می‌شود:

FinchRoute(
  key: 'admin.panel',
  path: 'admin/panel',
  auth: AppAuthController(),
  permissions: ['admin'],
  index: adminController.panel,
),

برای جزئیات پیاده‌سازی به Auth Controller مراجعه کنید.

کش مسیر

از پسوند .cache() برای کش کردن پاسخ‌ها استفاده کنید:

FinchRoute(
  key: 'root.route',
  path: 'example/route',
  methods: Methods.ONLY_GET,
  index: homeController.exampleRoute,
).cache(
  cacheDuration: Duration(minutes: 10),
  cacheType: [CacheParam.path, CacheParam.method, CacheParam.language],
  cacheSource: CacheSource.file,
),

برای جزئیات کامل به Route Cache مراجعه کنید.

تولید URL از کلید مسیر

در قالب‌ها، از $e.routeUrl('key') برای تولید URL استفاده کنید:

<a href="{{ $e.routeUrl('root') }}">صفحه اصلی</a>
<a href="{{ $e.routeUrl('users.show', {'id': user.id}) }}">نمایش کاربر</a>

در این صفحه