راهنمای مسیریابی

به راهنمای مسیریابی فینچ خوش آمدید! این راهنما شما را با مراحل پیکربندی مسیریابی در برنامه فینچ آشنا می‌کند. چه توسعه‌دهنده حرفه‌ای باشید یا تازه‌کار، فینچ ابزارهای قدرتمندی برای ساده‌سازی توسعه برنامه‌های سمت سرور ارائه می‌دهد.

FinchRoute

کلاس FinchRoute برای تعریف یک مسیر در برنامه فینچ شما استفاده می‌شود. این کلاس تمام ویژگی‌های لازم برای تعریف یک مسیر را دارد. در اینجا یک مثال از نحوه استفاده آورده شده است:

FinchRoute(
  path: '/',
  index: () async => rq.renderString(text: 'سلام دنیا'),
);

ویژگی‌ها:

• path: مسیر. می‌تواند شامل متغیرهایی به صورت {variableName} باشد. مثال: /users/{id}
• index: تابعی که هنگام تطبیق مسیر فراخوانی می‌شود. باید یک Future<String> بازگرداند.
• methods: متدهای HTTP که مسیر باید به آن‌ها پاسخ دهد. لیستی از String مانند ['GET', 'POST', ...]
• controller: کنترلری که برای مسیر استفاده می‌شود. باید نمونه‌ای از Controller باشد.
• children: مسیرهای فرزند. لیستی از FinchRoute.
• extraPath: مسیرهای اضافی برای مسیر. لیستی از String.
• apiDoc: تابعی برای تولید مستندات API مسیر. باید یک Future<ApiDoc> بازگرداند.
• auth: کنترلر احراز هویت برای مسیر. باید نمونه‌ای از AuthController باشد.
• permissions: مجوزهای مورد نیاز برای مسیر. لیستی از String مانند ['admin']
• widget: ویجتی که برای مسیر رندر می‌شود. یک String که مسیر ویجت را نشان می‌دهد.
• params: پارامترهای پیش‌فرض برای ویجت. یک Map<String, Object?>.
• title: عنوان صفحه. یک String.
• excludePaths: مسیرهایی که باید از مسیر حذف شوند. لیستی از String.
• hosts: هاست‌هایی که مسیر باید به آن‌ها پاسخ دهد. لیستی از String مانند ['example.com'].
• ports: پورت‌هایی که مسیر باید به آن‌ها پاسخ دهد. لیستی از int مانند [80, 443].

مثال تعریف یک مسیر ساده:

FinchRoute(
  key: 'route.users',
  path: '/users',
  index: () async => rq.renderJson(data: {'message': 'لیست کاربران'}),
  methods: Methods.ONLY_GET,
  hosts: ['example.com'], // یا ['*'] برای همه هاست‌ها
  ports: [80, 443], // یا [] برای همه پورت‌ها
);

مثال مسیر با کنترلر:

FinchRoute(
  key: 'route.users',
  path: '/users',
  controller: UserController(),
  methods: Methods.ONLY_GET,
  hosts: ['example.com'],
  ports: [80, 443],
);

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

FinchRoute(
  key: 'route.users',
  path: '/users',
  controller: UserController(),
  methods: Methods.ONLY_GET,
  hosts: ['example.com'],
  ports: [80, 443],
  children: [
    FinchRoute(
      key: 'route.users.show',
      path: '/{id}',
      index: () async => rq.renderJson(data: {'message': 'جزئیات کاربر'}),
      methods: Methods.ONLY_GET,
    ),
  ],
);

مثال مسیر با احراز هویت و مجوز:

FinchRoute(
  key: 'route.users',
  path: '/users',
  controller: UserController(),
  methods: Methods.ONLY_GET,
  hosts: ['example.com'],
  ports: [80, 443],
  auth: AppAuthController(),
  permissions: ['admin'],
);

AppAuthController کلاسی است که از AuthController ارث‌بری می‌کند. نمونه آن را می‌توانید در example ببینید.

مسیریابی API

فینچ راه ساده‌ای برای تعریف مسیرهای API فراهم می‌کند. می‌توانید از مسیر /api در FinchApp برای تعریف مسیر API استفاده کنید. مثال:

app.get(
  path: '/api/users',
  controller: UserController(),
);

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

برای تعریف پارامتر در مسیر، می‌توانید از سینتکس {} استفاده کنید. مثال: /users/{id}. برای دسترسی به پارامترها در تابع index از متد rq.getParam('id') استفاده کنید.