欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.csdn.net
前言
在 GraphQL 开发中，手动解析 JSON 是极其低效且易出错的。graphql_codegen 通过自动生成的强类型 Dart 代码，让你的开发体验从“黑盒解析”进化到“全量代码提示”。
本指南将结合 OpenHarmony 环境，详细介绍如何配置、编写以及解决常见的版本与构建报错。
一、 核心原理解析
graphql_codegen 的工作流程可以概括为：输入（Schema + Query） -> 编译 -> 输出（Type Safe Dart Code）。
- Schema (lib/schema.graphql): 它是服务端的“说明书”，定义了后端支持的所有对象类型。
- Document (lib/graphql/users.graphql): 它是客户端的“订单”，定义了你具体想要查询哪些字段。
- 生成的代码: 包含 Result 类（数据模型）、Variables 类（参数模型）以及 Flutter Hook（如果配置了插件）。
二、 快速上手配置
2.1 依赖安装 (版本避坑指南)
重要： 请务必检查 graphql_codegen 的版本。目前社区常用且稳定的版本是 ^1.1.1，很多教程中提到的 ^5.0.0 实际上是无效的版本号，会导致 pub get 失败。
pubspec.yaml:
dependencies:
dio: ^5.7.0
graphql_flutter: ^5.1.0
dev_dependencies:
build_runner: ^2.4.0
# 💡 避坑提示：使用 1.x.x 稳定分支
graphql_codegen: ^1.1.1
2.2 核心配置文件
在项目根目录创建 build.yaml。 注意： clients 选项不应包含文件路径，而是指定生成的代码适配哪种客户端。
build.yaml:
targets:
$default:
builders:
graphql_codegen:
options:
# 💡 必填：指定生成适配 graphql_flutter 的代码
clients:
– graphql_flutter
三、 编写 GraphQL 定义文件
3.1 准备服务端 Schema (lib/schema.graphql)
这是生成代码的基石。如果缺少这个文件或字段不匹配，构建会直接报错。它定义了基础的数据结构。
type User {
id: ID!
name: String!
avatar_url: String
}
type Query {
users: [User!]!
}
3.2 编写业务查询 (lib/graphql/users.graphql)
具体业务中用到的查询语句。生成器会为每个 query 生成对应的 Dart 类。
query FetchUsers {
users {
id
name
avatar_url
}
}
四、 代码生成与使用
4.1 执行构建
在终端运行以下命令。建议增加 –delete-conflicting-outputs 以清理旧代码：
dart run build_runner build –delete-conflicting-outputs
完成后，你会在 lib/graphql/ 目录下看到 users.graphql.dart。
4.2 在鸿蒙工程中使用
import 'graphql/users.graphql.dart';
void fetchUserList() async {
// 💡 优点 1：全自动生成的 Options 类
final options = Options$Query$FetchUsers(
fetchPolicy: FetchPolicy.networkOnly,
);
final result = await client.query(options);
if (result.hasException) return;
// 💡 优点 2：不再是 result.data['users'][0]['name']
// 而是强类型方案，享受 IDE 的属性补全
final user = result.parsedData!.users.first;
print("用户姓名: ${user.name}");
}
五、 鸿蒙适配与常见报错排查
5.1 常见构建报错及解法
报错：Invalid argument(s): {schema: …} is not one of the supported values
- 原因：在 build.yaml 的 clients 列表里错误地夹带了 schema 配置。
- 解法：修正 build.yaml，让 clients 仅包含 graphql_flutter 字符串。
报错：Document contains unknown types
- 原因：users.graphql 中引用的字段在 schema.graphql 中找不到定义。
- 解法：核对两个文件中的字段名和类型名（注意大小写敏感）。
版本冲突 (Version Solving Failed)
- 原因：使用了不存在的大版本号（如尝试安装 5.0.0）。
- 解法：根据 dart pub add 的建议，回退到对应的 1.x.x 版本。
5.2 平台建议
由于 graphql_codegen 仅在编译期运行，生成的全是纯 Dart 代码，因此在 OpenHarmony 模拟器和真机上具有 100% 的原生兼容性。只需确保在鸿蒙的 module.json5 中开启了网络权限即可。
六、 总结
graphql_codegen 不仅仅是一个工具，它引入了一套契约式开发的流程。
