AgentSkillsCN

graphql

提供 GraphQL API 模式设计与实现的专业知识。确保类型定义规范、查询/变更模式合理、分页策略得当，并遵循统一的错误处理标准。擅长以模式优先的设计方法，精通解析器实现、DataLoader 以避免 N+1 查询问题、订阅模式以及联邦架构；同时，能够高效实施 Relay 游标连接和 Apollo 最佳实践。 适用场景：设计 GraphQL 模式、定义类型与接口、实现查询与变更、创建解析器、以连接与边设计分页方案、利用 DataLoader 解决 N+1 查询难题、为实时更新实现订阅功能、妥善处理错误与空值情况、搭建 GraphQL 联邦架构，或与 Apollo Server/Client 及其他 GraphQL 库进行深度集成。

SKILL.md
--- frontmatter
name: graphql
description: |
  Provides GraphQL API schema design and implementation expertise. Ensures proper type definitions, query/mutation patterns, pagination strategies, and error handling standards. Specializes in schema-first design, resolver implementation, DataLoader for N+1 prevention, subscription patterns, and federation architecture. Implements Relay cursor connections and Apollo best practices.
  Use when: designing GraphQL schemas, defining types and interfaces, implementing queries and mutations, creating resolvers, designing pagination with connections and edges, solving N+1 query problems with DataLoader, implementing subscriptions for real-time updates, handling errors and nullability, setting up GraphQL federation, or integrating with Apollo Server/Client or other GraphQL libraries.

GraphQL API Standards

Naming Conventions

Field Naming

  • •Boolean: Require is/has/can prefix
  • •Date: Require ~At suffix
  • •Use consistent terminology throughout the project (unify on either "create" or "add")

Date Format

  • •ISO 8601 UTC
  • •Use DateTime type

Pagination

Relay Connection Specification

graphql
type UserConnection {
  edges: [UserEdge!]!
  pageInfo: PageInfo!
}

type UserEdge {
  node: User!
  cursor: String!
}

type PageInfo {
  hasNextPage: Boolean!
  endCursor: String
}
  • •Parameters: first, after

Sorting

  • •orderBy: [{ field: "createdAt", order: DESC }]

Type Naming

  • •Input: {Verb}{Type}Input
  • •Connection: {Type}Connection
  • •Edge: {Type}Edge

Input

  • •Separate creation and modification (required for creation, optional for modification)
  • •Avoid nesting - IDs only

Errors

extensions (default)

  • •code, field in errors[].extensions

Union (type safety)

  • •User | ValidationError

N+1

  • •DataLoader is mandatory

Documentation

  • •"""description""" is required
  • •Explicitly state Input constraints

Deprecation

  • •@deprecated(reason: "...")
  • •Never delete types