Flutter数据存储插件the_storage的使用

TheStorage

一个用于Flutter的快速且安全的数据存储库。

特性

• 快速高效的存储操作
• 数据加密安全
• 易于使用的API

开始使用

要使用该包，请在pubspec.yaml文件中添加the_storage作为依赖项。

dependencies:
  the_storage: ^x.x.x

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

使用方法

导入包

import 'package:the_storage/the_storage.dart';

初始化存储实例

// 初始化存储实例，可以指定数据库文件名
TheStorage.i().init(dbName: 'my_storage.db');

写入键值对到存储

// 写入键值对到存储
TheStorage.i().set('myKey', 'myValue');

从存储读取值

// 从存储读取值
final value = await TheStorage.i().get('myKey');

使用域来分离数据

// 在特定域下写入键值对
await TheStorage.i().set('myKey', 'myValue', domain: 'myDomain');

// 从特定域读取键值对
final data = await TheStorage.i().get('myKey', domain: 'myDomain');

删除键值对

// 删除特定域下的键值对
await TheStorage.i().delete(
  'myKey',
  domain: 'myDomain',
);

批量操作

// 在特定域下批量写入多个键值对，并指定是否覆盖现有值
await TheStorage.i().setDomain(
  {
    'myKey': 'myValue',
    'myKey2': 'myValue2',
  },
  domain: 'myDomain',
  overwrite: false,
);

获取特定域下的所有键值对或仅获取键

// 获取特定域下的所有键值对
final domain = await TheStorage.i().getDomain(
  domain: 'myDomain',
);

// 获取特定域下的所有键
final domainKeys = await TheStorage.i().getDomainKeys(
  domain: 'myDomain',
);

删除特定域下的数据

// 删除特定域下的数据
await TheStorage.i().deleteDomain(
  [
    'myKey',
    'myKey2',
  ],
  domain: 'myDomain',
);

清除所有数据

// 清除所有数据
await TheStorage.i().clear();

重置存储（用于调试）

// 重置存储，这将删除存储文件并释放存储实例。因此，应该在重置后再次调用 `init()` 方法
await TheStorage.i().reset();

反应式监听

TheStorage 提供了一种反应式的方式来监听存储的变化。你可以使用 stream 版本的 get, getDomain 和 getDomainKeys 方法来监听存储的变化：

// 监听特定键的变化
final valueStream = await TheStorage.i().subscribe('myKey', domain: 'myDomain');

// 监听特定域下的所有键值对的变化
final domainStream = await TheStorage.i().subscribeDomain('myDomain');

// 监听特定域下的所有键的变化
final domainKeysStream = await TheStorage.i().subscribeDomainKeys('myDomain');

这些方法除了与非流版本相同的方法参数外，还接受一个布尔类型的 keepAlive 参数，该参数指定在最后一个订阅者取消订阅时是否保持流活跃，以便数据保留在内存中而不是从存储重新获取。默认情况下，keepAlive 为 true。

加密

TheStorage 使用 flutter_secure_storage 包来存储密钥和初始向量。每个记录键都使用AES算法和256位密钥及128位初始向量进行加密。为了加密记录数据，使用相同的256位密钥和唯一的（对于每个记录）128位种子向量，该向量与加密数据一起存储。因此，每个记录都有自己的初始向量。这种方法使得不可能通过比较已知源数据的加密数据来进行重放攻击。

存储

TheStorage 使用 sqflite 包来存储数据。这是一种在设备上存储数据的快速可靠的方法。TheStorage 使用单个表来存储所有数据，并使用索引来加速数据搜索。

测试

该包包含几个单元测试以验证其功能。要运行这些测试，请使用以下命令：

flutter test

完整示例

以下是一个完整的示例代码，展示了如何使用 the_storage 插件：

// ignore_for_file: public_member_api_docs

import 'dart:developer' as developer;

import 'package:flutter/material.dart';
import 'package:the_storage/the_storage.dart';

void main() {
  runApp(const MyApp());
}

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

  // 这个小部件是你的应用的根。
  [@override](/user/override)
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'TheStorage Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      home: const MyHomePage(),
    );
  }
}

class MyHomePage extends StatefulWidget {
  const MyHomePage({super.key});

  [@override](/user/override)
  State<MyHomePage> createState() => _MyHomePageState();
}

class _MyHomePageState extends State<MyHomePage> {
  [@override](/user/override)
  void initState() {
    super.initState();
    TheStorage.i().init();
  }

  [@override](/user/override)
  void dispose() {
    TheStorage.i().dispose();
    super.dispose();
  }

  Future<void> writeDb() async {
    await TheStorage.i().set('myKey', 'myValue');
    developer.log("read from DB: myKey: 'myValue'");
  }

  Future<void> readDb() async {
    developer.log("read from DB: myKey: '${await TheStorage.i().get('myKey')}'");
  }

  Future<void> clearDb() async {
    await TheStorage.i().clearAll();
    developer.log('clear DB');
  }

  [@override](/user/override)
  Widget build(BuildContext context) {
    return Scaffold(
      body: Center(
        child: Column(
          mainAxisSize: MainAxisSize.min,
          children: [
            ElevatedButton(
              onPressed: writeDb,
              child: const Text('Write to DB'),
            ),
            ElevatedButton(
              onPressed: readDb,
              child: const Text('Read from DB'),
            ),
            ElevatedButton(
              onPressed: clearDb,
              child: const Text('Clear DB'),
            ),
          ],
        ),
      ),
    );
  }
}