در این صفحه

سیستم کش مسیر (Route Cache)

این راهنما شما را با مراحل استفاده از کش (caching) در مسیرهای برنامه Finch آشنا می‌کند. کش کردن با ذخیره پاسخ‌های HTTP در حافظه یا سیستم فایل، به طور چشمگیری زمان پاسخ‌دهی به درخواست‌های تکراری را کاهش داده و به بهبود عملکرد کمک می‌کند.

کش مسیر چیست؟

کلاس RouteCache با افزودن قابلیت کش کردن، FinchRoute استاندارد را توسعه می‌دهد. به جای اجرای پردازشگر مسیر برای هر درخواست، Finch مسیر را رهگیری کرده و پاسخ کش شده‌ی قبلی را در صورتی که وجود داشته باشد و منقضی نشده باشد، ارائه می‌دهد.

نحوه استفاده از کش مسیر

فریم‌ورک Finch یک افزونه (extension) راحت روی FinchRoute به نام .cache() ارائه می‌دهد که به سادگی مسیرهای موجود شما را با قابلیت کش کردن می‌پوشاند.

نمونه‌ای از کش کردن یک مسیر ساده:

FinchRoute(
  path: '/api/data',
  index: () async {
    // پردازش سنگین یا کوئری دیتابیس
    await Future.delayed(Duration(seconds: 2));
    return Context.rq.renderJson(data: {'message': 'Heavy data loaded'});
  },
).cache(
  cacheDuration: Duration(minutes: 5), // اعتبار کش به مدت ۵ دقیقه
  cacheSource: CacheSource.memory,     // ذخیره کش در حافظه (RAM)
);

گزینه‌های پیکربندی

هنگامی که .cache() را فراخوانی می‌کنید (یا به طور مستقیم یک RouteCache ایجاد می‌کنید)، می‌توانید رفتار آن را با این ویژگی‌ها پیکربندی کنید:

  • cacheDuration: یک شیء Duration که مدت زمان معتبر بودن کش را مشخص می‌کند. پس از این زمان، کش منقضی شده و کنترل‌کننده اصلی برای درخواست بعدی دوباره اجرا می‌شود. مقدار پیش‌فرض 10 دقیقه است.
  • cacheSource: محل ذخیره‌سازی کش. می‌تواند CacheSource.memory (پیش‌فرض) برای کش کردن سریع در رم یا CacheSource.file برای کش کردن دائمی در فایل باشد.
  • cacheType: لیستی از CacheParam که مشخص می‌کند چه بخش‌هایی از درخواست، کلید منحصر به فرد کش را تشکیل می‌دهند. پیش‌فرض [CacheParam.method, CacheParam.path] است.

انواع کش (CacheParam)

شما می‌توانید با استفاده از CacheParam نحوه ساخت کلید کش را تعریف کنید. این کار اطمینان حاصل می‌کند که درخواست‌های متفاوت، به اشتباه یک پاسخ کش شده‌ی یکسان را دریافت نمی‌کنند.

  • CacheParam.path: (الزامی) مسیر URI درخواست (مثل /api/data).
  • CacheParam.method: متد HTTP (مثل GET، POST).
  • CacheParam.query: پارامترهای پرس‌وجو در URL (مثل ?page=1&limit=10).
  • CacheParam.data: داده‌های بدنه (body) درخواست.

نمونه با انواع کش خاص:

اگر یک اندپوینت جستجو دارید که پارامترهای پرس‌وجو می‌گیرد، باید CacheParam.query را در cacheType خود بگنجانید تا ?q=apple و ?q=orange کش‌های متفاوتی تولید کنند.

FinchRoute(
  path: '/search',
  index: () async {
    final query = Context.rq.getQuery('q');
    return Context.rq.renderJson(data: {'results': 'Found results for $query'});
  },
).cache(
  cacheType: [CacheParam.path, CacheParam.method, CacheParam.query],
);

منابع کش (CacheSource)

  • CacheSource.memory: کش در یک Map ثابت (static) در حافظه ذخیره می‌شود. این سریع‌ترین روش کش کردن است اما در صورت راه‌اندازی مجدد سرور پاک می‌شود.
  • CacheSource.file: کش به صورت فایل‌های JSON در دیسک محلی ذخیره می‌شود. دایرکتوری با FinchApp.config.pathCache مشخص می‌شود. این نوع کش پس از راه‌اندازی مجدد برنامه باقی می‌ماند اما نیاز به خواندن/نوشتن دیسک دارد.

مدیریت کش

شما می‌توانید تمام پاسخ‌های کش شده را به صورت سراسری در کل برنامه خود پاک کنید. این کار به خصوص در زمان به‌روزرسانی برنامه یا مهاجرت داده‌ها مفید است.

import 'package:finch/src/router/route_cache.dart';

void main() async {
  // پاک کردن تمام کش‌ها (هم در حافظه و هم در سیستم فایل)
  await RouteCache.clearAllCache();
}

با استفاده از RouteCache، می‌توانید بدون افزودن وابستگی‌های خارجی پیچیده، عملکرد اندپوینت‌های برنامه Finch خود را به میزان قابل توجهی ارتقا دهید!

قبلی
انجینکس برای فینچ
فینچ برای استفاده با داکر و Nginx ساده‌سازی شده اس...