Flutter CQRS架构与Cubit工具插件leancode_cubit_utils_cqrs的使用

要求

1. 参考提供的内容和示例代码回答此问题。
2. 提供完整的示例Demo。
3. 不添加无用图片。
4. 将英文介绍转换为简体中文。
5. 保留代码不进行翻译。
6. 添加必要的注释。

需求

cqrs: ">=10.0.1"

安装

在项目中添加依赖：

flutter pub add leancode_cubit_utils_cqrs

导入包：

import 'package:leancode_cubit_utils_cqrs/leancode_cubit_utils_cqrs.dart';

使用

leancode_cubit_utils_cqrs 包包含了一个完整的实现，用于处理CQRS查询的cubits。这些实现适用于单个请求工具和分页工具。

单个请求工具

QueryCubit

QueryCubit 用于执行单个CQRS查询。以下是 QueryCubit 的示例实现：

class ProjectDetailsCubit extends QueryCubit<ProjectDetailsDTO, ProjectDetailsDTO> {
  ProjectDetailsCubit({
    required this.cqrs,
    required this.id,
  }) : super('ProjectDetailsCubit');

  final Cqrs cqrs;
  final String id;

  [@override](/user/override)
  // 将给定的TRes映射到TOut。在这种情况下，我们不想改变它，所以直接返回数据。
  ProjectDetailsDTO map(ProjectDetailsDTO data) => data;

  [@override](/user/override)
  // 在此方法中执行查询并以QueryResult<TRes>的形式返回结果。QueryResult<TRes>由QueryCubit内部处理。
  Future<QueryResult<ProjectDetailsDTO>> request() {
    return cqrs.get(ProjectDetails(id: id));
  }
}

ArgsQueryCubit

ArgsQueryCubit<TArgs, TRes, TOut> 是一个接受参数的 QueryCubit 版本。TArgs 确定了请求方法接受的参数类型。TRes 和 TOut 的作用与 QueryCubit 相同。

使用QueryCubit和UseArgsQueryCubit

有时，没有必要对查询响应进行任何映射。这种情况下，没有必要实现扩展 QueryCubit 或 ArgsQueryCubit 的cubit。相反，可以使用提供的钩子之一 useQueryCubit 或 useArgsQueryCubit。只需提供要执行的请求，然后就可以像通过 RequestCubitBuilder 传递它一样使用该cubit。

final queryCubit = useQueryCubit(
    () => cqrs.get(ProjectDetails(id: id)),
);

final argsQueryCubit = useArgsQueryCubit(
    (args) => cqrs.get(AllProjects(sortByNameDescending: args.isDescending)),
);

可以通过传递可选参数来配置 requestMode 和 loggerTag。在 useQueryCubit 中，还可以通过传递 callOnCreate 标志来定义是否立即调用请求。

分页工具

分页工具是为了简化创建主元素为分页列表的页面而设计的。

PaginatedQueryCubit

PaginatedQueryCubit<TData, TRes, TItem> 是一种用于CQRS的分页cubit实现。它用于处理检索分页列表下一页的逻辑。它有三个泛型参数：

• TData 表示我们希望存储和处理的附加数据。
• TRes 表示从API返回项目的结构。
• TItem 对应于计划在页面上显示的单个列表项模型（经过潜在转换）。

以下是 PaginatedQueryCubit 的示例实现：

class IdentitiesCubit extends PaginatedQueryCubit<void, PaginatedResult<KratosIdentityDTO>, KratosIdentityDTO> {
  IdentitiesCubit({
    super.config,
    required this.cqrs,
  }) : super(loggerTag: 'IdentitiesCubit');

  final Cqrs cqrs;

  [@override](/user/override)
  Future<QueryResult<PaginatedResult<KratosIdentityDTO>>> requestPage(
    PaginatedArgs args,
  ) {
    return cqrs.get(
      // 查询获取下一页
      SearchIdentities(
        pageSize: args.pageSize,
        pageNumber: args.pageNumber,
        emailPattern: args.searchQuery,
      ),
    );
  }

  [@override](/user/override)
  PaginatedResponse<void, KratosIdentityDTO> onPageResult(
    PaginatedResult<KratosIdentityDTO> page,
  ) {
    // 使用cubit方法计算是否有下一页
    final args = state.args;
    final hasNextPage = calculateHasNextPage(
      pageNumber: args.pageNumber,
      totalCount: page.totalCount,
    );

    // 返回带有下一页的响应
    return PaginatedResponse.append(
      items: page.items,
      hasNextPage: hasNextPage,
    );
  }
}

需要实现两个方法的主体：requestPage 和 onPageResult。在第一个方法中执行请求并返回其结果。在第二个方法中，需要处理结果并以 PaginatedResponse 的形式返回它。

预请求

预请求允许你在请求第一页之前执行操作。例如，这可以用于获取可用过滤器。

QueryPreRequest

QueryPreRequest 是一个专为CQRS设计的预请求实现类。要利用此功能提供的预请求功能，创建一个扩展 QueryPreRequest 的类。

class FiltersPreRequest extends QueryPreRequest<List<Filter>, List<Filter>, User> {
  FiltersPreRequest({required this.cqrs});

  final Cqrs cqrs;

  [@override](/user/override)
  Future<QueryResult<List<Filter>>> request(PaginatedState<List<Filter>, User> state) {
    return api.getFilters();
  }

  [@override](/user/override)
  List<Filter> map(
    List<Filter> res,
    PaginatedState<List<Filter>, User> state,
  ) {
    return res;
  }
}

然后需要在 PaginatedCubit 构造函数中创建定义的 FiltersPreRequest 实例。

class IdentitiesCubit extends PaginatedQueryCubit<List<Filter>, PaginatedResult<KratosIdentityDTO>, KratosIdentityDTO> {
  IdentitiesCubit({
    super.config,
    preRequest: FiltersPreRequest(cqrs: cqrs), // 这里
    required this.cqrs,
  }) : super(loggerTag: 'IdentitiesCubit');

  /* IdentitiesCubit 的其余实现 */
}

示例

以下是一个完整的示例，展示了如何使用 leancode_cubit_utils_cqrs 包：

import 'dart:developer';

import 'package:cqrs/cqrs.dart';
import 'package:example/cqrs/cqrs.dart';
import 'package:example/pages/home_page.dart';
import 'package:example/pages/paginated/paginated_cubit_page.dart';
import 'package:example/pages/query/query_page.dart';
import 'package:flutter/material.dart';
import 'package:leancode_cubit_utils_cqrs/leancode_cubit_utils_cqrs.dart';
import 'package:logging/logging.dart';
import 'package:provider/provider.dart';

class Routes {
  static const home = '/';
  static const simpleQuery = '/simple-query';
  static const simpleQueryHook = '/simple-query-hook';
  static const paginatedCubit = '/paginated-cubit';
}

void _setupLogger() {
  Logger.root.level = Level.ALL;

  Logger.root.onRecord.listen(
    (record) => log(
      record.message,
      time: record.time,
      sequenceNumber: record.sequenceNumber,
      level: record.level.value,
      name: record.loggerName,
      zone: record.zone,
      error: record.error,
      stackTrace: record.stackTrace,
    ),
  );

  FlutterError.onError = (details) {
    FlutterError.dumpErrorToConsole(details);
  };
}

void main() {
  final cqrs = createMockedCqrs();

  _setupLogger();

  runApp(
    Provider<Cqrs>.value(
      value: cqrs,
      child: PaginatedLayoutConfigProvider(
        onFirstPageLoading: (context) => const Center(
          child: CircularProgressIndicator(),
        ),
        onFirstPageError: (context, error, retry) => Error(
          retry: retry,
          error: error,
        ),
        onNextPageLoading: (context) => const Center(
          child: CircularProgressIndicator(),
        ),
        onNextPageError: (context, error, retry) => Error(
          retry: retry,
          error: error,
        ),
        onEmptyState: (context) => const Center(child: Text('No items')),
        child: RequestLayoutConfigProvider(
          requestMode: RequestMode.replace,
          onLoading: (BuildContext context) =>
              const CircularProgressIndicator(),
          onError: (
            BuildContext context,
            RequestErrorState<dynamic, dynamic> error,
            VoidCallback? onErrorCallback,
          ) =>
              const Text(
            'Error',
            style: TextStyle(color: Colors.red),
          ),
          child: const MainApp(),
        ),
      ),
    ),
  );
}

class MainApp extends StatelessWidget {
  const MainApp({super.key});

  [@override](/user/override)
  Widget build(BuildContext context) => MaterialApp(
        routes: <String, WidgetBuilder>{
          Routes.home: (_) => const HomePage(),
          Routes.simpleQuery: (_) => const QueryScreen(),
          Routes.simpleQueryHook: (_) => const QueryHookScreen(),
          Routes.paginatedCubit: (_) => const PaginatedCubitScreen(),
        },
      );
}

class Error extends StatelessWidget {
  const Error({
    super.key,
    this.retry,
    required this.error,
  });

  final VoidCallback? retry;
  final Object? error;

  [@override](/user/override)
  Widget build(BuildContext context) => retry != null
      ? Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text(error.toString()),
            ElevatedButton(onPressed: retry, child: const Text('Retry')),
          ],
        )
      : Text(error.toString());
}