graphql-api-design
Design GraphQL APIs with well-structured schemas, efficient resolvers, pagination, and performance patterns like DataLoader and federation.
awesome-ai-agent-skills · 已有静态检查记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add h4vzz/awesome-ai-agent-skills --skill graphql-api-design技能说明
name: graphql-api-design description: Design GraphQL APIs with well-structured schemas, efficient resolvers, pagination, and performance patterns like DataLoader and federation. license: MIT metadata: author: awesome-ai-agent-skills version: 1.0.0
GraphQL API Design
This skill enables an AI agent to design complete GraphQL APIs from specifications, schemas, or natural language descriptions. The agent produces type definitions, queries, mutations, subscriptions, input types, enums, and resolver implementations. It applies performance patterns including DataLoader for N+1 prevention, cursor-based pagination via the Relay connection spec, query depth limiting, and schema federation for microservice architectures.
Workflow
-
Model the domain as types: Analyze the application domain and define GraphQL object types, input types, enums, interfaces, and unions. Each type should represent a real entity with fields that match the data consumers actually need. Use non-nullable (
!) annotations deliberately—fields that can genuinely be absent should be nullable. Prefer specific scalar types (e.g.,DateTime,URL) over rawStringfor self-documenting schemas. -
Design queries and mutations: Define Query fields for read operations and Mutation fields for write operations. Queries should be noun-based (
user,posts) while mutations should be verb-based (createPost,updateUser). Each mutation should accept a single input type argument and return a payload type that includes the modified object plus any user-facing errors. This pattern keeps mutations consistent and extensible. -
Implement pagination with connections: For any list field that could return many items, use the Relay connection specification with
edges,node,cursor, andpageInfo. This provides cursor-based pagination that is stable under insertions and deletions, unlike offset-based pagination. Define reusable connection types per entity rather than returning raw arrays. -
Write resolvers with DataLoader: Implement resolvers that use DataLoader to batch and cache database lookups within a single request. Without DataLoader, a query that fetches 50 posts and their authors would make 50 separate author queries (the N+1 problem). DataLoader collapses these into a single batched query. Create a new DataLoader instance per request to avoid leaking data between users.
-
Add subscriptions for real-time data: Define Subscription fields for events clients need to react to in real-time (e.g., new messages, status changes). Use a pub/sub backend (Redis, Kafka, or in-memory for development) to publish events. Keep subscription payloads lean—clients can use the subscription trigger to refetch full data if needed.
-
Secure and optimize the schema: Add query depth limiting (max 10-15 levels) and query complexity analysis to prevent abusive queries. Implement field-level authorization in resolvers. Use persisted queries in production to reduce bandwidth and prevent arbitrary query execution. Consider schema federation if the API spans multiple services.
Supported Technologies
- Servers: Apollo Server, GraphQL Yoga, Mercurius (Fastify), Strawberry (Python), graphql-java
- Schema tools: SDL-first (typeDefs), code-first (TypeGraphQL, Nexus, Pothos)
- Performance: DataLoader, @defer/@stream directives, persisted queries, automatic persisted queries (APQ)
- Federation: Apollo Federation, GraphQL Mesh, Schema Stitching
- Testing: GraphQL Playground, Apollo Studio, graphql-test (jest), Insomnia
Usage
Provide the agent with a description of the data entities, their relationships, and the operations needed. The agent will produce a complete SDL schema, resolver implementations, and DataLoader setup. Specify whether you want SDL-first or code-first output, and which server framework to target.
Examples
Example 1: Blog Platform Schema with Resolvers
# schema.graphql — Complete blog platform schema
scalar DateTime
enum PostStatus {
DRAFT
PUBLISHED
ARCHIVED
}
type User {
id: ID!
username: String!
email: String!
bio: String
avatarUrl: String
posts(first: Int, after: String): PostConnection!
createdAt: DateTime!
}
type Post {
id: ID!
title: String!
slug: String!
content: String!
excerpt: String
status: PostStatus!
author: User!
tags: [Tag!]!
comments(first: Int, after: String): CommentConnection!
publishedAt: DateTime
createdAt: DateTime!
updatedAt: DateTime!
}
type Comment {
id: ID!
body: String!
author: User!
post: Post!
createdAt: DateTime!
}
type Tag {
id: ID!
name: String!
slug: String!
posts(first: Int, after: String): PostConnection!
}
# Relay connection types for cursor-based pagination
type PostConnection {
edges: [PostEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type PostEdge {
cursor: String!
node: Post!
}
type CommentConnection {
edges: [CommentEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type CommentEdge {
cursor: String!
node: Comment!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
# Queries
type Query {
post(id: ID, slug: String): Post
posts(
first: Int = 10
after: String
status: PostStatus
tagSlug: String
): PostConnection!
user(id: ID!): User
me: User
tags: [Tag!]!
}
# Mutations with input types and payload types
input CreatePostInput {
title: String!
content: String!
tagIds: [ID!]
status: PostStatus = DRAFT
}
type CreatePostPayload {
post: Post
errors: [MutationError!]!
}
input UpdatePostInput {
title: String
content: String
status: PostStatus
tagIds: [ID!]
}
type UpdatePostPayload {
post: Post
errors: [MutationError!]!
}
type MutationError {
field: String
message: String!
}
type Mutation {
createPost(input: CreatePostInput!): CreatePostPayload!
updatePost(id: ID!, input: UpdatePostInput!): UpdatePost
阅读完整来源 ↗