Flutter密封类生成插件sealed_class_creators的使用

Dart密封类生成器

用于生成Dart和Flutter中的密封类层次结构。

特性

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

使用方法

在你的 pubspec.yaml 文件中添加依赖：

dependencies:
  sealed_class_annotations: ^latest.version

dev_dependencies:
  sealed_class_creators: ^latest.version

导入 sealed_class_annotations：

import 'package:sealed_class_annotations/sealed_class_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,
  }) {
    /* ... */
  }

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

  R? whenOrNull<R extends Object?>({
    R Function()? sunny,
    R Function(int rain)? rainy,
    R Function(double velocity, double? angle)? windy,
    R Function(Weather weather)? orElse,
  }) {
    /* ... */
  }

  R map<R extends Object?>({
    required R Function(WeatherSunny sunny) sunny,
    required R Function(WeatherRainy rainy) rainy,
    required R Function(WeatherWindy windy) windy,
  }) {
    /* ... */
  }

  R maybeMap<R extends Object?>({
    R Function(WeatherSunny sunny)? sunny,
    R Function(WeatherRainy rainy)? rainy,
    R Function(WeatherWindy windy)? windy,
    required R Function(Weather weather) orElse,
  }) {
    /* ... */
  }

  R? mapOrNull<R extends Object?>({
    R Function(WeatherSunny sunny)? sunny,
    R Function(WeatherRainy rainy)? rainy,
    R Function(WeatherWindy windy)? windy,
    R Function(Weather weather)? orElse,
  }) {
    /* ... */
  }
}

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 {
  /* ... */
}

注意事项：

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

相等性和生成类名

你可以使用 @WithEquality(...) 注解选择三种类型的相等性之一。默认相等性是 data，如果没有指定。这将变成所有子类的默认相等性。你可以在单个方法上使用此注解以更改每个子类的相等性。

相等性类型：

• data：使用Equatable包实现相等性。行为类似于Kotlin的数据类。
• identity：只有相同实例才相等。类似于不实现任何特定相等性的行为。
• distinct：所有实例都不相等。即使实例也不等于自身。

基本示例：

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

  void rainy(int rain);

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

在这个例子中，所有类都将具有 data 相等性。如果你想让所有类都具有 identity 相等性，但 windy 具有 distinct 相等性：

@Sealed()
@WithEquality(Equality.identity)
abstract class _Weather {
  void sunny();

  void rainy(int rain);

  @WithEquality(Equality.distinct)
  void windy(double velocity, double? angle);
}

生成的抽象超类名称与清单类名称相同（这里为 Weather）。每个方法都会成为子类。应该至少有一个方法。子类名称基于方法名称并前缀为超类名称（例如 WeatherSunny）。命名过程可以通过使用 @WithPrefix 和 @WithName 注解进行调整。每个方法参数都会成为相应子类中的字段。字段名称与参数名称相同，字段类型与参数类型相同或为 dynamic 如果未指定。可以通过 @WithType 注解覆盖参数类型，例如在构建时无法获得类型信息时。请注意，你可以有可空和不可空字段。

要更改子类名称的前缀（默认为顶层类名称），可以使用 @WithPrefix 注解。例如：

@Sealed()
@WithPrefix('Hello')
abstract class _Weather {
  void sunny();
}

现在 sunny 将被命名为 HelloSunny 而不是默认的 WeatherSunny。你可以使用 @WithPrefix('') 删除所有子类名称前缀。

要直接更改子类名称，可以使用 @WithName 注解。它会覆盖 @WithPrefix 注解。例如：

@Sealed()
abstract class _Weather {
  @WithName('Hello')
  void sunny();
}

现在 sunny 将被命名为 Hello 而不是默认的 WeatherSunny。这对于不想在某些项上使用前缀非常有用。

几乎所有密封类上的方法都使用从清单方法名称提取的短名称。不使用完整的子类名称。建议不要直接使用子类。超类上有每个项目的工厂方法。

泛型使用

对于泛型密封类，你应该像实现通用类一样编写清单类。

建议如果要声明可空的泛型字段，则应将泛型参数声明为 T extends Base? 并使用 T 而不带可空后缀。如果要声明不可空的泛型字段，则应将泛型参数声明为 T extends Base 并使用 T 而不带可空后缀。如果不指定上限，默认为 Object? 所以你的泛型类型将是可空的。

import 'package:sealed_class_annotations/sealed_class_annotations.dart';

part 'result.sealed.dart';

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

  void error(Object exception);
}

或者你可以有多个泛型类型并混合它们。

import 'package:sealed_class_annotations/sealed_class_annotations.dart';

part 'result.sealed.dart';

@Sealed()
abstract class _Result<D extends num, E extends Object> {
  void success(D data);

  void error(E exception);

  void mixed(D data, E exception);
}

动态类型和在一个密封类型中使用另一个密封类型

假设你有一个密封结果类型，如下所示：

@Sealed()
abstract class _Result<D extends Object> {
  /* ... */
}

你想在另一个密封类型中使用这个类型。

@Sealed()
abstract class _WeatherInfo {
  void fromInternet(Result<WeatherData> result);
}

如果你为 WeatherInfo 生成代码，你会看到结果具有 dynamic 类型。这是因为 Result 本身在构建时未被代码生成。

你应该使用 @WithType 注解。

@Sealed()
abstract class _WeatherInfo {
  void fromInternet(@WithType('Result<WeatherData>') result);

  // 你也可以有可空类型。
  void nullable(@WithType('Result<WeatherData>?') result);
}

层次结构特性

如果密封类在同一文件中，你可以直接引用它们，以避免 @WithType 注解并提高重构能力。

@Sealed()
abstract class _Apple {
  void eat();
}

@Sealed()
abstract class _Banana {
  void eat();
}

@Sealed()
abstract class _Basket {
  void friends(_Apple? apple, _Banana? banana);

// 或者等效地：
// void friends(@WithType('Apple?') apple, @WithType('Banana?') banana);
}

对于泛型情况：

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

  void error(Object exception);
}

@Sealed()
abstract class _Basket {
  void hold(_Result<int> x);

// 或者等效地：
// void hold(@WithType('Result<int>') x);
}

@WithType 注解会覆盖层次结构特性。

公共字段

有时你需要一些字段存在于所有的密封类中。例如考虑制作一个不同错误类型的密封类，并且所有错误都需要有 code 和 message。手动将 code 和 message 添加到所有密封类中是非常烦人的。而且如果你有一个错误对象，你无法在不使用类型转换或匹配方法的情况下获取其代码或消息。这里可以使用公共字段。

要声明一个公共字段，可以在清单类中添加一个getter或final字段，它将自动添加到所有密封类中。例如：

@Sealed()
abstract class _ApiError {
  // 使用getter
  String get message;

  // 使用final字段
  final String? code = null;

  // code和message将自动添加到这里
  void internetError();

  void badRequest();

  void internalError(Object? error);
}

你也可以与final字段一起使用构造函数等效地实现。

公共字段在 ApiError 对象及其子类中都是可用的。

如果你在密封类中指定了公共字段，将不会产生效果。例如：

@Sealed()
abstract class _Common {
  Object get x;

  // one和two将有相同的签名
  void one(Object x);

  void two();
}

你可以在密封类中使用公共字段类型的子类。例如：

@Sealed()
abstract class _Common {
  Object get x;

  // x的类型是int
  void one(int x);

  // x的类型是String
  void one(String x);

  // x的类型是Object
  void three();
}

公共字段也适用于其他Dart密封构造，如泛型和 @WithType。例如：

@Sealed()
abstract class _Common {
  @WithType('num')
  dynamic get x; // 你可以省略dynamic

  // x的类型是int
  void one(@WithType('int') dynamic x); // 你可以省略dynamic

  // x的类型是num
  void two();
}

例如：

@Sealed()
abstract class _Result<D extends num> {
  Object? get value;

  void success(D value);

  void error();
}

忽略生成的文件

建议在Git中忽略生成的文件。在你的 .gitignore 文件中添加以下内容：

*.sealed.dart

为了排除分析中的生成文件，在你的 analysis_options.yaml 文件中添加以下内容：

analyzer:
  exclude:
    - lib/**/*.sealed.dart

示例代码

import 'result.dart';
import 'weather.dart';

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.success(data: 1);
  final e = Result.success(data: 5.6);
  final f = Result.error(exception: 'error');

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