graphql-schema
Guide for designing GraphQL schemas following industry best practices. Use this skill when: (1) designing a new GraphQL schema or API, (2) reviewing existing schema for improvements, (3) deciding on type structures or nullability, (4) implementing pagination or error patterns, (5) ensuring security in schema design.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 29
- Forks
- 156
01 前言 Front Matter
- name
- graphql-schema
- license
- MIT
- metadata
- { "author": "apollographql", "version": "1.0.1" }
- description
- Guide for designing GraphQL schemas following industry best practices. Use this skill when: (1) designing a new GraphQL schema or API, (2) reviewing existing schema for improvements, (3) deciding on type structures or nullability, (4) implementing pagination or error patterns, (5) ensuring security in schema design.
- allowed-tools
- Bash(npm:*) Bash(npx:*) Read Write Edit Glob Grep
- compatibility
- Any GraphQL implementation (Apollo Server, graphql-js, Yoga, etc.)
02 资源文件 5
- 参考文档references/errors.md6.5 KB
- 参考文档references/naming.md6.7 KB
- 参考文档references/pagination.md7.0 KB
- 参考文档references/security.md9.1 KB
- 参考文档references/types.md7.8 KB
03 SKILL.md 正文
GraphQL Schema Design Guide
This guide covers best practices for designing GraphQL schemas that are intuitive, performant, and maintainable. Schema design is primarily a server-side concern that directly impacts API usability.
Schema Design Principles
1. Design for Client Needs
- Think about what queries clients will write
- Organize types around use cases, not database tables
- Expose capabilities, not implementation details
2. Be Explicit
- Use clear, descriptive names
- Make nullability intentional
- Document with descriptions
3. Design for Evolution
- Plan for backwards compatibility
- Use deprecation before removal
- Avoid breaking changes
Quick Reference
Type Definition Syntax
"""
A user in the system.
"""
type User {
id: ID!
email: String!
name: String
posts(first: Int = 10, after: String): PostConnection!
createdAt: DateTime!
}
Nullability Rules
| Pattern | Meaning |
|---|---|
| String | Nullable - may be null |
| String! | Non-null - always has value |
| [String] | Nullable list, nullable items |
| [String!] | Nullable list, non-null items |
| [String]! | Non-null list, nullable items |
| [String!]! | Non-null list, non-null items |
Best Practice: Use [Type!]! for lists - empty list over null, no null items.
Input vs Output Types
# Output type - what clients receive
type User {
id: ID!
email: String!
createdAt: DateTime!
}
# Input type - what clients send
input CreateUserInput {
email: String!
name: String
}
# Mutation using input type
type Mutation {
createUser(input: CreateUserInput!): User!
}
Interface Pattern
interface Node {
id: ID!
}
type User implements Node {
id: ID!
email: String!
}
type Post implements Node {
id: ID!
title: String!
}
Union Pattern
union SearchResult = User | Post | Comment
type Query {
search(query: String!): [SearchResult!]!
}
Reference Files
Detailed documentation for specific topics:
- Types - Type design patterns, interfaces, unions, and custom scalars
- Naming - Naming conventions for types, fields, and arguments
- Pagination - Connection pattern and cursor-based pagination
- Errors - Error modeling and result types
- Security - Security best practices for schema design
Key Rules
Type Design
- Define types based on domain concepts, not data storage
- Use interfaces for shared fields across types
- Use unions for mutually exclusive types
- Keep types focused (single responsibility)
- Avoid deep nesting - flatten when possible
Field Design
- Fields should be named from client's perspective
- Return the most specific type possible
- Make expensive fields explicit (consider arguments)
- Use arguments for filtering, sorting, pagination
Mutation Design
- Use single input argument pattern:
mutation(input: InputType!) - Return affected objects in mutation responses
- Model mutations around business operations, not CRUD
- Consider returning a union of success/error types
ID Strategy
- Use globally unique IDs when possible
- Implement
Nodeinterface for refetchability - Base64-encode compound IDs if needed
Ground Rules
- ALWAYS add descriptions to types and fields
- ALWAYS use non-null (!) for fields that cannot be null
- ALWAYS use [Type!]! pattern for lists
- NEVER expose database internals in schema
- NEVER break backwards compatibility without deprecation
- PREFER dedicated input types over many arguments
- PREFER enums over arbitrary strings for fixed values
- USE
IDtype for identifiers, notStringorInt - USE custom scalars for domain-specific values (DateTime, Email, URL)
04 同仓库更多 Skills
business-data
暂无简介
workflow
Creates durable, resumable workflows using Vercel's Workflow SDK. Use when building workflows that need to survive restarts, pause for external events, retry on failure, or coordinate multi-step operations over time. Triggers on mentions of "workflow", "durable functions", "resumable", "workflow sdk", "queue", "event", "push", "subscribe", or step-based orchestration.
workflow
Vercel Workflow SDK expert guidance. Use when building durable workflows, long-running tasks, API routes or agents that need pause/resume, retries, step-based execution, or crash-safe orchestration with Vercel Workflow.
verification
Full-story verification — infers what the user is building, then verifies the complete flow end-to-end: browser → API → data → response. Triggers on dev server start and 'why isn't this working' signals.
vercel-storage
Vercel storage expert guidance — Blob, Global Config (formerly Edge Config), and Marketplace storage (Neon Postgres, Upstash Redis). Use when choosing, configuring, or using data storage with Vercel applications.
vercel-services
Configure and troubleshoot Vercel Services for multiple frontends and backends in one project. Use when composing a polyglot or multi-service application on one Vercel deployment; defining the `services` key, service-targeted rewrites, or service bindings in `vercel.json`; or running all services with `vercel dev`.