What are the best practices for GraphQL Schema design

GraphQL Schema Design Best Practices

GraphQL Schema is the core of the API. Good Schema design can improve development efficiency, reduce maintenance costs, and provide better developer experience.

1. Schema Basic Structure

Type Definitions

graphql
type User {
  id: ID!
  name: String!
  email: String!
  age: Int
  posts: [Post!]!
  createdAt: DateTime!
}

type Post {
  id: ID!
  title: String!
  content: String!
  author: User!
  comments: [Comment!]!
  createdAt: DateTime!
}

type Comment {
  id: ID!
  text: String!
  author: User!
  post: Post!
  createdAt: DateTime!
}

Input Types

graphql
input CreateUserInput {
  name: String!
  email: String!
  age: Int
}

input CreatePostInput {
  title: String!
  content: String!
  authorId: ID!
}

Enum Types

graphql
enum PostStatus {
  DRAFT
  PUBLISHED
  ARCHIVED
}

Union Types

graphql
union SearchResult = User | Post | Comment

Interface Types

graphql
interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  name: String!
  email: String!
}

type Post implements Node {
  id: ID!
  title: String!
  content: String!
}

2. Naming Conventions

Type Naming

• Use PascalCase (first letter uppercase)
• Use descriptive names
• Avoid abbreviations
• Use singular form

Examples:

graphql
# Good naming
type UserProfile { }
type Article { }
type ShoppingCart { }

# Bad naming
type user { }
type Art { }
type ShopCart { }

Field Naming

• Use camelCase (first letter lowercase)
• Use verbs or nouns
• Avoid reserved words

Examples:

graphql
# Good naming
type User {
  firstName: String!
  lastName: String!
  fullName: String!
  isActive: Boolean!
}

# Bad naming
type User {
  first_name: String!
  LastName: String!
  Full_Name: String!
  active: Boolean!
}

Parameter Naming

• Use camelCase
• Descriptive names
• Include unit or type information

Examples:

graphql
# Good naming
query GetUsers($limit: Int, $offset: Int) { }
query GetPosts($after: String, $first: Int) { }

# Bad naming
query GetUsers($l: Int, $o: Int) { }
query GetPosts($a: String, $f: Int) { }

3. Type Design Principles

Avoid Excessive Nesting

graphql
# Bad design - excessive nesting
type User {
  posts {
    comments {
      author {
        posts {
          comments {
            # Infinite nesting
          }
        }
      }
    }
  }
}

# Good design - reasonable nesting
type User {
  posts(limit: Int): [Post!]!
}

type Post {
  comments(limit: Int): [Comment!]!
}

Use Input Types to Encapsulate Parameters

graphql
# Bad design - too many parameters
mutation CreateUser($name: String!, $email: String!, $age: Int, $address: String, $phone: String) { }

# Good design - use input types
input CreateUserInput {
  name: String!
  email: String!
  age: Int
  address: String
  phone: String
}

mutation CreateUser($input: CreateUserInput!) { }

Implement Pagination

graphql
# Cursor-based pagination (recommended)
type PageInfo {
  hasNextPage: Boolean!
  hasPreviousPage: Boolean!
  startCursor: String
  endCursor: String
}

type PostConnection {
  edges: [PostEdge!]!
  pageInfo: PageInfo!
  totalCount: Int!
}

type PostEdge {
  node: Post!
  cursor: String!
}

type Query {
  posts(after: String, first: Int): PostConnection!
}

# Offset-based pagination
type PostResult {
  posts: [Post!]!
  total: Int!
  page: Int!
  pageSize: Int!
}

type Query {
  posts(offset: Int, limit: Int): PostResult!
}

4. Error Handling

Custom Error Types

graphql
type Error {
  code: String!
  message: String!
  field: String
}

type UserResult {
  user: User
  errors: [Error!]!
}

type Mutation {
  createUser(input: CreateUserInput!): UserResult!
}

Use Nullable Fields

graphql
type Mutation {
  # Return nullable type to indicate possible failure
  createUser(input: CreateUserInput!): User
}

5. Version Control and Evolution

Deprecate Fields

graphql
type User {
  id: ID!
  name: String!
  # Deprecated field, provide alternative
  fullName: String @deprecated(reason: "Use 'name' instead")
  email: String!
}

Add New Fields

graphql
type User {
  id: ID!
  name: String!
  email: String!
  # New field, doesn't affect existing clients
  phoneNumber: String
}

6. Performance Optimization

Use DataLoader

javascript
const userLoader = new DataLoader(async (userIds) => {
  const users = await User.findAll({ where: { id: userIds } });
  return userIds.map(id => users.find(user => user.id === id));
});

Field-level Permission Control

graphql
type User {
  id: ID!
  name: String!
  # Sensitive fields require permissions
  email: String! @auth(requires: ADMIN)
  salary: Float @auth(requires: ADMIN)
}

7. Documentation and Description

Add Descriptions

graphql
"""
User type containing user's basic information
"""
type User {
  """
  User unique identifier
  """
  id: ID!
  
  """
  User name, maximum length 100 characters
  """
  name: String!
  
  """
  User email address, must be valid email format
  """
  email: String!
}

8. Best Practices Summary

1. Keep it Simple: Avoid over-design, keep Schema concise and clear
2. Consistency: Maintain naming and structure consistency throughout the project
3. Extensibility: Consider future expansion needs when designing
4. Backward Compatibility: Maintain backward compatibility when adding new features
5. Documentation: Add descriptions for all types, fields, and parameters
6. Performance Considerations: Avoid excessive nesting, use pagination reasonably
7. Security: Implement appropriate permission control and validation
8. Testing: Write unit tests and integration tests for Resolvers