Flutter数据库管理插件nest_db的使用

Nest DB

Beta版本

Nest DB 是一个专为 Flutter 应用设计的轻量级内存数据库，具有持久化存储功能。它提供了一种简单而强大的方式来管理应用程序中的结构化数据，支持模式验证、响应式更新和持久化存储。

特性

• 文档导向: 将数据存储为类似 JSON 的文档（映射）集合，提供了灵活性和易用性。
• 模式验证: 允许定义集合的模式以确保数据符合特定的数据类型和规则。
• 响应式更新: 集成到 Flutter 的响应式框架中，可以轻松监听数据变化并相应地更新用户界面。
• 持久化存储: 将数据保存到磁盘，确保在应用会话之间保持数据持久性。每个集合的数据都存储在单独的 JSON 文件中。
• 多集合支持: 支持在一个 Nest 数据库实例中管理多个独立的集合。
• 可选加密: 提供可选的数据加密以增强安全性。
• 简单的 API: 提供直观的 API 进行 CRUD（创建、读取、更新、删除）操作以及更高级的查询。

开始使用

1. 安装

在 pubspec.yaml 中添加 nest_db 依赖：

dependencies:
  nest_db: <最新版本>

2. 导入

在 Dart 文件中导入 nest_db 包：

import 'package:nest_db/nest_db.dart';

3. 初始化

在使用之前初始化 Nest DB，最好在主函数中进行初始化：

void main() async {
  WidgetsFlutterBinding.ensureInitialized(); // 确保 Flutter 已初始化
  final db = Nest();
  await db.initialize('your_encryption_key'); // 可选的加密密钥
  runApp(MyApp());
}

如果不需要加密，可以传递空字符串：

await db.initialize(''); // 无加密

4. 创建集合和定义模式

创建集合并定义模式以强制执行数据结构。模式是可选的，但强烈推荐用于数据完整性。

final userSchema = Schema({
  'id': FieldType(type: String, isRequired: true),
  'name': FieldType(type: String),
  'age': FieldType(type: int),
  'email': FieldType(type: String),
  'address': FieldType(type: Map),
});

await db.createCollection('users', userSchema);

5. 执行 CRUD 操作

获取特定集合的 CollectionManager 实例：

final usersCollection = db.getCollection('users');
final productsCollection = db.getCollection('products');

if (usersCollection == null || productsCollection == null) {
  // 处理集合不存在的情况
  return;
}

创建（写入）

await usersCollection.write('1', {
  id: '1',
  name: 'Alice',
  age: 30,
  email: 'alice@example.com',
  address: {
    street: {
      name: "Main St",
      number: 123
    },
    city: "New York"
  }
});

读取

final user = await usersCollection.read('1');
print(user?.data); 

// 输出:
{
  id: "1",
  name: "Alice",
  age: 30,
  email: "alice@example.com",
  createdAt: ..., // 实际日期对象
  updatedAt: ...  // 实际日期对象
}

更新

await usersCollection.update('1', {
  age: 31,
  email: '[email address removed]',
  address: {
    street: {
      name: "Main St",
      number: 124
    },
    city: "New York"
  }
});

删除

await usersCollection.delete('your-doc-id');

6. 高级查询

投影

仅检索文档中的特定字段：

final documents = {
  "1": {"name": "Alice", "age": 25, "city": "New York"},
  "2": {"name": "Bob", "occupation": "Software Engineer"},
  "3": {"name": "Charlie", "age": 30}, // 缺少 "city" 字段
};
final schema = Schema({}); // 假模式
final collectionManager = CollectionManager('users', documents, schema);

// 仅投影 "name" 和 "age" 字段
final nameAgeProjections = collectionManager.project(fields: ["name", "age"]);
print(nameAgeProjections);
// 输出:
[
  {"id": "1", "name": "Alice", "age": 25},
  {"id": "2", "name": "Bob"}, // 缺少 "age" 字段
  {"id": "3", "name": "Charlie", "age": 30},
]

// 仅投影 "name" 字段
final nameProjections = collectionManager.project(fields: ["name"]);
print(nameProjections);
// 输出:
[
  {"id": "1", "name": "Alice"},
  {"id": "2", "name": "Bob"},
  {"id": "3", "name": "Charlie"},
]

存在查询

检查字段是否存在于文档中：

final documents = {
  "1": {"name": "Alice", "age": 25},
  "2": {"name": "Bob"}, // 缺少 "age" 字段
  "3": {"name": "Charlie", "age": 30},
};
final schema = Schema({}); // 假模式
final collectionManager = CollectionManager('users', documents, schema);

// 查找包含 "age" 字段的用户
final withAge = collectionManager.existsQuery("age");
print(withAge);

// 输出:
[{"name": "Alice", "age": 25}, {"name": "Charlie", "age": 30}]

// 查找不包含 "age" 字段的用户
final withoutAge = collectionManager.existsQuery("age", exists: false);
print(withoutAge);

// 输出:
[{"name": "Bob"}]

// 查找包含 "city" 字段的用户
final withCity = collectionManager.existsQuery("city");
print(withCity);

// 输出:
[]

通配符查询

搜索字段匹配通配符模式的文档：

final documents = {
  "1": {"name": "Alice Wonderland"},
  "2": {"name": "Bob the Builder"},
  "3": {"name": "Charlie Chaplin"},
  "4": {"name": "David"},
  "5": {"name": null},
};
final schema = Schema({}); // 假模式
final collectionManager = CollectionManager('users', documents, schema);

// 查找名字以 "A" 开头的用户
final startsWithA = collectionManager.wildcardQuery("name", "A*");
print(startsWithA);

// 输出:
[{"name": "Alice Wonderland"}]

// 查找名字以 "er" 结尾的用户
final endsWithEr = collectionManager.wildcardQuery("name", "*er");
print(endsWithEr);

// 输出:
[{"name": "Bob the Builder"}]

// 查找名字包含 "li" 的用户
final containsLi = collectionManager.wildcardQuery("name", "*li*");
print(containsLi);

// 输出:
[{"name": "Alice Wonderland"}, {"name": "Charlie Chaplin"}]

// 查找所有名字
final allNames = collectionManager.wildcardQuery("name", "*");
print(allNames);

// 输出:
[
  {"name": "Alice Wonderland"},
  {"name": "Bob the Builder"},
  {"name": "Charlie Chaplin"},
  {"name": "David"},
  {"name": null}
]

// 查找名字为 null 的用户
final nullName = collectionManager.wildcardQuery("name", "");
print(nullName);

// 输出:
[{"name": null}]

嵌套字段查询

基于嵌套对象中的值查询文档：

final documents = {
  "1": {
    "address": {
      "street": {"name": "Main St", "number": 123},
      "city": "New York"
    }
  },
  "2": {
    "address": {
      "street": {"name": "Oak Ave", "number": 456},
      "city": "Los Angeles"
    }
  },
  "3": {"address": {"city": "Chicago"}}, // 缺少 "street"
  "4": {"name": "David"}, // 缺少 "address"
};
final schema = Schema({}); // 假模式
final collectionManager = CollectionManager('places', documents, schema);

// 查找位于 "Main St" 的地方
final mainStreetPlaces = collectionManager.nestedFieldQuery("address.street.name", "Main St");
print(mainStreetPlaces);

// 输出:
[{"address": {"street": {"name": "Main St", "number": 123}, "city": "New York"}}]

// 查找街道号为 456 的地方
final number456Places = collectionManager.nestedFieldQuery("address.street.number", 456);
print(number456Places);

// 输出:
[{"address": {"street": {"name": "Oak Ave", "number": 456}, "city": "Los Angeles"}}]

// 查找名字为 David 的地方
final davidPlaces = collectionManager.nestedFieldQuery("name", "David");
print(davidPlaces);

// 输出:
[{"name": "David"}]

响应式更新

监听集合的变化：

db.watchCollection('users').listen((change) {
  print('Users collection changed: $change');
});