mcpField
I
implement-graphql

implement-graphql

github.com/igmarin开发2839 次安装4 周前更新
代码仓库

关于 implement-graphql

面向使用 `graphql-ruby` 的 Rails 应用，用于设计、实现和审查 GraphQL API 的 Skill。它强调先写失败测试，并检查授权与 N+1 查询防护。

主要功能

  1. 01要求实现前先编写失败测试
  2. 02定义 GraphQL 类型、参数与解析器
  3. 03使用 Dataloader 防止 N+1 查询
  4. 04检查字段授权与 Schema 防护
  5. 05规范 Mutation 的错误响应

适用场景

  1. 01构建 GraphQL 解析器或 Mutation
  2. 02审查敏感字段的授权
  3. 03检查分页与查询性能

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/igmarin/rails-agent-skills --skill implement-graphql

安装后在 Claude Code 中输入/implement-graphql确认已加载。

附带文件EXAMPLES.mdTESTING.md

详细介绍

实现 GraphQL

当你在 Rails 应用中使用 graphql-ruby gem 设计、实现或审查 GraphQL API 时，使用本技能。

核心流程

在第 1 步编写完成并失败之前，不要进入第 3 步。

  1. SPEC： 编写失败的 spec（正常路径 + 认证 + 校验错误场景）——参见 TESTING.md。在 spec/graphql/ 中使用 AppSchema.execute。GraphQL spec 绝不要使用 HTTP controller dispatch。

  2. TYPE： 定义参数和返回类型。分页形态使用 connection_type。不要泄露内部模型名称。

  3. IMPLEMENT： 创建 resolver/mutation 类，委托给 service object。使用专用类，而不是内联 field block。

  4. N+1 CHECK： 每次加载关联都使用 dataloader。对于列表 resolver，在字段解析关联对象之前，用 relation 返回的记录为 dataloader 预加载。在 spec 中使用 bullet 和 db-query-matchers。

    # ✅ batches loads across all records
def buyer
  dataloader.with(Sources::RecordById, Buyer).load(object.buyer_id)
end

  5. AUTH CHECK： 对敏感数据使用 Pundit 或自定义 context guard 应用字段级防护。

    field :internal_notes, String, null: true do
  guard -> (_obj, _args, ctx) { ctx[:current_user]&.admin? }
end

  6. FINAL CHECK： 验证下方 HARD-GATE 检查清单中的每一项。确保 mutation 在失败时返回 { result, errors } 形态。

    rescue ActiveRecord::RecordInvalid => e
  { order: nil, errors: e.record.errors.full_messages }

  7. RUN： 在提 PR 之前确保完整测试套件通过。

HARD-GATE 检查清单

在交付 resolver/mutation 切片之前，必须确认以下所有事项：

  • Specs —— 覆盖正常路径、未认证、未授权、校验错误、N+1 计数和 schema 限制。
  • N+1 Prevention —— 每个关联都使用 dataloader.with(Source, Model).load(id)；绝不要使用 object.association。
  • Dataloader Priming —— 集合 resolver 在关联字段解析之前预加载记录。
  • Authorization —— 敏感字段有字段级防护（不能只有类型级防护）。
  • Type Conventions —— 分页集合使用 Types::*Type.connection_type，而不是普通数组。
  • Schema Safeguards —— 生产环境禁用 introspection；设置 max_depth 和 max_complexity。
  • Error Handling —— mutation 使用 rescue 块返回 { result, errors }；没有未处理异常。
  • Documentation —— 每个类型中的每个字段都有 description:。
  • Resolver Structure —— 使用专用 resolver 类，而不是内联 field block。

扩展资源（渐进式披露）

仅在需要其特定内容时加载这些文件：

  • TESTING.md —— spec 模板、路径和检查清单。
  • EXAMPLES.md —— dataloader、mutation 和类型的详细代码示例。

集成

技能何时串联
define-domain-language类型和字段命名必须与业务语言一致
plan-tests选择第一个失败的 spec（mutation vs query vs resolver unit）
write-tests对 resolver 和 mutation 执行完整 TDD 周期
security-check认证、禁用 introspection、查询深度/复杂度限制

评论

支持 Markdown