Flutter数据封装与安全性插件sealed_annotations的使用

概述

sealed_annotations 是一个用于生成密封类层次结构的 Dart 和 Flutter 插件。它可以帮助开发者创建更安全和可维护的数据模型，支持多种特性如静态工厂方法、类型转换、数据平等性等。

主要特性

• 生成带有抽象超类和数据子类的密封类。
• 静态工厂方法，例如 Result.success(data: 0)。
• 类型转换方法，例如 a.asSuccess、a.isSuccess 或 a.asSuccessOrNull。
• 支持三种类型的平等性和哈希码生成：数据（类似 Kotlin 数据类）、身份和独特。
• 支持使用流行库 Equatable 实现数据平等性。
• 支持泛型，甚至可以混合不同类型。
• 支持在空安全项目中使用可空和不可空类型。
• 支持在一个密封类型中使用另一个密封类型。
• 支持空安全。
• 为数据类生成 toString 方法。
• 生成六种不同的匹配方法，如 when、maybeWhen 和 map。

使用示例

添加依赖

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

dependencies:
  sealed_annotations: ^latest.version

dev_dependencies:
  sealed_generators: ^latest.version

导入包

导入 sealed_annotations 包：

import 'package:sealed_annotations/sealed_annotations.dart';

添加部分文件

添加 part 指向您希望生成代码的文件，并使用 .sealed.dart 扩展名：

part 'weather.sealed.dart';

定义密封类

添加 @Sealed 注解和一个抽象私有类作为生成代码的清单。例如：

@Sealed()
abstract class _Weather {
  void sunny();

  void rainy(int rain);

  void windy(double velocity, double? angle);
}

生成代码

如果您是 Flutter 开发者，请运行以下命令来生成代码：

flutter pub run build_runner build

如果是纯 Dart 项目，则运行：

dart run build_runner build

生成的代码将类似于以下内容（以下是简化版本）：

abstract class Weather {
  const factory Weather.rainy({required int rain}) = WeatherRainy;

  bool get isRainy => this is WeatherRainy;

  WeatherRainy get asRainy => this as WeatherRainy;

  WeatherRainy? get asRainyOrNull {
    /* ... */
  }

  R when<R extends Object?>({
    required R Function() sunny,
    required R Function(int rain) rainy,
    required R Function(double velocity, double? angle) windy,
  }) {
    /* ... */
  }

  // 其他匹配方法...
}

class WeatherSunny extends Weather {
  /* ... */
}

class WeatherRainy extends Weather with EquatableMixin {
  WeatherRainy({required this.rain});

  final int rain;

  @override
  String toString() => 'Weather.rainy(rain: $rain)';

  @override
  List<Object?> get props => [rain];
}

class WeatherWindy extends Weather {
  /* ... */
}

示例代码

以下是一个完整的示例代码，展示如何使用生成的密封类：

// result.dart
@Sealed()
abstract class _Result<D extends num> {
  void success(D data);

  void error(Object exception);
}

// weather.dart
@Sealed()
abstract class _Weather {
  void sunny();

  void rainy(int rain);

  void windy(double velocity, double? angle);
}

void main() {
  final a = Weather.sunny();
  final b = Weather.rainy(rain: 12);
  final c = Weather.windy(velocity: 1.5, angle: null);

  print(a);
  print(b);
  print(c);

  final d = Result<num>.success(data: 1);
  final e = Result<double>.success(data: 5.6);
  final f = Result.error(exception: 'error');

  print(d);
  print(e);
  print(f);
}

注意事项

• 尽量使用超类中的工厂方法而不是子类构造函数，例如使用 Whether.rainy() 而不是 WhetherRainy()。
• 尽量减少使用类型转换方法，大多数情况下可以用匹配方法替代。

总结

通过使用 sealed_annotations 插件，您可以更方便地在 Flutter 和 Dart 项目中实现数据封装和安全性。该插件提供了丰富的功能，帮助您创建更健壮和可维护的代码。请根据您的需求选择合适的配置和注解，以充分利用其功能。