کنترلرها

کنترلرها منطق مدیریت درخواست را در فینچ کپسوله می‌کنند. یک کنترلر کلاسی است که از Controller ارث‌بری می‌کند و به شیء درخواست جاری از طریق rq دسترسی می‌دهد.

ساختار پایه

import 'package:finch/finch_route.dart';

class HomeController extends Controller {
  Future<String> index() async {
    return rq.renderView(path: 'home/index');
  }
}

برای دسترسی به کنترلر در مسیریابی:

final homeController = HomeController();

FinchRoute(
  key: 'root',
  path: '/',
  methods: Methods.ONLY_GET,
  index: homeController.index,
),

شیء rq

rq (کوتاه‌شده برای request) شیء مرکزی موجود در هر متد کنترلر است. این شیء دسترسی به داده‌های درخواست، متدهای پاسخ، session، کوکی‌ها، زبان و موارد دیگر را فراهم می‌کند.

متدهای پاسخ

رندر یک قالب

Future<String> index() async {
  return rq.renderView(
    path: 'home/index',        // مسیر نسبت به widgetsPath بدون پسوند
    params: {
      'title': 'صفحه اصلی',
      'user': currentUser,
    },
  );
}

بازگرداندن JSON

Future<String> apiUser() async {
  var id = rq.getParam('id');
  var user = await UserModel().find(id: id);
  return rq.renderData(data: user?.toJson() ?? {});
}

خواندن داده‌های درخواست

// پارامترهای query/form
var name = rq.get<String>('name', def: '');
var age  = rq.get<int>('age', def: 0);

// پارامترهای مسیر (/users/{id})
var id   = rq.getParam('id');

// Body خام JSON
var body = await rq.getBodyAsJson();

// فایل آپلودی
var file = rq.getFile('avatar');

ویژگی‌های درخواست

rq.method           // 'GET', 'POST', …
rq.path             // '/users/42'
rq.ip               // آدرس IP کلاینت
rq.headers          // Map<String, List<String>>
rq.isJson           // آیا Content-Type برابر application/json است
rq.currentLanguage  // کد زبان جاری

ارسال داده به قالب

علاوه بر params درون متد renderView، می‌توانید پارامترها را برای کل مسیر در تعریف FinchRoute تعیین کنید:

FinchRoute(
  key: 'root',
  path: '/',
  params: {'siteName': 'فینچ دمو'},
  index: homeController.index,
),

داده‌های سطح route با داده‌های سطح controller در renderView ادغام می‌شوند.

خطاهای HTTP

// ارسال ۴۰۳ Forbidden
return rq.renderError(status: 403, message: 'دسترسی ممنوع');

// ارسال ۵۰۰ Internal Server Error
return rq.renderError(status: 500);