اعتبارسنجی مجدد

مستنداتی که فرستادی، معماری کاملاً جدید سیستم کشینگ و اعتبارسنجی مجدد (Revalidation) در نسل جدید Next.js (با فعال بودن قابلیت cacheComponents: true در فایل next.config.ts) را توصیف می‌کند. در این مدل، از دایرکتیو قدرتمند 'use cache' به همراه پکیج next/cache برای مدیریت کش استفاده می‌شود.

اعتبارسنجی مجدد (Revalidation) فرآیند به‌روزرسانی داده‌های کش‌شده است. این سیستم به شما اجازه می‌دهد تا در عین حفظ سرعت فوق‌العاده پاسخ‌های کش‌شده، از تازگی محتوا نیز مطمئن شوید. در این مدل جدید، دو استراتژی اصلی داریم:

۱. اعتبارسنجی مبتنی بر زمان (Time-based): به‌روزرسانی خودکار کش پس از یک مدت زمان مشخص با cacheLife.

۲. اعتبارسنجی بر اساس تقاضا (On-demand): باطل کردن دستی کش بلافاصله بعد از تغییر دیتابیس (Mutation) با استفاده از revalidateTag، updateTag یا revalidatePath.

۱. اعتبارسنجی مبتنی بر زمان: تابع cacheLife

تابع cacheLife مشخص می‌کند که دیتای کش‌شده چقدر معتبر بماند. این تابع باید حتماً درون اسکوپی که دایرکتیو 'use cache' دارد صدا زده شود.

// app/lib/data.ts
import { cacheLife } from 'next/cache'
 
export async function getProducts() {
  'use cache' // فعال‌سازی سیستم کشینگ جدید روی این تابع
  cacheLife('hours') // استفاده از پروفایل پیش‌فرض hours
  return db.query('SELECT * FROM products')
}

پروفایل‌های پیش‌فرض cacheLife

ری‌آکت و Next.js پروفایل‌های زمانی آماده‌ای را برای راحتی کار در اختیارتان می‌گذارند:

💡 نکته مهم (Short-lived Caches): اگر از پروفایل seconds استفاده کنید، یا به صورت دستی مقدار expire را زیر ۵ دقیقه یا revalidate: 0 تنظیم کنید، کش شما «کوتاه مدت» فرض می‌شود. این نوع کش‌ها به طور خودکار از فرآیند Prerender (رندر اولیه در زمان بیلد) حذف شده و به جایش یک حفره پویا (Dynamic Hole) ایجاد می‌شود.

تنظیمات شخصی‌سازی شده (Custom Configuration)

برای کنترل دقیق‌تر، می‌توانید یک شیء با مقادیر ثانیه به تابع پاس دهید:

'use cache'
cacheLife({
  stale: 3600,     // تا ۱ ساعت دیتا کاملاً تازه فرض می‌شود
  revalidate: 7200, // بعد از ۲ ساعت تلاش برای اعتبارسنجی مجدد در پس‌زمینه آغاز می‌شود
  expire: 86400,   // بعد از ۱ روز کش کاملاً منقضی شده و هارد-ریفرش می‌شود
})

۲. برچسب‌گذاری کش: تابع cacheTag

برای اینکه بتوانید در زمان دلخواه (مثلاً بعد از این که ادمین یک محصول را ویرایش کرد) کش را به صورت دستی پاک کنید، باید به کش خود یک برچسب (Tag) اختصاص دهید:

// app/lib/data.ts
import { cacheTag } from 'next/cache'
 
export async function getProducts() {
  'use cache'
  cacheTag('products') // برچسب‌گذاری این کش با نام products
  return db.query('SELECT * FROM products')
}

۳. متدهای اعتبارسنجی بر اساس تقاضا (On-demand)

بعد از برچسب‌گذاری، سه ابزار قدرتمند برای باطل کردن کش در اختیار دارید:

الف) متد revalidateTag (مدل تعویض در پس‌زمینه)

این متد از استراتژی Stale-while-revalidate استفاده می‌کند؛ یعنی به محض فراخوانی، دیتای کهنه بلافاصله به کاربر فعلی نمایش داده می‌شود، اما در پس‌زمینه دیتای جدید لود شده و جایگزین می‌شود. این روش برای بخش‌هایی مثل بلاگ یا کاتالوگ محصولات که تأخیر چند ثانیه‌ای در به‌روزرسانی برای کاربر ملاک نیست، فوق‌العاده است.

// app/lib/actions.ts
import { revalidateTag } from 'next/cache'
 
export async function updateUser(id: string) {
  // عملیات تغییر دیتا در دیتابیس (Mutation)
  // ...
  revalidateTag('user', 'max') 
}

💡 پارامتر دوم (max): مشخص می‌کند دیتای کهنه (Stale) چه مدت مجاز است در حین ساخته شدن دیتای جدید در پس‌زمینه به کاربران نشان داده شود. مقدار 'max' طولانی‌ترین پنجره زمان ممکن را به شما می‌دهد. این متد هم در Server Actions و هم در Route Handlers قابل استفاده است.

ب) متد updateTag (مدل انقضای آنی)

این متد دقیقاً برای سناریوی Read-your-own-writes طراحی شده است؛ یعنی کاربر فرمی را سابمیت می‌کند و مایل است بلافاصله تغییر خود را ببیند. updateTag کش را در همان لحظه منقضی می‌کند تا کاربر دیتای کهنه را نبیند.

⚠️ محدودیت مهم: این متد فقط و فقط درون Server Actions قابل استفاده است.

// app/lib/actions.ts
import { updateTag } from 'next/cache'
import { redirect } from 'next/navigation'
 
export async function createPost(formData: FormData) {
  await db.post.create({ data: { title: formData.get('title') } })
 
  updateTag('posts') // انقضای فوری کش محصولات/پست‌ها
  redirect(`/posts`) // هدایت کاربر و مشاهده دیتای ۱۰۰٪ تازه
}

تفاوت کلیدی updateTag و revalidateTag

ج) متد revalidatePath (پاک‌سازی بر اساس مسیر)

اگر می‌خواهید تمام کش‌های مربوط به یک صفحه یا مسیر خاص را بدون درگیر شدن با برچسب‌ها باطل کنید، از این متد استفاده می‌کنید:

import { revalidatePath } from 'next/cache'
 
export async function updateProfile() {
  // تغییر دیتای پروفایل...
  revalidatePath('/profile') // پاک کردن کل کش‌های صفحه پروفایل
}

🎯 توصیه معماری: تا حد امکان ترجیح بر این است که از متدهای مبتنی بر تگ (cacheTag / updateTag) استفاده کنید. متد revalidatePath کل مسیر را هدف قرار می‌دهد و ممکن است بخش‌هایی از صفحه را که نیازی به رندر مجدد ندارند، به شکل غیربهینه بازسازی کند.

چه چیزهایی را کش کنیم؟

1. دیتایی را کش کنید که وابسته به داده‌های زمان اجرا (Runtime Data مانند کوکی‌ها یا هدرهای متغیر هر کاربر) نیست و مشکلی ندارید که برای مدتی از حافظه موقت خوانده شود.

2. برای سیستم‌های مدیریت محتوا (CMS) که سیستم وب‌هوک یا تریکر به‌روزرسانی دارند، بهترین استراتژی این است که طول عمر کش (cacheLife) را بسیار طولانی (مثل days یا weeks) تنظیم کنید و فقط با استفاده از revalidateTag به محض تغییر واقعی محتوا در پنل مدیریت، کش را به صورت On-demand تازه کنید. این کار سرور شما را از رندرهای بیهوده نجات می‌دهد.