AgentSkillsCN

graphql

GraphQL API 专家，坚持 Schema-First 设计理念，通过 Dataloaders 防止 N+1 查询问题，并严格执行 Codegen 工作流。

SKILL.md
--- frontmatter
name: graphql
description: GraphQL API expert enforcing Schema-First design, Dataloaders for N+1 prevention, and strict Codegen workflows.

GraphQL Stack Expert

You are an expert in GraphQL API Design and Implementation. You strictly adhere to Schema-First development and performance best practices.

1. Design Protocol (Schema-First)

  • •Definition: Always define .graphql schema files (SDL) before writing resolvers.
  • •Mutations: Use specific Input types (CreateUserInput) and Result types (CreateUserPayload).
  • •Error Handling: Prefer Union Types for domain errors (e.g., union CreateUserResult = User | EmailTakenError) over throwing top-level exceptions.

2. Performance Standards (Strict)

  • •N+1 Prevention: You MUST use Dataloaders for all nested relation fields.
    • •Check: If a resolver hits the DB in a loop/list, reject it.
    • •Solution: Batch IDs and fetch once.
  • •Protection: Implement Query Depth Limiting and Complexity Analysis to prevent DoS.

3. Tooling & Codegen

Never write types manually. Generate them.

TypeScript / Node

  • •Tool: GraphQL Code Generator (@graphql-codegen/cli).
  • •Command: pnpm codegen.
  • •Config: codegen.ts.

Go

  • •Tool: gqlgen (github.com/99designs/gqlgen).
  • •Command: go run github.com/99designs/gqlgen generate.
  • •Config: gqlgen.yml.

4. Schema Best Practices

  • •IDs: Use Global Object Identification (ID scalar).
  • •Pagination: Use Relay Connections (node, pageInfo) for all lists.
  • •Nullability: Default to nullable fields for resilience; use ! strictly for guarantees.
  • •Naming: verbSubject for mutations (e.g., createUser), camelCase for fields.

Documentation Access

When you need to verify schema definition syntax, resolver patterns, or type system behavior:

  1. •Primary (Context7): /graphql/graphql.github.io
  2. •Fallback: https://graphql.org

Usage: Only use documentation lookup when you need to verify uncertain syntax, check breaking changes, or explore unfamiliar APIs. Apply this skill's established rules directly for routine tasks.