Ferry Generator 2代码生成器深度解读纯Dart模型升级亮点与迁移指南【免费下载链接】ferryStream-based strongly typed GraphQL client for Dart项目地址: https://gitcode.com/gh_mirrors/fer/ferryFerry 是 Dart 生态中基于流的强类型 GraphQL 客户端而Ferry Generator 2包名ferry_generator2是它新一代的 GraphQL 代码生成器不再依赖built_value而是直接生成纯 Dart 类实现更小的产物、更快的构建和更强的正确性检查。本文面向新手讲清 v2 相比旧生成器ferry_generator升级了什么、怎么配置以及如何把现有项目迁移过来。一、为什么会有 Generator 2告别 built_value旧版生成器基于 built_value 构建模型稳定可靠但代价是builder 样板代码多、序列化器serializers体系复杂、产物体积大对 Flutter 的 Tree Shaking 也不太友好。Generator 2 的核心目标来自 docs/codegen2.md产物更小无 builder、无 serializers只剩toJson()/fromJson()纯 Dart 模型const构造器 简单字段可读性高构建更快不再需要built_value_generator那套重依赖可选项按需开启copyWith、、hashCode、toString全部可选对比项v1ferry_generatorv2ferry_generator2模型基座built_value builder纯 Dart 类const 构造器序列化serializers /serializer_builder直接toJson()/fromJson()集合类型BuiltList/BuiltMap原生List/Map联合/接口普通类 手动判断sealed 继承层级 __unknown兜底copyWith / / hashCode默认就有配置项按需开启构建依赖重built_value 全家桶轻仅 build_runner二、真实产物长什么样看一个 Pokémon 查询仓库自带完整示例 examples/pokemon_explorer2/其中AllPokemon查询只有一个片段展开query AllPokemon($limit: Int!, $offset: Int!) { pokemon(limit: $limit, offset: $offset, order_by: {id: asc}) { ...PokemonCard } }运行dart run build_runner build后__generated__目录会产出 4 个文件ast、data、var、req。响应模型 all_pokemon.data.gql.dart 只有 30 多行class GAllPokemonData { const GAllPokemonData({required this.pokemon, required this.G__typename}); factory GAllPokemonData.fromJson(MapString, dynamic json) { /* ... */ } final ListGPokemonCardData pokemon; final String G__typename; MapString, dynamic toJson() { /* ... */ } }没有 builder、没有GxSerializer一眼可读。对比 v1 为同一查询生成的数百行 builder serializer 代码这就是小产物的实际含义。每个.graphql文件可能产出的文件类型文件后缀内容*.ast.gql.dartGraphQL 文档的 AST 常量*.data.gql.dart响应数据模型类*.var.gql.dart变量模型类无变量则不生成*.req.gql.dart请求类继承OperationRequest*.schema.gql.dartschema 枚举、input 类型、possibleTypes 映射*.utils.gql.dart相等性/哈希辅助启用后才生成三、升级亮点速览1️⃣ Sealed 类处理联合与接口接口/联合选择会生成 sealed 基类 每个具体类型的子类 __unknown兜底变体配合可选的when/maybeWhen扩展做模式匹配穷举检查更安心。2️⃣ 片段自动复用与去重同一个 fragment 被多个 operation 引用时只生成一个类选择集若只是片段展开加__typename会直接复用片段类而不是嵌套复制一份。3️⃣ 三态变量tristate开启vars.tristate_optionals后可空变量使用ValueT能精确区分不传、传值、传 null三种语义。4️⃣ 自定义标量映射scalars配置项支持类型映射 导入路径 from_json/to_json钩子替代 v1 的type_overrides和全局序列化器列表。5️⃣ 枚举兜底值服务端新增枚举值不会让客户端反序列化崩溃可配置全局兜底名默认gUnknownEnumValue或按枚举单独指定。6️⃣ 格式化与日志产物自动dart format构建日志支持text/json格式与分类过滤方便 CI 中排查。四、五步上手从依赖到运行代码生成 完整配置参考 docs/codegen2.md官方迁移文档在 docs/migration-generator2.md。加依赖dev_dependencies加入build_runner和ferry_generator2当前为0.1.0-dev.x实验版本启用三态变量时再加gql_tristate_value。准备 schema把 GraphQL SDL 存到lib/graphql/schema.graphql。写查询文件把.graphql操作与 fragment 放在lib/下支持#import注释引入其他文件。配置 build.yaml核心配置只有一段schema.file指到 schema其余开关按项目习惯勾选详见 ferry_generator2 READMEbuilders: ferry_generator2|graphql_builder: options: schema: file: your_pkg|lib/graphql/schema.graphql add_typenames: true data_classes: when_extensions: { when: true, maybe_when: true } utils: { copy_with: true, equals: true } enums: fallback: { global: true, name: gUnknownEnumValue }运行生成dart run build_runner build --delete-conflicting-outputs产物默认落在.graphql文件旁的__generated__目录。五、迁移指南v1 项目怎么切到 v2官方明确说明 v2不追求与 built_value API 兼容迁移需要改动代码主要五步① 依赖瘦身删掉ferry_generator、built_value、built_collection加上ferry_generator2build_runner。② 改写 build.yamlserializer_builder整段删除schema改为schema.file嵌套写法type_overrides换成scalarsglobal_enum_fallbacks等旧键名换成enums.fallback.*。③ builder 写法 → 构造器写法// v1 final req GAllPokemonReq((b) b..vars.first 20); // v2 final req GAllPokemonReq(vars: GAllPokemonVars(first: 20));④ 序列化与集合serializers.serializeWith(...)改成data.toJson()toBuiltList()改成toList()。⑤ 数据更新rebuild((b) ...)改为copyWith(...)需开启utils.copy_with注意它是浅拷贝嵌套更新需逐层 map。✅迁移检查清单build.yaml中 builder 名换成ferry_generator2|graphql_builder删除serializer_builder与 built_value 相关依赖标量映射迁移到scalars:含from_json/to_jsonbuilder 风格构造全部改写为构造器 /copyWithBuiltList/BuiltMap改为List/Map序列化调用改为toJson()/fromJson()六、注意事项与限制⚠️ v2 目前处于实验阶段首个稳定版发布前 API 与产物可能有变化见 CHANGELOG。仅支持单一 schema多 schema 场景建议拆分成多个 Dart 包、各自独立 Ferry 客户端。无变量操作不生成.var.gql.dart请求类型为OperationRequestData, Nullreq输出依赖ast、data、vars同时开启。若项目深度依赖 built_value 特性如BuiltListAPI可暂时继续使用 v1两者可并存。 想系统验证生成质量仓库提供两层测试包内构建测试packages/ferry_generator2/test/与端到端包packages/ferry_generator2_end_to_end/后者把真实 schema 的生成产物提交进仓库并做运行时校验是理解 v2 产物结构最好的活文档。【免费下载链接】ferryStream-based strongly typed GraphQL client for Dart项目地址: https://gitcode.com/gh_mirrors/fer/ferry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/8/24 11:23:47 · 阅读 1.2k Ferry Generator 2代码生成器深度解读：纯Dart模型升级亮点与迁移指南
Ferry Generator 2代码生成器深度解读纯Dart模型升级亮点与迁移指南【免费下载链接】ferryStream-based strongly typed GraphQL client for Dart项目地址: https://gitcode.com/gh_mirrors/fer/ferryFerry 是 Dart 生态中基于流的强类型 GraphQL 客户端而Ferry Generator 2包名ferry_generator2是它新一代的 GraphQL 代码生成器不再依赖built_value而是直接生成纯 Dart 类实现更小的产物、更快的构建和更强的正确性检查。本文面向新手讲清 v2 相比旧生成器ferry_generator升级了什么、怎么配置以及如何把现有项目迁移过来。一、为什么会有 Generator 2告别 built_value旧版生成器基于 built_value 构建模型稳定可靠但代价是builder 样板代码多、序列化器serializers体系复杂、产物体积大对 Flutter 的 Tree Shaking 也不太友好。Generator 2 的核心目标来自 docs/codegen2.md产物更小无 builder、无 serializers只剩toJson()/fromJson()纯 Dart 模型const构造器 简单字段可读性高构建更快不再需要built_value_generator那套重依赖可选项按需开启copyWith、、hashCode、toString全部可选对比项v1ferry_generatorv2ferry_generator2模型基座built_value builder纯 Dart 类const 构造器序列化serializers /serializer_builder直接toJson()/fromJson()集合类型BuiltList/BuiltMap原生List/Map联合/接口普通类 手动判断sealed 继承层级 __unknown兜底copyWith / / hashCode默认就有配置项按需开启构建依赖重built_value 全家桶轻仅 build_runner二、真实产物长什么样看一个 Pokémon 查询仓库自带完整示例 examples/pokemon_explorer2/其中AllPokemon查询只有一个片段展开query AllPokemon($limit: Int!, $offset: Int!) { pokemon(limit: $limit, offset: $offset, order_by: {id: asc}) { ...PokemonCard } }运行dart run build_runner build后__generated__目录会产出 4 个文件ast、data、var、req。响应模型 all_pokemon.data.gql.dart 只有 30 多行class GAllPokemonData { const GAllPokemonData({required this.pokemon, required this.G__typename}); factory GAllPokemonData.fromJson(MapString, dynamic json) { /* ... */ } final ListGPokemonCardData pokemon; final String G__typename; MapString, dynamic toJson() { /* ... */ } }没有 builder、没有GxSerializer一眼可读。对比 v1 为同一查询生成的数百行 builder serializer 代码这就是小产物的实际含义。每个.graphql文件可能产出的文件类型文件后缀内容*.ast.gql.dartGraphQL 文档的 AST 常量*.data.gql.dart响应数据模型类*.var.gql.dart变量模型类无变量则不生成*.req.gql.dart请求类继承OperationRequest*.schema.gql.dartschema 枚举、input 类型、possibleTypes 映射*.utils.gql.dart相等性/哈希辅助启用后才生成三、升级亮点速览1️⃣ Sealed 类处理联合与接口接口/联合选择会生成 sealed 基类 每个具体类型的子类 __unknown兜底变体配合可选的when/maybeWhen扩展做模式匹配穷举检查更安心。2️⃣ 片段自动复用与去重同一个 fragment 被多个 operation 引用时只生成一个类选择集若只是片段展开加__typename会直接复用片段类而不是嵌套复制一份。3️⃣ 三态变量tristate开启vars.tristate_optionals后可空变量使用ValueT能精确区分不传、传值、传 null三种语义。4️⃣ 自定义标量映射scalars配置项支持类型映射 导入路径 from_json/to_json钩子替代 v1 的type_overrides和全局序列化器列表。5️⃣ 枚举兜底值服务端新增枚举值不会让客户端反序列化崩溃可配置全局兜底名默认gUnknownEnumValue或按枚举单独指定。6️⃣ 格式化与日志产物自动dart format构建日志支持text/json格式与分类过滤方便 CI 中排查。四、五步上手从依赖到运行代码生成 完整配置参考 docs/codegen2.md官方迁移文档在 docs/migration-generator2.md。加依赖dev_dependencies加入build_runner和ferry_generator2当前为0.1.0-dev.x实验版本启用三态变量时再加gql_tristate_value。准备 schema把 GraphQL SDL 存到lib/graphql/schema.graphql。写查询文件把.graphql操作与 fragment 放在lib/下支持#import注释引入其他文件。配置 build.yaml核心配置只有一段schema.file指到 schema其余开关按项目习惯勾选详见 ferry_generator2 READMEbuilders: ferry_generator2|graphql_builder: options: schema: file: your_pkg|lib/graphql/schema.graphql add_typenames: true data_classes: when_extensions: { when: true, maybe_when: true } utils: { copy_with: true, equals: true } enums: fallback: { global: true, name: gUnknownEnumValue }运行生成dart run build_runner build --delete-conflicting-outputs产物默认落在.graphql文件旁的__generated__目录。五、迁移指南v1 项目怎么切到 v2官方明确说明 v2不追求与 built_value API 兼容迁移需要改动代码主要五步① 依赖瘦身删掉ferry_generator、built_value、built_collection加上ferry_generator2build_runner。② 改写 build.yamlserializer_builder整段删除schema改为schema.file嵌套写法type_overrides换成scalarsglobal_enum_fallbacks等旧键名换成enums.fallback.*。③ builder 写法 → 构造器写法// v1 final req GAllPokemonReq((b) b..vars.first 20); // v2 final req GAllPokemonReq(vars: GAllPokemonVars(first: 20));④ 序列化与集合serializers.serializeWith(...)改成data.toJson()toBuiltList()改成toList()。⑤ 数据更新rebuild((b) ...)改为copyWith(...)需开启utils.copy_with注意它是浅拷贝嵌套更新需逐层 map。✅迁移检查清单build.yaml中 builder 名换成ferry_generator2|graphql_builder删除serializer_builder与 built_value 相关依赖标量映射迁移到scalars:含from_json/to_jsonbuilder 风格构造全部改写为构造器 /copyWithBuiltList/BuiltMap改为List/Map序列化调用改为toJson()/fromJson()六、注意事项与限制⚠️ v2 目前处于实验阶段首个稳定版发布前 API 与产物可能有变化见 CHANGELOG。仅支持单一 schema多 schema 场景建议拆分成多个 Dart 包、各自独立 Ferry 客户端。无变量操作不生成.var.gql.dart请求类型为OperationRequestData, Nullreq输出依赖ast、data、vars同时开启。若项目深度依赖 built_value 特性如BuiltListAPI可暂时继续使用 v1两者可并存。 想系统验证生成质量仓库提供两层测试包内构建测试packages/ferry_generator2/test/与端到端包packages/ferry_generator2_end_to_end/后者把真实 schema 的生成产物提交进仓库并做运行时校验是理解 v2 产物结构最好的活文档。【免费下载链接】ferryStream-based strongly typed GraphQL client for Dart项目地址: https://gitcode.com/gh_mirrors/fer/ferry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考