Schema Design Best Practices
# Use Relay pagination spec throughout
# Use mutation payload types with errors array
# Name mutations as verb + noun
# Use enums for finite sets
# Make scalar types explicit
type Query {
node(id: ID!): Node # Global node interface (Relay spec)
users(
first: Int
after: String
last: Int
before: String
filter: UserFilter
orderBy: UserOrderBy = { field: CREATED_AT, direction: DESC }
): UserConnection!
user(id: ID!): User
}
interface Node {
id: ID!
}
type User implements Node {
id: ID!
email: String!
displayName: String!
createdAt: DateTime!
# Nested connections — implement with DataLoader
posts(first: Int, after: String): PostConnection!
followers(first: Int): UserConnection!
}
type UserConnection {
edges: [UserEdge!]!
pageInfo: PageInfo!
totalCount: Int!
}
type UserEdge {
node: User!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
hasPreviousPage: Boolean!
startCursor: String
endCursor: String
}
# Mutation payload pattern — structured errors
type Mutation {
createPost(input: CreatePostInput!): CreatePostPayload!
updatePost(id: ID!, input: UpdatePostInput!): UpdatePostPayload!
deletePost(id: ID!): DeletePostPayload!
}
type CreatePostPayload {
post: Post # null if errors
errors: [UserError!]!
clientMutationId: String # Relay spec
}
type UserError {
field: [String!] # Which field (null = form-level)
code: String!
message: String!
}
input CreatePostInput {
title: String!
content: String!
tags: [String!]
status: PostStatus = DRAFT
}
enum PostStatus {
DRAFT
PUBLISHED
ARCHIVED
}
scalar DateTime
scalar JSON
Resolvers with TypeScript
// Apollo Server 4 with TypeScript
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
import { makeExecutableSchema } from '@graphql-tools/schema';
interface Context {
user: AuthUser | null;
loaders: ReturnType<typeof createLoaders>;
db: Database;
}
const resolvers = {
Query: {
users: async (_, { first = 20, after, filter }, ctx: Context) => {
const users = await ctx.db.users.findMany({
take: first + 1, // Fetch one extra to determine hasNextPage
cursor: after ? { id: decodeCursor(after) } : undefined,
where: buildUserFilter(filter),
orderBy: { createdAt: 'desc' },
});
const hasNextPage = users.length > first;
const nodes = hasNextPage ? users.slice(0, -1) : users;
return {
edges: nodes.map(user => ({
node: user,
cursor: encodeCursor(user.id),
})),
pageInfo: {
hasNextPage,
hasPreviousPage: !!after,
startCursor: nodes[0] ? encodeCursor(nodes[0].id) : null,
endCursor: nodes.at(-1) ? encodeCursor(nodes.at(-1)!.id) : null,
},
totalCount: () => ctx.db.users.count({ where: buildUserFilter(filter) }),
};
},
user: async (_, { id }, ctx: Context) => {
return ctx.loaders.user.load(id); // DataLoader for batching
},
},
User: {
// N+1 solution: use DataLoader
posts: async (user, { first = 10, after }, ctx: Context) => {
return ctx.loaders.userPosts.load({ userId: user.id, first, after });
},
// Computed field
displayName: (user) => user.name || user.email.split('@')[0],
},
Mutation: {
createPost: async (_, { input }, ctx: Context) => {
if (!ctx.user) {
return {
post: null,
errors: [{ code: 'UNAUTHENTICATED', message: 'Must be logged in', field: null }],
};
}
// Validate
const errors = validateCreatePost(input);
if (errors.length > 0) return { post: null, errors };
try {
const post = await ctx.db.posts.create({
data: { ...input, authorId: ctx.user.id }
});
return { post, errors: [] };
} catch (e) {
return {
post: null,
errors: [{ code: 'DATABASE_ERROR', message: 'Failed to create post', field: null }]
};
}
},
},
};
DataLoader (N+1 Prevention)
import DataLoader from 'dataloader';
import { PrismaClient } from '@prisma/client';
export function createLoaders(db: PrismaClient) {
return {
// Batch user lookups
user: new DataLoader<string, User | null>(
async (ids) => {
const users = await db.user.findMany({
where: { id: { in: ids as string[] } },
});
const map = new Map(users.map(u => [u.id, u]));
return ids.map(id => map.get(id) ?? null);
},
{
cache: true, // Cache per request (default)
maxBatchSize: 100, // Max batch size
batchScheduleFn: (callback) => setTimeout(callback, 0), // Next tick
}
),
// Batch load posts by userId
userPosts: new DataLoader<string, Post[]>(
async (userIds) => {
const posts = await db.post.findMany({
where: { authorId: { in: userIds as string[] } },
orderBy: { createdAt: 'desc' },
});
// Group by authorId, preserving order
const grouped = userIds.map(userId =>
posts.filter(p => p.authorId === userId)
);
return grouped;
},
{ cache: false } // No caching for time-sensitive data
),
};
}
// Create fresh loaders per request (prevents cache bleeding between users)
// In Apollo context:
const server = new ApolloServer({ resolvers, typeDefs });
startStandaloneServer(server, {
context: async ({ req }) => ({
user: await getUserFromToken(req.headers.authorization),
loaders: createLoaders(prisma), // NEW loaders per request
db: prisma,
}),
});
Subscriptions
import { createServer } from 'http';
import { WebSocketServer } from 'ws';
import { useServer } from 'graphql-ws/lib/use/ws';
import { PubSub } from 'graphql-subscriptions';
const pubsub = new PubSub();
// In production, use Redis-based PubSub for multi-server:
// import { RedisPubSub } from 'graphql-redis-subscriptions';
// const pubsub = new RedisPubSub({ publisher: redisClient, subscriber: redisClient });
const resolvers = {
Subscription: {
postCreated: {
subscribe: (_, args, ctx) => {
// Authorization check
if (!ctx.user) throw new Error('Unauthorized');
return pubsub.asyncIterator(['POST_CREATED']);
},
resolve: (payload) => payload.postCreated,
},
// Filter subscription events
postUpdated: {
subscribe: withFilter(
() => pubsub.asyncIterator(['POST_UPDATED']),
(payload, variables) => payload.postUpdated.authorId === variables.authorId
),
},
},
Mutation: {
createPost: async (_, { input }, ctx) => {
const post = await ctx.db.posts.create({ data: input });
// Publish to subscribers
await pubsub.publish('POST_CREATED', { postCreated: post });
return { post, errors: [] };
},
},
};
GraphQL Federation (Microservices)
// Subgraph: users service
import { buildSubgraphSchema } from '@apollo/subgraph';
import { gql } from 'graphql-tag';
const userSchema = gql`
extend schema @link(url: "https://specs.apollo.dev/federation/v2.3")
type Query {
me: User
user(id: ID!): User
}
type User @key(fields: "id") { # This type is "owned" by users service
id: ID!
email: String!
name: String!
}
`;
// Subgraph: posts service
const postSchema = gql`
extend schema @link(url: "https://specs.apollo.dev/federation/v2.3")
type Query {
posts: [Post!]!
}
type Post {
id: ID!
title: String!
author: User! # References User from users service
}
# Extend User to add posts field (without owning the User type)
extend type User @key(fields: "id") {
id: ID! @external # ID comes from users service
posts: [Post!]! # Added by posts service
}
`;
const resolvers = {
User: {
// Federation: resolve User from just its key
__resolveReference: async ({ id }) => {
return db.users.findUnique({ where: { id } });
},
posts: async (user) => {
return db.posts.findMany({ where: { authorId: user.id } });
},
},
};
// Automatic Persisted Queries (APQ) reduce bandwidth
// Client sends hash first, server responds with error if not found, then client sends full query
import { ApolloServer } from '@apollo/server';
import { createPersistedQueryLink } from "@apollo/client/link/persisted-queries";
import { generatePersistedQueryIdsFromManifest } from "@apollo/persisted-query-lists";
import { sha256 } from 'crypto-hash';
// Server-side: allow only registered operations (safelisting)
const server = new ApolloServer({
typeDefs,
resolvers,
// Only allow pre-registered operations in production
allowBatchedHttpRequests: true,
csrfPrevention: true,
});
// Client-side APQ link
const link = createPersistedQueryLink({ sha256 }).concat(httpLink);
Security Patterns
// Depth limiting — prevent deeply nested queries (DoS protection)
import depthLimit from 'graphql-depth-limit';
import { createComplexityLimitRule } from 'graphql-validation-complexity';
const server = new ApolloServer({
typeDefs,
resolvers,
validationRules: [
depthLimit(10), // Max query depth
createComplexityLimitRule(1000, { // Max complexity score
scalarCost: 1,
objectCost: 2,
listFactor: 10,
}),
],
plugins: [
{
// Log expensive queries
requestDidStart: async () => ({
willSendResponse: async ({ response, metrics }) => {
if (metrics.executionStarted) {
const duration = Date.now() - metrics.executionStarted;
if (duration > 1000) {
logger.warn('Slow GraphQL query', {
duration,
operationName: response.http.headers.get('x-apollo-operation-name'),
});
}
}
},
}),
},
],
});