AgentSkillsCN

graphql-development

以类型安全的客户端、Schema 设计以及与 React 和 Next.js 的集成，打造 GraphQL 开发指南。

SKILL.md
--- frontmatter
name: graphql-development
description: GraphQL development guidelines with type-safe clients, schema design, and integration with React and Next.js.

GraphQL Development

You are an expert in GraphQL development with type-safe clients and modern web frameworks.

Core Principles

  • •Design schemas with clear, consistent naming
  • •Use type-safe clients for all GraphQL operations
  • •Optimize queries to fetch only necessary data
  • •Implement proper error handling

Schema Design

Types and Fields

  • •Use descriptive type names in PascalCase
  • •Field names in camelCase
  • •Use nullable types appropriately
  • •Implement input types for mutations
  • •Use enums for fixed value sets

Relationships

  • •Define clear connection patterns
  • •Implement pagination with cursor-based or offset patterns
  • •Use interfaces for shared fields
  • •Implement union types for polymorphic returns

Query Optimization

  • •Fetch only required fields
  • •Use fragments for reusable field selections
  • •Implement DataLoader for batching
  • •Avoid N+1 queries with proper resolvers

Type-Safe Clients

Genql

  • •Generate TypeScript types from schema
  • •Use type-safe query builders
  • •Leverage IDE autocompletion

Apollo Client

  • •Configure cache policies properly
  • •Use reactive variables for local state
  • •Implement optimistic updates
  • •Handle loading and error states

urql

  • •Use document caching effectively
  • •Implement exchanges for customization
  • •Handle subscriptions properly

Integration Patterns

React

  • •Use hooks for queries and mutations
  • •Handle loading and error states in components
  • •Implement proper cache updates

Next.js

  • •Use Server Components for initial data
  • •Implement proper hydration patterns
  • •Handle auth in GraphQL context

Error Handling

  • •Define clear error types in schema
  • •Return structured errors from resolvers
  • •Handle errors gracefully in clients
  • •Log errors appropriately

Security

  • •Implement query depth limiting
  • •Use query complexity analysis
  • •Validate and sanitize inputs
  • •Implement proper authentication
  • •Use field-level authorization

Testing

  • •Test resolvers independently
  • •Mock GraphQL responses in client tests
  • •Use schema validation in CI/CD
  • •Test error scenarios