路由缓存系统

本指南将向您展示如何在您的 Finch 应用程序路由中使用缓存。缓存可以通过将 HTTP 响应存储在内存或文件系统中来帮助提高性能，从而大幅减少重复请求的响应时间。

什么是路由缓存？

RouteCache 类通过添加缓存功能扩展了标准的 FinchRoute。Finch 不会针对每个请求执行路由处理程序，而是拦截路由，并提供之前缓存的响应（如果存在且未过期）。

如何使用路由缓存

Finch 提供了一个关于 FinchRoute 的便捷扩展方法 .cache()，可以轻松地为现有路由封装缓存功能。

缓存基础路由示例：

FinchRoute(
  path: '/api/data',
  index: () async {
    // 一些繁重的处理或数据库查询
    await Future.delayed(Duration(seconds: 2));
    return Context.rq.renderJson(data: {'message': '已加载海量数据'});
  },
).cache(
  cacheDuration: Duration(minutes: 5), // 缓存有效期为 5 分钟
  cacheSource: CacheSource.memory,     // 将缓存存储在内存 (RAM) 中
);

配置选项

在调用 .cache()（或直接创建 RouteCache）时，您可以使用以下属性配置其行为：

cacheDuration: 缓存条目被视为有效的持续时间 (Duration)。在此时间之后，缓存将过期，并且原始处理程序将在下一次请求时重新运行。默认值为 10 分钟。
cacheSource: 缓存的存储位置。可以是用于快速 RAM 缓存的 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 data)。

包含特定缓存类型的示例：

如果您有一个接受查询参数的搜索端点，您必须在 cacheType 中包含 CacheParam.query，以便 ?q=apple 和 ?q=orange 生成不同的缓存条目。

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

缓存源 (`CacheSource`)

CacheSource.memory: 缓存存储在内存中的静态 Map 中。这是最快的缓存方法，但在服务器重新启动时将被清除。
CacheSource.file: 缓存作为 JSON 文件存储在本地磁盘上。目录由 FinchApp.config.pathCache 决定。这可以在应用程序重新启动后继续存在，但需要磁盘 I/O。

管理缓存

您可以跨应用程序全局清除所有缓存的响应。这在应用程序更新或数据迁移期间特别有用。

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

void main() async {
  // 清除所有缓存（包括内存和文件系统）
  await RouteCache.clearAllCache();
}

通过利用 RouteCache，您可以大大扩展 Finch 应用程序端点的性能，而无需添加复杂的外部依赖项！

本页内容