Flutter架构插件supa_architecture的使用

Flutter架构插件supa_architecture的使用

概述

supa_architecture库通过提供干净的架构和预构建的功能来增强您的Flutter项目。

目录

• supa_architecture库
• 安装
• 兼容性
• 使用
• 示例
• 贡献
• 许可证

安装

要将库添加到Flutter项目中，请更新pubspec.yaml文件：

dependencies:
  supa_application: ^1.0.0

兼容性

supa_architecture包旨在支持多个平台。然而，某些功能依赖于底层平台特定的实现，这可能会限制在某些平台上的功能。以下是功能兼容性的摘要：

• OAuth: aad_oauth 和 sign_in_with_apple 提供了对移动设备和macOS的强大支持，但在web和桌面端的支持有限或不可用。
• 安全存储: flutter_secure_storage 在Windows上不支持，但在不受支持的平台上可以使用类似shared_preferences的替代方案。
• 生物识别认证: local_auth 在移动设备和macOS上受支持，但在web、Windows和Linux上不支持。

对于跨平台开发，确保使用条件导入或平台检查来处理平台特定的限制。对于特定平台上的不受支持的功能，请考虑使用替代实现。

使用

ApiClient

ApiClient类用于处理HTTP请求。以下是如何初始化它并进行HTTP请求的示例：

// 初始化ApiClient
final client = ApiClient(baseUrl: "https://api.example.com");

// 发起GET请求
client.get("/users").then((response) {
  print(response.data);
}).catchError((error) {
  print("Error: $error");
});

Blocs

Authentication Bloc

AuthenticationBloc用于管理用户身份验证。以下是初始化和使用的示例：

// 初始化AuthenticationBloc
final authBloc = AuthenticationBloc();

// 登录事件
authBloc.add(Login(email: "user@example.com", password: "password"));

// 注销事件
authBloc.add(Logout());

Tenant Bloc

TenantBloc用于处理多租户逻辑。以下是初始化和使用的示例：

// 初始化TenantBloc
final tenantBloc = TenantBloc();

// 切换租户事件
tenantBloc.add(SwitchTenant(tenantId: "tenant-id"));

常量

列出并描述可用的常量，例如日期时间格式。

const dateTimeFormat = "yyyy-MM-dd HH:mm:ss";

数据模型

提供内置数据模型类的概述，包括关键类及其用途。以下是示例使用：

class User extends JsonModel {
  int id;
  String name;
  DateTime createdAt;

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

  @override
  void fromJSON(Map<String, dynamic> json) {
    id = json['id'];
    name = json['name'];
    createdAt = DateTime.parse(json['createdAt']);
  }

  @override
  Map<String, dynamic> toJSON() {
    return {
      'id': id,
      'name': name,
      'createdAt': createdAt.toIso8601String(),
    };
  }
}

异常

描述库中定义的自定义异常及其用法。

class CustomException implements Exception {
  final String message;

  CustomException(this.message);

  @override
  String toString() {
    return message;
  }
}

扩展

列出Dart/Flutter类扩展及其好处。

extension StringExtension on String {
  String capitalize() {
    return "${this[0].toUpperCase()}${substring(1)}";
  }
}

过滤器

DataFilter

DataFilter类提供了过滤和查询数据的结构。它支持分页、排序和基本的过滤操作。它设计为与包含过滤标准的FilterField对象列表一起使用。

final filter = DataFilter(
  skip: 0,
  take: 10,
  orderBy: "name",
  orderType: "ASC",
  search: "search term",
  viewCode: "view-code"
);

print(filter.toString()); // 输出JSON字符串表示形式

FilterField

FilterField类是特定过滤类型的基础类。它包括常见的过滤操作作为常量，并实现了JSON序列化和反序列化。

final filterField = FilterField(
  name: "email",
  operation: FilterField.equal,
  value: "user@example.com"
);

print(filterField.toString()); // 输出JSON字符串表示形式

AbstractIdFilter<T>

AbstractIdFilter类提供了过滤ID字段的操作。它允许按特定ID过滤、排除ID或处理ID列表。

final idFilter = GuidFilter(
  equal: "123e4567-e89b-12d3-a456-426614174000"
);

print(idFilter.toJSON()); // 输出JSON表示形式

AbstractNumberFilter<T>

AbstractNumberFilter类提供了过滤数字字段的操作。它支持大于、小于、等于和不等于等操作。

final numberFilter = NumberFilter<int>(
  greaterEqual: 10,
  lessEqual: 20,
  equal: 15
);

print(numberFilter.toJSON()); // 输出JSON表示形式

DateFilter

DateFilter类扩展AbstractNumberFilter以支持DateTime字段的过滤。它使用日期时间值进行操作，并将其转换为ISO 8601字符串格式。

final dateFilter = DateFilter(
  greaterEqual: DateTime.now().subtract(Duration(days: 30)),
  lessEqual: DateTime.now()
);

print(dateFilter.toJSON()); // 输出带有日期时间值的JSON表示形式

DoubleFilter, IntFilter, NumberFilter

这些类分别扩展AbstractNumberFilter以支持特定类型的数字：

final doubleFilter = DoubleFilter<double>(greater: 10.5);

print(doubleFilter.toJSON()); // 输出JSON表示形式

GuidFilter

GuidFilter类扩展AbstractIdFilter以支持String类型的ID（通常用于GUID）。

final guidFilter = GuidFilter(
  equal: "123e4567-e89b-12d3-a456-426614174000"
);

print(guidFilter.toJSON()); // 输出JSON表示形式

StringFilter

StringFilter类提供了过滤字符串字段的操作。它包括相等性、包含性和字符串匹配等操作。

final stringFilter = StringFilter(
  equal: "user@example.com",
  contain: "example"
);

print(stringFilter.toJSON()); // 输出JSON表示形式

JSON处理

json.dart文件提供了一种强大的机制，用于使用一系列类和接口处理JSON序列化和反序列化。这种方法确保了类型安全和轻松地在JSON数据和Dart对象之间转换。

JsonField<T>

抽象类，代表JSON对象中的一个字段。

class MyField extends JsonField<int> {
  @override
  int value() {
    return 42;
  }

  @override
  Map<String, dynamic> toJSON() {
    return {"myField": value()};
  }
}

JsonBoolean

具体类，用于处理布尔值。

class MyBoolean extends JsonBoolean {
  MyBoolean(String fieldName) : super(fieldName);

  @override
  bool value() {
    return true;
  }
}

JsonDate

具体类，用于处理DateTime值。

class MyDate extends JsonDate {
  MyDate(String fieldName) : super(fieldName);

  @override
  DateTime value() {
    return DateTime.now();
  }
}

JsonList<T>

泛型类，用于处理JsonModel对象的列表。

class MyList extends JsonList<MyModel> {
  MyList(String fieldName, InstanceConstructor<MyModel> type) : super(fieldName, type);

  @override
  List<MyModel> value() {
    return [MyModel(), MyModel()];
  }
}

JsonModel

抽象类，表示可以序列化/反序列化为JSON的模型。

class MyModel extends JsonModel {
  int id;
  String name;

  MyModel({required this.id, required this.name});

  @override
  void fromJSON(Map<String, dynamic> json) {
    id = json['id'];
    name = json['name'];
  }

  @override
  Map<String, dynamic> toJSON() {
    return {
      'id': id,
      'name': name,
    };
  }
}

JsonNumber

具体类，用于处理数值。

class MyNumber extends JsonNumber {
  MyNumber(String fieldName) : super(fieldName);

  @override
  num value() {
    return 42;
  }
}

JsonObject<T>

泛型类，用于处理继承JsonModel的复杂对象。

class MyObject extends JsonObject<MyModel> {
  MyObject(String fieldName, InstanceConstructor<MyModel> type) : super(fieldName, type);

  @override
  MyModel value() {
    return MyModel(id: 1, name: "Test");
  }
}

JsonSerializable

用于支持JSON序列化和反序列化的mixin。

class MySerializableClass with JsonSerializable {
  int id;
  String name;

  MySerializableClass({required this.id, required this.name});

  @override
  void fromJSON(Map<String, dynamic> json) {
    id = json['id'];
    name = json['name'];
  }

  @override
  Map<String, dynamic> toJSON() {
    return {
      'id': id,
      'name': name,
    };
  }
}

JsonString

具体类，用于处理字符串值。

class MyString extends JsonString {
  MyString(String fieldName) : super(fieldName);

  @override
  String value() {
    return "Hello World";
  }
}

存储库

提供存储库类的概述，包括：

• 认证
• 多租户
• Cookies
• 持久数据
• 安全存储

服务

描述库提供的服务，包括：

• 逻辑处理
• Cookie管理
• 安全性

小部件

解释提供的可重用小部件，包括：

• 关键小部件
• 使用示例

SupaApplication

详细说明主类SupaApplication，包括：

• 它的目的
• 如何与其他部分的库集成

示例

查看包示例：

example/example.md