Ferry代码生成器教程从GraphQL Schema一键生成不可变强类型类【免费下载链接】ferryStream-based strongly typed GraphQL client for Dart项目地址: https://gitcode.com/gh_mirrors/fer/ferryFerry 代码生成器是 Dart/Flutter 生态中一款强大的 GraphQL 代码生成工具。只需一份 GraphQL Schema 和若干.graphql操作文件它就能通过一条命令自动为你生成不可变、强类型的 Dart 数据类让 GraphQL 客户端告别运行时错误。本文是面向新手的完整指南带你从零跑通Ferry GraphQL 代码生成全流程并对比两代生成器的选型与进阶配置。为什么需要 GraphQL 代码生成器手写 GraphQL 客户端时你通常要面对这些痛点⚠️运行时才报错字段名拼错、类型不匹配只有请求发出后才发现手动解析 JSON反复写map[field]空值处理全靠小心翼翼类型安全缺失IDE 无法补全重构时无法自动追踪字段变化Ferry 的解决方案是基于你的 GraphQL Schema在编译期生成完整的强类型类。正如 README.md 中所描述的它是 Fully Typed 的核心能力——编译期检查 IDE 自动补全连缓存的读写都是强类型的。快速开始4步一键生成强类型类第 1 步克隆仓库并添加依赖git clone https://gitcode.com/gh_mirrors/fer/ferry在你的 Dart/Flutter 项目中将ferry_generator加入dev_dependencies并安装build_runner详见 packages/ferry_generator/ 目录说明。第 2 步下载 GraphQL Schema把服务的 Schema 以 SDL 格式保存到lib/目录下例如lib/schema.graphqlnpx get-graphql-schema [ENDPOINT_URL] lib/schema.graphql第 3 步编写 .graphql 操作文件把 Query、Mutation 和 Fragment 保存为.graphql文件必须放在lib/目录内。官方建议放入graphql/子目录例如仓库中的 examples/pokemon_explorer2/lib/graphql/query AllPokemon($first: Int!) { pokemons(first: $first) { id name maxHP } }如果操作引用了其他文件里的 Fragment用注释导入即可# import ./pokemon_card_fragment.graphql第 4 步配置 build.yaml 并运行构建在项目根目录创建build.yaml指向你的 Schema 文件然后执行dart run build_runner build --delete-conflicting-outputs完成后每个.graphql文件旁边都会出现__generated__目录强类型类已全部就绪 ✅生成物详解generated目录里有什么以all_pokemon.graphql为例生成器会产出以下文件文件后缀作用*.ast.gql.dartGraphQL 文档的 AST 常量定义*.data.gql.dart响应数据类强类型模型*.var.gql.dart变量类操作没有变量时不生成*.req.gql.dart请求类继承OperationRequest内置 FetchPolicy 等执行配置*.schema.gql.dartSchema 中的枚举、Input 类型、possibleTypes 映射*.utils.gql.dart可选的 equals / hashCode 辅助v2 中按需开启以 v1 生成器为例AllPokemon查询会生成三个核心类GAllPokemonReq请求、GAllPokemonVars变量、GAllPokemonData响应数据并自动生成 Schema 中用到的 input、enum 和自定义 scalar 支持类。小知识点所有类名前都会加G前缀这是built_value包的命名限制也是识别 Ferry 生成类的标志。两代生成器怎么选ferry_generator vs ferry_generator2Ferry 目前提供两代生成器完整说明见 docs/codegen.md 与 docs/codegen2.md。v1ferry_generatorbuilt_value 路线生成的类基于built_value包四大特性不可变创建后无法修改可比较值相同的实例相等可序列化内置toJson()/fromJson()Builder 模式深度复制并修改字段v1 额外支持多 Schema配置schemas列表按目录划分作用域适合复杂的中台架构。v2ferry_generator2下一代实验性ferry_generator2 主打小体积、快构建、纯 Dart 类核心优势 无 builder、无序列化器样板代码输出更小、编译更快const构造函数 直接的toJson/fromJson 接口/联集生成sealed 密封类并附带__unknown兜底变体模式匹配更安全⚙️copyWith、、hashCode、toString全部可选配置Fragment 复用去重同一 Fragment 用于多个操作时只映射到一个类从 v1 迁移到 v2 的详细步骤可参考 docs/migration-generator2.md。进阶配置这些长尾选项值得了解枚举兜底值防止新枚举值打崩客户端服务端新增枚举值而客户端未升级时可配置 fallback 避免反序列化失败ferry_generator|graphql_builder: options: global_enum_fallbacks: true enum_fallbacks: MyEnumType: OTHER自定义标量类型自定义 scalar如Date可在build.yaml中映射为 Dart 类型并指定fromJson/toJson更多用法见 docs/custom-scalars.md。三态可选变量Tristate Optionals开启tristate_optionals: true后可空变量用ValueT表示未提供 / 显式 null / 有值三种状态专门解决更新类 Mutation中区分不更新与置空的经典难题。输出目录控制默认输出到__generated__目录设置output_dir: 可让生成文件直接落在.graphql旁边。常见问题 FAQQ1为什么.graphql文件必须在lib/下A构建系统只能读取lib/内的资源放到外面生成器无法访问。Q2构建时报 conflicting outputs 怎么办A给 build_runner 命令加上--delete-conflicting-outputs参数。Q3生成文件太多干扰浏览A在 VSCode 的settings.json中用files.exclude隐藏*.ast.gql.dart等模式docs/codegen.md 提供了现成配置。Q4v2 支持多 Schema 吗A目前 v2 仅支持单 Schemaschema.files会直接报错。多 Schema 场景可拆分为多个 Dart 包、各配一个 Ferry 客户端或继续使用 v1。总结Ferry 代码生成器把 Schema → 强类型 Dart 类 变成了一条命令的事4 步上手下载 Schema、写.graphql、配置build.yaml、跑 build_runner️编译期安全不可变、可比较、可序列化的强类型模型两代可选v1 稳定且支持多 Schemav2 更轻更快sealed 类型匹配体验极佳实战参考端到端示例见 packages/ferry_generator2_end_to_end/ 与 examples/pokemon_explorer2/现在就可以克隆仓库给你的 GraphQL 项目加上 Ferry 强类型代码生成让错误在编译期就无处遁形【免费下载链接】ferryStream-based strongly typed GraphQL client for Dart项目地址: https://gitcode.com/gh_mirrors/fer/ferry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Ferry代码生成器教程：从GraphQL Schema一键生成不可变强类型类
Ferry代码生成器教程从GraphQL Schema一键生成不可变强类型类【免费下载链接】ferryStream-based strongly typed GraphQL client for Dart项目地址: https://gitcode.com/gh_mirrors/fer/ferryFerry 代码生成器是 Dart/Flutter 生态中一款强大的 GraphQL 代码生成工具。只需一份 GraphQL Schema 和若干.graphql操作文件它就能通过一条命令自动为你生成不可变、强类型的 Dart 数据类让 GraphQL 客户端告别运行时错误。本文是面向新手的完整指南带你从零跑通Ferry GraphQL 代码生成全流程并对比两代生成器的选型与进阶配置。为什么需要 GraphQL 代码生成器手写 GraphQL 客户端时你通常要面对这些痛点⚠️运行时才报错字段名拼错、类型不匹配只有请求发出后才发现手动解析 JSON反复写map[field]空值处理全靠小心翼翼类型安全缺失IDE 无法补全重构时无法自动追踪字段变化Ferry 的解决方案是基于你的 GraphQL Schema在编译期生成完整的强类型类。正如 README.md 中所描述的它是 Fully Typed 的核心能力——编译期检查 IDE 自动补全连缓存的读写都是强类型的。快速开始4步一键生成强类型类第 1 步克隆仓库并添加依赖git clone https://gitcode.com/gh_mirrors/fer/ferry在你的 Dart/Flutter 项目中将ferry_generator加入dev_dependencies并安装build_runner详见 packages/ferry_generator/ 目录说明。第 2 步下载 GraphQL Schema把服务的 Schema 以 SDL 格式保存到lib/目录下例如lib/schema.graphqlnpx get-graphql-schema [ENDPOINT_URL] lib/schema.graphql第 3 步编写 .graphql 操作文件把 Query、Mutation 和 Fragment 保存为.graphql文件必须放在lib/目录内。官方建议放入graphql/子目录例如仓库中的 examples/pokemon_explorer2/lib/graphql/query AllPokemon($first: Int!) { pokemons(first: $first) { id name maxHP } }如果操作引用了其他文件里的 Fragment用注释导入即可# import ./pokemon_card_fragment.graphql第 4 步配置 build.yaml 并运行构建在项目根目录创建build.yaml指向你的 Schema 文件然后执行dart run build_runner build --delete-conflicting-outputs完成后每个.graphql文件旁边都会出现__generated__目录强类型类已全部就绪 ✅生成物详解generated目录里有什么以all_pokemon.graphql为例生成器会产出以下文件文件后缀作用*.ast.gql.dartGraphQL 文档的 AST 常量定义*.data.gql.dart响应数据类强类型模型*.var.gql.dart变量类操作没有变量时不生成*.req.gql.dart请求类继承OperationRequest内置 FetchPolicy 等执行配置*.schema.gql.dartSchema 中的枚举、Input 类型、possibleTypes 映射*.utils.gql.dart可选的 equals / hashCode 辅助v2 中按需开启以 v1 生成器为例AllPokemon查询会生成三个核心类GAllPokemonReq请求、GAllPokemonVars变量、GAllPokemonData响应数据并自动生成 Schema 中用到的 input、enum 和自定义 scalar 支持类。小知识点所有类名前都会加G前缀这是built_value包的命名限制也是识别 Ferry 生成类的标志。两代生成器怎么选ferry_generator vs ferry_generator2Ferry 目前提供两代生成器完整说明见 docs/codegen.md 与 docs/codegen2.md。v1ferry_generatorbuilt_value 路线生成的类基于built_value包四大特性不可变创建后无法修改可比较值相同的实例相等可序列化内置toJson()/fromJson()Builder 模式深度复制并修改字段v1 额外支持多 Schema配置schemas列表按目录划分作用域适合复杂的中台架构。v2ferry_generator2下一代实验性ferry_generator2 主打小体积、快构建、纯 Dart 类核心优势 无 builder、无序列化器样板代码输出更小、编译更快const构造函数 直接的toJson/fromJson 接口/联集生成sealed 密封类并附带__unknown兜底变体模式匹配更安全⚙️copyWith、、hashCode、toString全部可选配置Fragment 复用去重同一 Fragment 用于多个操作时只映射到一个类从 v1 迁移到 v2 的详细步骤可参考 docs/migration-generator2.md。进阶配置这些长尾选项值得了解枚举兜底值防止新枚举值打崩客户端服务端新增枚举值而客户端未升级时可配置 fallback 避免反序列化失败ferry_generator|graphql_builder: options: global_enum_fallbacks: true enum_fallbacks: MyEnumType: OTHER自定义标量类型自定义 scalar如Date可在build.yaml中映射为 Dart 类型并指定fromJson/toJson更多用法见 docs/custom-scalars.md。三态可选变量Tristate Optionals开启tristate_optionals: true后可空变量用ValueT表示未提供 / 显式 null / 有值三种状态专门解决更新类 Mutation中区分不更新与置空的经典难题。输出目录控制默认输出到__generated__目录设置output_dir: 可让生成文件直接落在.graphql旁边。常见问题 FAQQ1为什么.graphql文件必须在lib/下A构建系统只能读取lib/内的资源放到外面生成器无法访问。Q2构建时报 conflicting outputs 怎么办A给 build_runner 命令加上--delete-conflicting-outputs参数。Q3生成文件太多干扰浏览A在 VSCode 的settings.json中用files.exclude隐藏*.ast.gql.dart等模式docs/codegen.md 提供了现成配置。Q4v2 支持多 Schema 吗A目前 v2 仅支持单 Schemaschema.files会直接报错。多 Schema 场景可拆分为多个 Dart 包、各配一个 Ferry 客户端或继续使用 v1。总结Ferry 代码生成器把 Schema → 强类型 Dart 类 变成了一条命令的事4 步上手下载 Schema、写.graphql、配置build.yaml、跑 build_runner️编译期安全不可变、可比较、可序列化的强类型模型两代可选v1 稳定且支持多 Schemav2 更轻更快sealed 类型匹配体验极佳实战参考端到端示例见 packages/ferry_generator2_end_to_end/ 与 examples/pokemon_explorer2/现在就可以克隆仓库给你的 GraphQL 项目加上 Ferry 强类型代码生成让错误在编译期就无处遁形【免费下载链接】ferryStream-based strongly typed GraphQL client for Dart项目地址: https://gitcode.com/gh_mirrors/fer/ferry创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考