Flutter未知功能插件snail的使用

🐌 Snail: A Simple ORM-like Library for Flutter/Dart 🐦

Snail 是一个受 Spring Boot 的 JPA 启发，旨在简化 Flutter/Dart 应用程序中 SQLite 数据库管理的库。它的使用像蜗牛一样简单（但功能强大如火箭）！

✨ 特性

• ✅ 增删改查（CRUD）操作。
• 🔍 基于方法命名约定的动态查询方法。
• 🛠️ 根据字段定义创建表。
• 🔄 实体与数据库行之间的自动映射。
• 🔗 支持 snake_case 和 camelCase 转换。
• 📜 分页、排序和过滤支持。

📥 安装

在 pubspec.yaml 中添加以下依赖：

dependencies:
  snail: ^1.1.2

Getting Started 🏁

创建仓库 📦

要为您的模型创建一个仓库，请扩展 SnailRepository 类：

import 'package:snail/snail.dart';

class UserRepository extends SnailRepository<User, int> {
  UserRepository() : super(
    tableName: 'users',
    primaryKeyColumn: 'id',
    defineFields: {
      'id': int,
      'name': String,
      'email': String,
      'isActive': bool,
    },
  );

  @override
  Map<String, dynamic> toMap(User entity) => entity.toMap();

  @override
  User fromMap(Map<String, dynamic> map) => User.fromMap(map);
}

class User {
  final int id;
  final String name;
  final String email;
  final bool isActive;

  User({
    required this.id,
    required this.name,
    required this.email,
    required this.isActive,
  });

  Map<String, dynamic> toMap() {
    return {
      'id': id,
      'name': name,
      'email': email,
      'isActive': isActive,
    };
  }

  factory User.fromMap(Map<String, dynamic> map) {
    return User(
      id: map['id']?.toInt() ?? 0,
      name: map['name'] ?? '',
      email: map['email'] ?? '',
      isActive: map['isActive'] ?? false,
    );
  }
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await Snail.initialize(
    repositories: [
      UserRepository(),
    ],
  );

  runApp(AppWidget());
}

使用仓库 🔧

void main() async {
  final userRepository = UserRepository();

  // Save a user
  await userRepository.save(User(id: 1, name: 'John Doe', email: 'john@example.com', isActive: true));

  // Find a user by ID
  final user = await userRepository.findById(1);

  // Find all users
  final users = await userRepository.findAll();

  // Delete a user
  await userRepository.deleteById(1);
}

动态方法 🔍

dynamicMethod 允许根据方法命名构造 SQL 查询。命名结构应遵循标准约定：

命名结构 🛠️

• 前缀: find 或 findAll
• 连接词: And, Or
• 操作符: Between, LessThan, GreaterThan, Like, StartingWith, EndingWith, Containing, In, NotIn, OrderBy, True, False, IsNull, NotNull

示例命名约定 📖

findByTitle(String title);
findById(int id);
findByTitleAndDescription(String title, String description);
findByTitleOrDescription(String title, String description);
findByTitleStartingWith(String title);
findByTitleEndingWith(String title);
findByTitleContaining(String title);
findByIdLessThan(int id);
findByIdGreaterThan(int id);
findByDateBetween(DateTime startDate, DateTime endDate);
findByTitleStartingWithAndIdLessThan(String title, int id);
findByTitleContainingOrDescriptionLike(String title, String description);
findByIdIn(List<int> ids);
findByIdNotIn(List<int> ids);
findByTitleOrderByDate(String title);
findByTitleOrderByDateDesc(String title);
findByTitleAndDescriptionOrderByDate(String title, String description);
findByIsActiveTrue();
findByIsActiveFalse();
findByTitleIsNull();
findByTitleNotNull();

使用示例 📝

Future<List<User>> findByTitleStartingWith(String title) {
  return dynamicMethod('findByTitleStartingWith', [title]);
}

过滤器：分页、排序和大小 📊

Snail 支持通过 size、page 和 sort 参数进行额外过滤：

• size: 每页获取的记录数。例如：size: 20。
• page: 获取的页码。例如：page: 1（如果 size 设置为 20，则获取前 20 条记录）。
• sort: 排序顺序。使用格式 <field>,<order>，其中 <order> 可以是 asc 或 desc。例如：sort: 'createdAt,asc'。

默认情况下，如果没有指定排序，Snail 会应用降序排序 (createdAt,desc)。

示例用法 📝

Future<List<User>> findAllUsersWithPagination() async {
  return await userRepository.findAll(
    size: 20,
    page: 1,
    sort: 'createdAt,asc',
  );
}

CRUD 操作 ⚙️

保存或更新实体 💾

Future<int> save(T entity);

保存或更新多个实体 💾💾

Future<List<int>> saveAll(List<T> entities);

按 ID 查找实体 🔍

Future<T?> findById(ID id);

查找所有实体 🔎

Future<List<T>> findAll({int? size, int? page, String? sort});

按 ID 删除实体 🗑️

Future<int> deleteById(ID id);

删除所有实体 🗑️🗑️

Future<int> deleteAll(List<T>? entities);

统计实体数量 🔢

Future<int> count();

自动字段：createdAt 和 updatedAt 🕒

Snail 自动为所有模型添加 createdAt 和 updatedAt 字段。这些字段跟踪记录的创建时间和最后更新时间。

在模型中的可选使用 📌

如果您希望在模型中显式包含这些字段，可以将它们定义为可选：

class TodoModel {
  final String id;
  final String title;
  final bool isCompleted;
  final DateTime? createdAt;
  final DateTime? updatedAt;

  TodoModel({
    required this.id,
    required this.title,
    this.isCompleted = false,
    this.createdAt,
    this.updatedAt,
  });

  Map<String, dynamic> toMap() {
    return {
      'id': id,
      'title': title,
      'isCompleted': isCompleted,
      'createdAt': createdAt,
      'updatedAt': updatedAt,
    };
  }

  factory TodoModel.fromMap(Map<String, dynamic> map) {
    return TodoModel(
      id: map['id'] as String,
      title: map['title'] as String,
      isCompleted: map['isCompleted'] as bool,
      createdAt: map['createdAt'] as DateTime?,
      updatedAt: map['updatedAt'] as DateTime?,
    );
  }
}

Full API 📚

以下是 Snail Repository 提供的完整方法列表：

Contributing 🤝

欢迎提交拉取请求贡献代码！您的贡献非常宝贵！💡

License 📜

本项目采用 MIT 许可证。

Made with ❤️ for Flutter developers! 🎯