Flutter数据缓存插件data_cache_x的使用

Flutter数据缓存插件data_cache_x的使用

data_cache_x

一个使用Hive作为后端的Dart包，用于缓存数据，并支持自动清理过期项。

特性

• 数据缓存：使用Hive作为底层存储来存储和检索任意类型的数据。
• 依赖注入：利用get_it进行依赖注入，便于替换不同的缓存适配器。
• Hive集成：利用Hive的NoSQL数据库能力实现快速高效的数据存储。
• 自动后台清理：使用workmanager包自动移除缓存中的过期项，确保存储空间的有效利用。
• 自定义过期时间：为缓存项设置过期时间，允许对数据新鲜度进行细粒度控制。
• 错误处理：包含强大的错误处理机制，针对各种错误情况抛出定制异常。
• 可扩展性：设计时考虑到扩展性，便于开发人员轻松添加其他存储适配器的支持。

安装

在pubspec.yaml文件中添加data_cache_x：

dependencies:
  data_cache_x: ^latest_version

然后运行flutter pub get以安装该包。

使用

基本用法

1. 初始化包

   import 'package:data_cache_x/data_cache_x.dart';
   import 'package:data_cache_x/service_locator.dart';
   
   Future<void> main() async {
     // 初始化服务定位器
     await setupDataCacheX();
   
     // 获取DataCacheX实例
     final dataCache = getIt<DataCacheX>();
   
     // ...
   }
   

2. 存储数据

   // 存储字符串并设置1小时过期时间
   await dataCache.put('myKey', 'myValue', expiry: Duration(hours: 1));
   
   // 存储整数且不设置过期时间
   await dataCache.put('anotherKey', 42);
   

3. 检索数据

   // 检索字符串值
   final myValue = await dataCache.get<String>('myKey');
   print(myValue); // 输出: myValue (如果未过期)
   
   // 检索整数值
   final anotherValue = await dataCache.get<int>('anotherKey');
   print(anotherValue); // 输出: 42
   

4. 删除数据

   await dataCache.delete('myKey');
   

5. 清空缓存

   await dataCache.clear();
   

6. 检查键是否存在

   final exists = await dataCache.containsKey('myKey');
   print(exists); // 输出: true 或 false
   

高级用法

1. 初始化后台清理

   import 'package:data_cache_x/utils/background_cleanup.dart';
   
   // ...
   
   // 初始化后台清理（在设置服务定位器后调用）
   initializeBackgroundCleanup();
   

   这将调度每小时运行一次的任务，以从缓存中移除过期项。

2. 使用不同的缓存适配器

   可以通过实现CacheAdapter接口创建自己的缓存适配器，然后将其注册到服务定位器中。

   // 示例：创建自定义缓存适配器（未在提供的代码中实现）
   class MyCustomAdapter implements CacheAdapter {
     // 实现CacheAdapter方法
     // ...
   }
   
   // 将自定义适配器注册到服务定位器
   getIt.registerSingleton<CacheAdapter>(MyCustomAdapter());
   
   // 使用自定义适配器
   getIt.registerSingleton<DataCacheX>(DataCacheX(getIt<CacheAdapter>()));
   

API 参考

DataCacheX

• put<T>(String key, T value, {Duration? expiry}): 在缓存中存储一个带有可选过期时间的值。
• get<T>(String key): 从缓存中检索一个值。如果键不存在或项已过期，则返回null。
• delete(String key): 从缓存中删除一个值。
• clear(): 清空整个缓存。
• containsKey(String key): 检查缓存中是否存在指定键。

CacheItem

• value: 要缓存的实际值。
• expiry: 表示缓存项过期日期的可选DateTime对象。
• isExpired: 如果项已过期则返回true。

异常

• DataCacheXException: 与数据存储操作相关的通用异常。
• KeyNotFoundException: 当指定键不在缓存中时抛出。
• DataTypeMismatchException: 当期望的数据类型与实际数据类型不匹配时抛出。
• StorageException: 与底层存储机制相关的错误。
• CacheException: 与缓存操作相关的通用异常。

示例代码

import 'package:example/news_app/bloc/news_bloc.dart';
import 'package:example/news_app/screens/news_screen.dart';
import 'package:example/service_locator.dart';
import 'package:example/todo_app/bloc/todo_bloc.dart';
import 'package:example/todo_app/screens/todo_screen.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await setup();
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'DataCacheX Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const HomeScreen(),
    );
  }
}

class HomeScreen extends StatelessWidget {
  const HomeScreen({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: const Text('DataCacheX Demo'),
      ),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            ElevatedButton(
              onPressed: () {
                Navigator.push(
                  context,
                  MaterialPageRoute(
                    builder: (context) => BlocProvider<NewsBloc>(
                      create: (context) => getIt<NewsBloc>(),
                      child: const NewsScreen(),
                    ),
                  ),
                );
              },
              child: const Text('News App'),
            ),
            ElevatedButton(
              onPressed: () {
                Navigator.push(
                  context,
                  MaterialPageRoute(
                    builder: (context) => BlocProvider<TodoBloc>(
                      create: (context) => getIt<TodoBloc>()..add(LoadTodosEvent()),
                      child: const TodoScreen(),
                    ),
                  ),
                );
              },
              child: const Text('Todo App'),
            ),
          ],
        ),
      ),
    );
  }
}