HydratedCubit Brick 完整指南：用 Mason 一键生成可持久化 Cubit

前端【免费下载链接】blocA predictable state management library that helps implement the BLoC design pattern项目地址https://gitcode.com/gh_mirrors/bl/bloc点击查看免费下载HydratedCubit 是 bloc 状态管理库提供的「可持久化 Cubit」形态它继承了HydratedCubit通过toJson/fromJson将状态自动持久化到本地存储App 重启后无需手动恢复状态。本指南以仓库中bricks/hydrated_cubit官方 BrickMason 模板为核心讲解它的演进历史、模板结构、生成方式与三种代码风格basic / equatable / freezed并深入其源码细节帮助你快速生成、定制并正确落地可持久化的 Cubit 代码。一、Brick 是什么hydrated_cubit的定位bricks/hydrated_cubit是 bloc 仓库中官方维护的一组 Mason Brick定位是「Generate a new HydratedCubit in Dart. Built for the bloc state management library」见 README.md。它服务于以下两类典型场景已有基于hydrated_bloc的 Dart / Flutter 项目需要快速创建带本地持久化能力的 Cubit 骨架团队需要统一 Cubit 代码风格避免每个人手写结构不一致。与普通cubitBrick 的关键区别在于生成的类继承自HydratedCubitT而非CubitT因此模板强制要求实现toJson与fromJson两个方法这也是持久化能力所在。与之配套的还有hydrated_bloc完整 Bloc与replay_cubit/replay_bloc等兄弟 Brick共同组成 bloc 生态的模板体系。二、版本演进从 0.1.0 到 0.3.0Brick 的版本历史完整记录在 CHANGELOG.md 中其演进脉络清晰反映了模板能力的扩展过程版本变更类型内容0.1.0feat初始发布支持 basic 风格的 hydrated cubit 生成0.1.1docs对 README 做小幅更新0.1.2docsREADME 增加徽章badges并使用深色 Logo 变体0.1.3fix修复 part 指令与 import 的声明问题0.2.0feat新增equatable与freezed两种风格的模板支持0.2.1chore更新版权年份与 Logo 图片引用0.3.0chore升级依赖mason ^0.1.0hooks 升级至dart ^3.5.4可以提炼出三条事实模板能力分层演进0.1.0 仅支持 basic 风格0.2.0 才引入 equatable 与 freezed因此style变量见下文的三个取值并非同时出现0.1.3 的 part/imports 修复对应模板文件中part {{name.snakeCase()}}_state.dart;与part of的配对关系这正是多文件生成 Brick 最容易出错的地方0.3.0 对齐了工具链版本Brick 依赖mason ^0.1.0hooks 运行环境要求dart ^3.5.4使用时需确保本地 mason CLI 与 Dart SDK 满足该约束可核对 brick.yaml 与 hooks/pubspec.yaml。三、使用方式一条命令生成两个文件按 README.md 的说明使用方式极其简单mason make hydrated_cubit --name counter --style basic执行后会在当前目录下生成├── counter_cubit.dart └── counter_state.dart使用前提本地已安装 Mason CLI。生成的counter_cubit.dart与counter_state.dart需要放置在你的lib/目录中并确保pubspec.yaml已引入hydrated_blocfreezed 风格还需freezed_annotation与 build_runner 配合。四、变量与参数name 与 style 详解Brick 的输入变量定义在 brick.yaml 中共两个变量类型默认值可选值说明namestringcounter任意字符串Cubit 类名命令行交互提示 Please enter the cubit name.styleenumbasicbasic、equatable、freezed生成模板风格交互提示 What is the cubit style?命令行交互方式不传参时按提示输入mason make hydrated_cubit # ? Please enter the cubit name. counter # ? What is the cubit style? basicname在模板中会被 Mason 的变量修饰器进一步处理{{name.snakeCase()}}用于文件名与 part 指令如counter_cubit.dart{{name.pascalCase()}}用于类名如CounterCubit/CounterState。style的分流逻辑并不写在模板的 if 条件里而是由 hooks/pre_gen.dart 在生成前将枚举值转换为三个布尔变量final style context.vars[style]; context.vars { ...context.vars, use_basic: style basic, use_equatable: style equatable, use_freezed: style freezed, };随后模板主文件 {{name.snakeCase()}}_cubit.dart%7D%7D_cubit.dart) 通过 Mustache 区块按需引入对应片段{{#use_freezed}}{{ freezed_cubit }}{{/use_freezed}}{{#use_equatable}}{{ equatable_cubit }}{{/use_equatable}}{{#use_basic}}{{ basic_cubit }}{{/use_basic}}{{name.snakeCase()}}_state.dart%7D%7D_state.dart) 采用相同的三段式分发。这种「pre_gen 预计算变量 主文件按片段拼接」的模式是 Mason 多风格 Brick 的通用最佳实践便于后续新增风格时只需添加片段文件与 hook 分支。五、三种生成风格与底层实现剖析5.1 basic最小可持久化 Cubitbasic 风格的 Cubit 模板见 {{~ basic_cubit }}import package:hydrated_bloc/hydrated_bloc.dart; part counter_state.dart; class CounterCubit extends HydratedCubitCounterState { CounterCubit() : super(const CounterState()); override MapString, dynamic toJson(CounterState state) { // TODO: implement toJson } override CounterState fromJson(MapString, dynamic json) { // TODO: implement fromJson } }对应状态模板见 {{~ basic_state }}part of counter_cubit.dart; class CounterState { const CounterState(); }两个要点继承自HydratedCubitT这是与普通 Cubit 模板的核心差异。HydratedCubit位于仓库的 packages/hydrated_bloc 包中它在每次emit新状态后自动调用toJson序列化并写入存储在 App 启动恢复时调用fromJson反序列化从而在原生状态管理之上叠加了透明的本地持久化能力模板刻意留白toJson/fromJson以// TODO: implement占位交由开发者按自己的状态模型填充因为 Brick 无法预知业务状态的字段结构。5.2 equatable带值比较的持久化状态equatable 风格的 Cubit 与 basic 几乎一致仅 import 增加equatable关键差异在状态模板 {{~ equatable_state }}part of counter_cubit.dart; class CounterState extends Equatable { const CounterState(); override ListObject get props []; }props目前为空列表生成后需按业务字段补充例如class CounterState extends Equatable { const CounterState({this.count 0}); final int count; override ListObject get props [count]; }Equatable的价值在于当状态值未变化时与hashCode判定相等bloc 生态可据此跳过冗余 rebuild从而减少不必要的 Widget 重建与状态派发。5.3 freezed代码生成与不可变状态freezed 风格引入 Dart 代码生成Cubit 模板见 {{~ freezed_cubit }}import package:freezed_annotation/freezed_annotation.dart; import package:hydrated_bloc/hydrated_bloc.dart; part counter_state.dart; part counter_cubit.freezed.dart; class CounterCubit extends HydratedCubitCounterState { CounterCubit() : super(const CounterState.initial()); override MapString, dynamic toJson(CounterState state) { // TODO: implement toJson } override CounterState fromJson(MapString, dynamic json) { // TODO: implement fromJson } }状态模板见 {{~ freezed_state }}part of counter_cubit.dart; freezed class CounterState with _$CounterState { const factory CounterState.initial() _Initial; }两个值得注意的细节多了一个part {{name.snakeCase()}}_cubit.freezed.dart;这是 freezed 代码生成产生的文件必须在运行build_runner后才会出现因此在 CI/团队协作中需先执行生成命令再编译初始状态由命名构造CounterState.initial()提供freezed 的 union/sealed 风格让后续扩展多个状态分支如loading、error、loaded变得非常自然例如freezed class CounterState with _$CounterState { const factory CounterState.initial() _Initial; const factory CounterState.value(int count) _Value; }三种风格的选择建议追求最小依赖选 basic需要频繁比较状态是否变化配合BlocBuilder/BlocSelector优化重建选 equatable需要不可变、可模式匹配的多分支状态且团队已接受 build_runner 工作流选 freezed。此建议由 bricks/cubit同样支持三种风格及 packages/flutter_bloc 的公开设计推断得出。六、与 bloc 仓库生态的联动hydrated_cubitBrick 在整个 bloc 仓库中并非孤立的模板理解其上下文有助于正确使用hydrated_bloc包packages/hydrated_bloc提供HydratedCubit基类与存储抽象是生成的代码能运行的运行时前提其示例example与测试test展示了持久化行为如何被验证兄弟 Brickbricks/cubit无持久化的纯 Cubit、bricks/hydrated_bloc持久化 Bloc、bricks/replay_cubit/bricks/replay_bloc可回放状态流、bricks/flutter_bloc_feature面向 Flutter 的完整 feature 脚手架。它们共享namestyle的变量设计学习hydrated_cubit后可以零成本迁移到其他 Brickhooks 机制pre_gen.dart是 Mason 的生成前钩子pubspec.yamlhooks/pubspec.yaml声明了 hooks 自身的依赖与 SDK 约束这与 0.3.0 中「升级 hooks 到 dart ^3.5.4」的变更相互印证。七、常见问题与最佳实践为什么toJson返回MapString, dynamic而不是直接存对象因为HydratedCubit的存储层默认基于本地文件/存储抽象以 JSON 可序列化的 Map 为持久化单元。返回 null 时表示该状态不需持久化例如某些瞬时状态可以跳过存储。part与part of必须配对Cubit 文件中part xxx_state.dart;状态文件中part of xxx_cubit.dart;。文件名由snakeCase()统一派生这正是 0.1.3 版本修复的重点改动文件名时务必保持两者一致。freezed 风格编译报错找不到freezed.dart需要先运行代码生成dart run build_runner build建议将其纳入 CI 流程。持久化不生效的排查路径确认HydratedBloc.storage已在main()中初始化参考hydrated_bloc包文档确认状态类字段都已纳入toJson/fromJson确认使用了HydratedCubit而不是普通Cubit。多文件生成的命名一致性所有模板文件都基于同一个name变量通过snakeCase()/pascalCase()派生文件名与类名因此只要name取规范的小驼峰/小写下划线形式生成的文件与类即可保证互相匹配。八、小结bricks/hydrated_cubit是一个「小而精」的官方 Brick两条变量name、style、两个输出文件、三种代码风格再叠加HydratedCubit的持久化语义与pre_genhook 的分流逻辑构成了 bloc 仓库中可持久化 Cubit 的标准生成入口。从 CHANGELOG.md 的演进可以看到它的成熟路径而从 brick.yaml 与brick模板则能完整复现它的工作机制。若你想进一步定制如增加新的风格、补充默认的 JSON 序列化实现以本 Brick 为起点修改是成本最低的路径。赞分享前端【免费下载链接】blocA predictable state management library that helps implement the BLoC design pattern项目地址https://gitcode.com/gh_mirrors/bl/bloc点击查看免费下载相关推荐霞鹜文楷免费商用楷体中文字体完整指南3 分钟装好霞鹜文楷免费商用楷体中文字体完整指南3 分钟装好 霞鹜文楷是一款基于 FONTWORKS Klee One 衍生的开源楷体中文字体覆盖简繁日汉字 2 万余前端Cult Directory Template认证配置避坑指南邮件确认与SMTP速率限制详解Cult Directory Template认证配置避坑指南邮件确认与SMTP速率限制详解 Cult Directory Template 是一款基于 Ne如何用city-roads一键生成城市道路艺术地图完整可视化指南如何用city roads一键生成城市道路艺术地图完整可视化指南 你是否曾想过将城市的脉络以艺术化的方式呈现传统的城市道路可视化工具往往复杂难用而city前端数据可视化3D渲染创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考