# GraphQL 工作流程技能该技能为具有自动代码生成功能的 GraphQL 开发提供了通用的、与项目无关的工作流程。核心模式是**基于角色的文件命名**，它支持类型安全、权限感知的 GraphQL 操作。 ## 该技能何时发动当您执行以下操作时，克劳德会自动使用此技能： * 创建新的 GraphQL 查询、突变或订阅 * 修改现有的GraphQL操作 * 解决 GraphQL 代码生成错误 * 模式更改后重新生成类型 * 验证 GraphQL 文件命名约定 * 需要了解基于角色的GraphQL结构 ## 核心模式：基于角色的文件命名关键的见解是 **GraphQL 操作应按权限角色**组织，而不是按功能或操作类型组织。操作名称.role.graphql ### 角色层次结构示例公共<用户<员工<管理员 **您的项目的角色可能有所不同。**常见模式：项目类型 |典型角色 ---|--- SaaS 应用程序 | `公共`、`用户`、`管理员` 市场| “公众”、“买家”、“卖家”、“管理员” 社交平台 | “公众”、“成员”、“版主”、“管理员” 电子商务| “公众”、“客户”、“员工”、“管理员” ## 关键规则 **使用 GraphQL 时切勿违反这些规则：** 1. ❌ **切勿编辑`*/ generated/` 目录中的文件** \- 这些是自动生成的 2. ✅ **始终遵循`.{role}.graphql`命名约定** \- 每个角色一个文件 3. ✅ **在 GraphQL 更改后始终运行 codegen** \- 重新生成类型 4. ✅ **始终在代码生成之前验证 GraphQL 后端是否正在运行** \- 服务必须可用 5. ✅ **始终将文件放在项目的 GraphQL 目录中** \- 配置您的代码生成器 ## 工作流程步骤 ### 1\.创建 GraphQL 操作 **第 1 步：确定要求** * 操作名称（驼峰命名法，描述性） * 用户角色（来自项目的角色层次结构） * 操作类型（查询、变异、订阅） * 必填数据字段 **第 2 步：创建正确命名的文件** # 文件命名模式：{操作名称}.{角色}.graphql # 典型 SaaS 应用程序的示例： src/graphql/getUserProfile.user.graphql src/graphql/createAppointment.user.graphql src/graphql/getAllUsers.admin.graphql src/graphql/getPublicData.public.graphql **第3步：编写GraphQL操作** # 查询示例 (getUserProfile.user.graphql) 查询 GetUserProfile($userId: ID!) { 用户（ID：$用户ID）{ 编号姓名电子邮件个人资料图片 } } # 突变示例 (createAppointment.user.graphql) 突变 CreateAppointment($input: AppointmentInput!) { 创建约会（输入：$输入）{ 编号预定时间状态 } } # 订阅示例 (onUserUpdate.user.graphql) 订阅 OnUserUpdate($userId: ID!) { userUpdated(userId: $userId) { 编号姓名更新时间 } } **第 4 步：验证后端可用性** # 检查您的 GraphQL 端点是否正在运行卷曲-f {YOUR_GRAPHQL_ENDPOINT} || echo“后端不可用” # 对于 Hasura：curl http://localhost:8080/healthz # 对于阿波罗：curl http://localhost:4000/.well-known/apollo/server-health ### 2\.运行代码生成 **您的项目的 codegen 命令会有所不同。** 常见模式： # GraphQL Codegen (codegen-ts / graphql-codegen) pnpm 代码生成器 # 使用 codegen-ts 配置文件： pnpm codegen:user # 仅用户角色 pnpm codegen:admin # 仅管理员角色 # 或者使用 npm 脚本： npm run 生成类型 npm 运行代码生成器 **预期输出：** * ✅ 在 `src/ generated/` 中生成的 TypeScript 类型（或您配置的输出） * ✅ 为每个操作自动生成 React hooks * ✅ 变量和响应的完整类型安全 ### 3\.验证生成的代码 // 在组件中导入生成的钩子从“@/生成/用户”导入{useGetUserProfileQuery}； // 具有完全类型安全性 const { 数据、加载、错误 } = useGetUserProfileQuery({ 变量：{ userId: currentUser.id }, }); // 数据已通过自动完成功能完全键入 const 用户 = 数据？.user； // 类型：用户 |未定义 ### 4\.处理常见错误错误 |原因 |解决方案 ---|---|--- “后端不可用” | GraphQL 服务器未运行 |启动您的 GraphQL 后端服务 “未找到 GraphQL 文件”|错误的目录或命名 |检查文件位置和“.role.graphql”后缀 “Codegen 因语法错误而失败” |无效的 GraphQL 语法 |验证操作语法和字段名称 “生成的类型未更新” |过时的构建缓存 |删除 ` generated/` 文件夹并重新运行 codegen “X 类型不存在” |架构不匹配 |检查您的 GraphQL 模式是否与后端匹配 ## GraphQL 操作模板 ### 查询模板 # src/graphql/{操作名称}.{角色}.graphql 查询 {OperationName}($param: 类型!) { 表名(其中: { 字段: { _eq: $param } }) { 编号字段1 字段2 相关表{ 编号姓名 } } } ### 突变模板 # src/graphql/{操作名称}.{角色}.graphql 突变 {OperationName}($input: table_insert_input!) { insert_table_one(对象: $input) { 编号字段1 字段2 创建时间 } } ### 订阅模板 # src/graphql/{操作名称}.{角色}.graphql 订阅 {OperationName}($userId: ID!) { 表名（其中：{ user_id：{ _eq：$ userId } }）{ 编号字段1 更新时间 } } ## 与组件集成 **第 1 步：导入生成的 Hook** 从“@/生成/用户”导入{useGetUserProfileQuery}； **第2步：在组件中使用** 导出函数 UserProfile({ userId }: { userId: string }) { const { 数据、加载、错误 } = useGetUserProfileQuery({ 变量：{ userId } }); 如果（正在加载）返回; if (错误) 返回 ; 返回（

{数据？.用户？.名称}

{数据？.用户？.电子邮件}

）； } ## 为您的项目配置 Codegen ### 基本 codegen.ts 配置从'@graphql-codegen/cli'导入类型{CodegenConfig}；常量配置：CodegenConfig = { schema: 'http://localhost:8080/v1/graphql', // 您的 GraphQL 端点文档：['src/graphql/**/*.graphql'], 本地生成：真， hooks: { afterAllFileWrite: ['prettier --write'] }, 生成：{ 'src/ generated/types.ts'：{ 插件：['打字稿']，配置：{ 标量：{ uuid: '字符串', 时间戳：'字符串'， }, }, }, 'src/生成/': { 预设：'附近操作文件'，预设配置：{ 扩展名: '. generated.ts', baseTypesPath: 'types.ts', }, 插件：['打字稿操作'，'打字稿反应阿波罗']， }, }, }; 导出默认配置； ### 基于角色的配置（多个输出文件）对于基于角色的分离，请使用多个配置文件： codegen.ts # 基本类型 codegen.user.ts # 用户操作 codegen.admin.ts # 管理操作 codegen.public.ts # 公共操作 **codegen.user.ts 示例：** 从'@graphql-codegen/cli'导入类型{CodegenConfig}；从'./codegen'导入baseConfig；常量配置：CodegenConfig = { ...基本配置，文档：['src/graphql/**/*.user.graphql'], 生成：{ 'src/生成/user.ts': { 插件：['打字稿'，'打字稿操作'，'打字稿反应阿波罗']， }, }, }; 导出默认配置； ## 最佳实践 1. **描述性名称**：使用清晰的操作名称（例如，“GetUserProfile”，而不是“GetUser”） 2. **Role Appropriate** : 只查询该角色应该访问的数据 3. **字段选择** ：仅请求您需要的字段（避免过度获取） 4. **分页** ：对大型数据集使用限制/偏移或基于光标的分页 5. **错误处理**：始终处理加载和错误状态 6. **类型安全**：充分利用生成的 TypeScript 类型 7. **片段**：通过 GraphQL 片段重用公共字段选择 ## 测试 GraphQL 操作 1. **在 GraphQL Playground/Console 中测试** \- 您的 GraphQL 端点的 UI 2. **使用模拟数据进行测试** \- 使用 MSW 或类似工具进行单元测试 3. **测试权限** \- 验证基于角色的访问是否正常工作 4. **测试错误案例** \- 处理网络故障、验证错误 ## 性能优化 * **片段**：重用公共字段选择 * **批处理** ：尽可能合并相关查询 * **缓存** ：利用 GraphQL 客户端的缓存（Apollo、urql 等） * **订阅** ：谨慎使用；大多数情况下更喜欢使用轮询进行查询 ## 快速参考任务|命令 ---|--- 生成所有类型 | `pnpm 代码生成器` 生成特定角色 | `pnpm 代码生成器：{角色}` 检查 GraphQL 端点 | `卷曲 {YOUR_GRAPHQL_ENDPOINT}` 清洁和重建 | `rm -rf 生成/ && pnpm codegen` ** ** **此技能与框架和后端无关。**适用于： * **后端**：Hasura、Apollo Server、GraphQL Yoga、PostGraphile 等。 * **框架** ：React、Next.js、Vue、Svelte、Solid 等。 * **客户端** ：Apollo 客户端、urql、GraphQL 请求等。

Graphql 工作流程

包含技能