graphql-expert · martinholovsky — Claude Code skill: GraphQL and setup
graphql-expert is a Claude Code skill for designing GraphQL schemas, building resolvers, and working with federation. It activates for API development, Apollo Server tasks, and query performance work.
Unlicense 220 installs ★ 48 updated 2025-12-06
npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a claude-codeWhat graphql-expert does
graphql-expert guides GraphQL API work through schema design and test-first resolver implementation. It points to GraphQL Code Generator for end-to-end type safety and DataLoader for batching data loads. Its guidance also covers query complexity limits, field authorization, and input validation.
Before writing code, the skill calls for checking Apollo Server settings against official documentation and confirming directives against the GraphQL specification. It also directs the agent to inspect existing project patterns and search the docs when needed. A schema error can break the whole API.
What it helps with
- design GraphQL types before implementing resolvers
- write tests for resolvers and integrations first
- address N+1 queries with DataLoader
- limit query complexity and field access
- verify Apollo Server settings and GraphQL directives
Example prompts for the agent
- Design a GraphQL schema for this API and write resolver tests first.
- Check these resolvers for N+1 queries and suggest a DataLoader approach.
- Set up GraphQL federation and verify the directives against Apollo documentation.
How to install graphql-expert
1Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a claude-code2Manually: put the files in place
~/.claude/skills/graphql-expert/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/graphql-expert/
1Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a codex2Manually: put the files in place
.agents/skills/graphql-expert/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a cursor2Manually: put the files in place
.cursor/skills/graphql-expert/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install martinholovsky/claude-skills-generator skills/graphql-expert2Manually: put the files in place
.github/skills/graphql-expert/SKILL.md1Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a gemini-cli2Platform CLI
gemini skills install https://github.com/martinholovsky/claude-skills-generator --path skills/graphql-expertManually: put the files in place
.devin/skills/graphql-expert/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about graphql-expert
How do I install graphql-expert in Claude Code?
Run npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a claude-code. The skill file is located at ~/.claude/skills/graphql-expert/SKILL.md.
What does graphql-expert do?
It guides GraphQL API development, including schema design, resolver tests, type safety, query performance, and security checks.
How does graphql-expert verify Apollo Server and GraphQL code?
It directs the agent to check Apollo Server settings against official docs and validate directives against the GraphQL specification before implementing uncertain APIs.
Source text
SKILL.md · Unlicense
---
name: graphql-expert
description: "Expert GraphQL developer specializing in type-safe API development, schema design, resolver optimization, and federation architecture. Use when building GraphQL APIs, implementing Apollo Server, optimizing query performance, or designing federated microservices."
model: sonnet
---
# GraphQL API Development Expert
## 0. Anti-Hallucination Protocol
**🚨 MANDATORY: Read before implementing any code using this skill**
### Verification Requirements
When using this skill to implement GraphQL features, you MUST:
1. **Verify Before Implementing**
- ✅ Check official Apollo Server 4+ documentation
- ✅ Confirm GraphQL spec compliance for directives/types
- ✅ Validate DataLoader patterns are current
- ❌ Never guess Apollo Server configuration options
- ❌ Never invent GraphQL directives
- ❌ Never assume federation resolver syntax
2. **Use Available Tools**
- 🔍 Read: Check existing codebase for GraphQL patterns
- 🔍 Grep: Search for similar resolver implementations
- 🔍 WebSearch: Verify APIs in Apollo/GraphQL docs
- 🔍 WebFetch: Read official Apollo Server documentation
3. **Verify if Certainty < 80%**
- If uncertain about ANY GraphQL API/directive/config
- STOP and verify before implementing
- Document verification source in response
- GraphQL schema errors break entire API - verify first
4. **Common GraphQL Hallucination Traps** (AVOID)
- ❌ Invented Apollo Server plugins or options
- ❌ Made-up GraphQL directives
- ❌ Fake DataLoader methods
- ❌ Non-existent federation directives
- ❌ Wrong resolver signature patterns
### Self-Check Checklist
Before EVERY response with GraphQL code:
- [ ] All imports verified (@apollo/server, graphql, etc.)
- [ ] All Apollo Server configs verified against v4 docs
- [ ] Schema directives are real GraphQL spec
- [ ] DataLoader API signatures are correct
- [ ] Federation directives match Apollo Federation spec
- [ ] Can cite official documentation
**⚠️ CRITICAL**: GraphQL code with hallucinated APIs causes schema errors and runtime failures. Always verify.
---
## 1. Overview
**Risk Level: HIGH** ⚠️
- API security vulnerabilities (query depth attacks, complexity attacks)
- Data exposure risks (unauthorized field access, over-fetching)
- Performance issues (N+1 queries, unbounded queries)
- Authentication/authorization bypass
You are an elite GraphQL developer with deep expertise in:
---
## 2. Core Principles
1. **TDD First** - Write tests before implementation. Every resolver, schema type, and integration must have tests written first.
2. **Performance Aware** - Optimize for efficiency from day one. Use DataLoader batching, query complexity limits, and caching strategies.
3. **Schema-First Design** - Design schemas before implementing resolvers. Use SDL for clear type definitions.
4. **Security by Default** - Implement query limits, field authorization, and input validation as baseline requirements.
5. **Type Safety End-to-End** - Use GraphQL Code Generator for type-safe resolvers and client operations.
6. **Fail Fast, Fail Clearly** - Validate schemas at startup, provide clear error messages, and catch issues early.
---
## 3. Implementation Workflow (TDD)
### Step 1: Write Failing Test First
```python
# tests/test_resolvers.py
import pytest
from unittest.mock import AsyncMock, MagicMock
from ariadne import make_executable_schema, graphql
from src.schema import type_defs
from src.resolvers import resolvers
@pytest.fixture
def schema():
return make_executable_schema(type_defs, resolvers)
@pytest.fixture
def mock_context():
return {
"user": {"id": "user-1", "role": "USER"},
"loaders": {
"user_loader": AsyncMock(),
"post_loader": AsyncMock(),
}
}
class TestUserResolver:
@pytest.mark.asyncio
async def test_get_user_by_id(self, schema, mock_context):
"""Test user query returns correct user data."""
# Arrange
mock_context["loaders"]["user_loader"].load.return_value = {
"id": "user-1",
"email": "[email protected]",
"name": "Test User"
}
query = """
query GetUser($id: ID!) {
user(id: $id) {
id
email
name
}
}
"""
# Act
success, result = await graphql(
schema,
{"query": query, "variables": {"id": "user-1"}},
context_value=mock_context
)
# Assert
assert success
assert result["data"]["user"]["id"] == "user-1"
assert result["data"]["user"]["email"] == "[email protected]"
mock_context["loaders"]["user_loader"].load.assert_called_once_with("user-1")
@pytest.mark.asyncio
async def test_get_user_unauthorized_returns_error(self, schema):
"""Test user query without auth returns error."""
# Arrange - no user in context
context = {"user": None, "loaders": {}}
query = """
query GetUser($id: ID!) {
user(id: $id) {
id
email
}
}
"""
# Act
success, result = await graphql(
schema,
{"query": query, "variables": {"id": "user-1"}},
context_value=context
)
# Assert
assert "errors" in result
assert any("FORBIDDEN" in str(err) for err in result["errors"])
class TestMutationResolver:
@pytest.mark.asyncio
async def test_create_post_success(self, schema, mock_context):
"""Test createPost mutation creates post correctly."""
# Arrange
mock_context["db"] = AsyncMock()
mock_context["db"].create_post.return_value = {
"id": "post-1",
"title": "Test Post",
"content": "Test content",
"authorId": "user-1"
}
mutation = """
mutation CreatePost($input: CreatePostInput!) {
createPost(input: $input) {
post {
id
title
content
}
errors {
message
code
}
}
}
"""
variables = {
"input": {
"title": "Test Post",
"content": "Test content"
}
}
# Act
success, result = await graphql(
schema,
{"query": mutation, "variables": variables},
context_value=mock_context
)
# Assert
assert success
assert result["data"]["createPost"]["post"]["id"] == "post-1"
assert result["data"]["createPost"]["errors"] is None
@pytest.mark.asyncio
async def test_create_post_validation_error(self, schema, mock_context):
"""Test createPost with empty title returns validation error."""
mutation = """
mutation CreatePost($input: CreatePostInput!) {
createPost(input: $input) {
post {
id
}
errors {
message
field
code
}
}
}
"""
variables = {
"input": {
"title": "", # Invalid - empty title
"content": "Test content"
}
}
# Act
success, result = await graphql(
schema,
{"query": mutation, "variables": variables},
context_value=mock_context
)
# Assert
assert success
assert result["data"]["createPost"]["post"] is None
assert result["data"]["createPost"]["errors"][0]["field"] == "title"
assert result["data"]["createPost"]["errors"][0]["code"] == "VALIDATION_ERROR"
class TestDataLoaderBatching:
@pytest.mark.asyncio
async def test_posts_batched_author_loading(self, schema):
"""Test that multiple posts batch author loading."""
from dataloader import DataLoader
# Track how many times batch function is called
batch_calls = []
async def batch_load_users(user_ids):
batch_calls.append(list(user_ids))
return [{"id": uid, "name": f"User {uid}"} for uid in user_ids]
context = {
"user": {"id": "user-1", "role": "ADMIN"},
"loaders": {
"user_loader": DataLoader(batch_load_users)
}
}
query = """
query GetPosts {
posts(first: 3) {
edges {
node {
id
author {
id
name
}
}
}
}
}
"""
# Act
success, result = await graphql(schema, {"query": query}, context_value=context)
# Assert - should batch all author loads into single call
assert success
assert len(batch_calls) == 1 # Only one batch call, not N calls
```
### Step 2: Implement Minimum to Pass
```python
# src/resolvers.py
from ariadne import QueryType, MutationType, ObjectType
query = QueryType()
mutation = MutationType()
user_type = ObjectType("User")
post_type = ObjectType("Post")
@query.field("user")
async def resolve_user(_, info, id):
context = info.context
if not context.get("user"):
raise Exception("FORBIDDEN: Authentication required")
return await context["loaders"]["user_loader"].load(id)
@mutation.field("createPost")
async def resolve_create_post(_, info, input):
context = info.context
# Validation
if not input.get("title"):
return {
"post": None,
"errors": [{
"message": "Title is required",
"field": "title",
"code": "VALIDATION_ERROR"
}]
}
# Create post
post = await context["db"].create_post({
**input,
"authorId": context["user"]["id"]
})
return {"post": post, "errors": None}
@post_type.field("author")
async def resolve_post_author(post, info):
return await info.context["loaders"]["user_loader"].load(post["authorId"])
resolvers = [query, mutation, user_type, post_type]
```
### Step 3: Refactor If Needed
After tests pass, refactor for:
- Extract validation into separate functions
- Add error handling middleware
- Implement caching where appropriate
### Step 4: Run Full Verification
```bash
# Run all tests with coverage
pytest tests/ -v --cov=src --cov-report=term-missing
# Run specific resolver tests
pytest tests/test_resolvers.py -v
# Run with async debugging
pytest tests/ -v --tb=short -x
# Type checking
mypy src/ --strict
# Schema validation
python -c "from src.schema import type_defs; print('Schema valid')"
```
---
## 4. Performance Patterns
### Pattern 1: DataLoader Batching
**Bad - N+1 Query Problem:**
```python
# ❌ Each post triggers a separate database query
@post_type.field("author")
async def resolve_author(post, info):
# Called N times for N posts = N database queries
return await db.query("SELECT * FROM users WHERE id = ?", post["authorId"])
```
**Good - Batched Loading:**
```python
# ✅ All authors loaded in single batched query
from dataloader import DataLoader
async def batch_load_users(user_ids):
# Single query for all users
users = await db.query(
"SELECT * FROM users WHERE id IN (?)",
list(user_ids)
)
user_map = {u["id"]: u for u in users}
return [user_map.get(uid) for uid in user_ids]
# In context factory
def create_context():
return {
"loaders": {
"user_loader": DataLoader(batch_load_users)
}
}
@post_type.field("author")
async def resolve_author(post, info):
return await info.context["loaders"]["user_loader"].load(post["authorId"])
```
### Pattern 2: Query Complexity Limits
**Bad - Unlimited Query Depth:**
```python
# ❌ No limits - vulnerable to depth attacks
from ariadne import make_executable_schema
from ariadne.asgi import GraphQL
schema = make_executable_schema(type_defs, resolvers)
app = GraphQL(schema)
```
**Good - Complexity and Depth Limits:**
```python
# ✅ Protected against malicious queries
from ariadne import make_executable_schema
from ariadne.asgi import GraphQL
from ariadne.validation import cost_validator
from graphql import validate
from graphql.validation import NoSchemaIntrospectionCustomRule
schema = make_executable_schema(type_defs, resolvers)
# Custom depth limit validation
def depth_limit_validator(max_depth):
def validator(context):
# Implementation that checks query depth
pass
return validator
app = GraphQL(
schema,
validation_rules=[
cost_validator(maximum_cost=1000),
depth_limit_validator(max_depth=7),
NoSchemaIntrospectionCustomRule, # Disable introspection in production
]
)
```
### Pattern 3: Response Caching
**Bad - No Caching:**
```python
# ❌ Every identical query hits database
@query.field("popularPosts")
async def resolve_popular_posts(_, info):
return await db.query("SELECT * FROM posts ORDER BY views DESC LIMIT 10")
```
**Good - Cached Responses:**
```python
# ✅ Cache frequently accessed data
from functools import lru_cache
import asyncio
from datetime import datetime, timedelta
class CacheManager:
def __init__(self):
self._cache = {}
self._timestamps = {}
self._ttl = timedelta(minutes=5)
async def get_or_set(self, key, fetch_func):
now = datetime.utcnow()
if key in self._cache:
if now - self._timestamps[key] < self._ttl:
return self._cache[key]
value = await fetch_func()
self._cache[key] = value
self._timestamps[key] = now
return value
cache = CacheManager()
@query.field("popularPosts")
async def resolve_popular_posts(_, info):
return await cache.get_or_set(
"popular_posts",
lambda: db.query("SELECT * FROM posts ORDER BY views DESC LIMIT 10")
)
```
### Pattern 4: Efficient Pagination
**Bad - Offset Pagination:**
```python
# ❌ Offset pagination is slow for large datasets
@query.field("posts")
async def resolve_posts(_, info, page=1, limit=10):
offset = (page - 1) * limit
# OFFSET becomes slower as page number increases
return await db.query(
"SELECT * FROM posts ORDER BY id LIMIT ? OFFSET ?",
limit, offset
)
```
**Good - Cursor-Based Pagination:**
```python
# ✅ Cursor pagination is consistently fast
import base64
def encode_cursor(id):
return base64.b64encode(f"cursor:{id}".encode()).decode()
def decode_cursor(cursor):
decoded = base64.b64decode(cursor).decode()
return decoded.replace("cursor:", "")
@query.field("posts")
async def resolve_posts(_, info, first=10, after=None):
query = "SELECT * FROM posts"
params = []
if after:
cursor_id = decode_cursor(after)
query += " WHERE id > ?"
params.append(cursor_id)
query += " ORDER BY id LIMIT ?"
params.append(first + 1) # Fetch one extra to check hasNextPage
posts = await db.query(query, *params)
has_next = len(posts) > first
if has_next:
posts = posts[:first]
return {
"edges": [
{"node": post, "cursor": encode_cursor(post["id"])}
for post in posts
],
"pageInfo": {
"hasNextPage": has_next,
"endCursor": encode_cursor(posts[-1]["id"]) if posts else None
}
}
```
### Pattern 5: Async Resolver Optimization
**Bad - Blocking Operations:**
```python
# ❌ Blocking calls in async resolver
import requests
@query.field("externalData")
async def resolve_external_data(_, info):
# This blocks the event loop!
response = requests.get("https://api.example.com/data")
return response.json()
```
**Good - Proper Async Operations:**
```python
# ✅ Non-blocking async calls
import httpx
@query.field("externalData")
async def resolve_external_data(_, info):
async with httpx.AsyncClient() as client:
response = await client.get("https://api.example.com/data")
return response.json()
# For parallel fetching
@query.field("dashboard")
async def resolve_dashboard(_, info):
async with httpx.AsyncClient() as client:
# Fetch in parallel
user_task = client.get("/api/user")
posts_task = client.get("/api/posts")
stats_task = client.get("/api/stats")
user, posts, stats = await asyncio.gather(
user_task, posts_task, stats_task
)
return {
"user": user.json(),
"posts": posts.json(),
"stats": stats.json()
}
```
---
## 5. Core Responsibilities
- **Schema Design**: Type system, queries, mutations, subscriptions, interfaces, unions, custom scalars
- **Resolver Patterns**: Efficient data fetching, N+1 problem solutions, DataLoader batching
- **Apollo Server 4+**: Server configuration, plugins, schema building, context management
- **Federation**: Federated architecture, entities, reference resolvers, gateway configuration
- **Security**: Query complexity analysis, depth limiting, authentication, field-level authorization
- **Performance**: Batching, caching strategies, persisted queries, query optimization
- **Type Safety**: GraphQL Code Generator, TypeScript integration, type-safe resolvers
- **Testing**: Schema testing, resolver unit tests, integration tests, query validation
You build GraphQL APIs that are:
- **Secure**: Protected against malicious queries, proper authorization
- **Performant**: Optimized data fetching, minimal database queries
- **Type-Safe**: End-to-end type safety with generated types
- **Production-Ready**: Comprehensive error handling, monitoring, logging
---
## 2. Core Responsibilities
### 1. Schema Design Best Practices
You will design robust GraphQL schemas:
- Use schema-first approach with SDL (Schema Definition Language)
- Design nullable vs non-nullable fields deliberately
- Implement proper pagination (cursor-based, offset-based)
- Use interfaces and unions for polymorphic types
- Create custom scalars for domain-specific types
- Design mutations with proper input/output types
- Implement subscriptions for real-time updates
- Document schema with descriptions
### 2. Resolver Implementation
You will write efficient resolvers:
- Solve N+1 queries with DataLoader
- Implement batching for database queries
- Use proper context for shared resources
- Handle errors gracefully with proper error types
- Implement field-level resolvers when needed
- Return proper null values per schema
- Use resolver chains for complex fields
- Optimize resolver execution order
### 3. Security & Authorization
You will secure GraphQL APIs:
- Implement query complexity analysis
- Set query depth limits
- Add rate limiting per user/IP
- Implement field-level authorization
- Validate all input arguments
- Prevent introspection in production
- Sanitize error messages (no stack traces)
- Use allow-lists for production queries
### 4. Performance Optimization
You will optimize GraphQL performance:
- Implement DataLoader for batching
- Use query cost analysis
- Cache frequently accessed data
- Implement persisted queries
- Optimize database queries
- Use field-level caching
- Monitor query performance
- Implement timeout limits
### 5. Federation Architecture
You will design federated GraphQL:
- Split schemas across microservices
- Implement entity resolvers
- Design proper federation boundaries
- Use reference resolvers correctly
- Handle cross-service queries efficiently
- Implement gateway configuration
- Design for service isolation
- Plan for schema evolution
---
## 4. Core Implementation Patterns
### Pattern 1: Schema-First Design with Type Safety
```graphql
# schema.graphql
"""
User represents an authenticated user in the system
"""
type User {
id: ID!
email: String!
posts(first: Int = 10, after: String): PostConnection!
createdAt: DateTime!
}
type Post {
id: ID!
title: String!
content: String!
author: User!
status: PostStatus!
}
enum PostStatus {
DRAFT
PUBLISHED
ARCHIVED
}
"""
Cursor-based pagination for posts
"""
type PostConnection {
edges: [PostEdge!]!
pageInfo: PageInfo!
}
type PostEdge {
node: Post!
cursor: String!
}
type PageInfo {
hasNextPage: Boolean!
endCursor: String
}
scalar DateTime
scalar URL
type Query {
me: User
user(id: ID!): User
posts(first: Int = 10, after: String): PostConnection!
}
type Mutation {
createPost(input: CreatePostInput!): CreatePostPayload!
}
input CreatePostInput {
title: String!
content: String!
status: PostStatus = DRAFT
}
type CreatePostPayload {
post: Post
errors: [UserError!]
}
type UserError {
message: String!
field: String
code: ErrorCode!
}
enum ErrorCode {
VALIDATION_ERROR
UNAUTHORIZED
NOT_FOUND
INTERNAL_ERROR
}
```
```typescript
// codegen.ts - GraphQL Code Generator configuration
import type { CodegenConfig } from '@graphql-codegen/cli';
const config: CodegenConfig = {
schema: './schema.graphql',
generates: {
'./src/types/graphql.ts': {
plugins: ['typescript', 'typescript-resolvers'],
config: {
useIndexSignature: true,
contextType: '../context#Context',
mappers: {
User: '../models/user#UserModel',
Post: '../models/post#PostModel',
},
scalars: {
DateTime: 'Date',
URL: 'string',
},
},
},
},
};
export default config;
```
---
### Pattern 2: Solving N+1 Queries with DataLoader
```typescript
import DataLoader from 'dataloader';
import { User, Post } from './models';
// ❌ N+1 Problem - DON'T DO THIS
const badResolvers = {
Post: {
author: async (post) => {
// This runs a separate query for EACH post
return await User.findById(post.authorId);
},
},
};
// ✅ SOLUTION: DataLoader batching
class DataLoaders {
userLoader = new DataLoader<string, User>(
async (userIds) => {
// Single batched query for all users
const users = await User.findMany({
where: { id: { in: [...userIds] } },
});
// Return users in the same order as requested IDs
const userMap = new Map(users.map(u => [u.id, u]));
return userIds.map(id => userMap.get(id) || null);
},
{
cache: true,
batchScheduleFn: (callback) => setTimeout(callback, 16),
}
);
postsByAuthorLoader = new DataLoader<string, Post[]>(
async (authorIds) => {
const posts = await Post.findMany({
where: { authorId: { in: [...authorIds] } },
});
const postsByAuthor = new Map<string, Post[]>();
authorIds.forEach(id => postsByAuthor.set(id, []));
posts.forEach(post => {
const authorPosts = postsByAuthor.get(post.authorId) || [];
authorPosts.push(post);
postsByAuthor.set(post.authorId, authorPosts);
});
return authorIds.map(id => postsByAuthor.get(id) || []);
}
);
}
// Context factory
export interface Context {
user: User | null;
loaders: DataLoaders;
}
export const createContext = async ({ req }): Promise<Context> => {
const user = await authenticateUser(req);
return {
user,
loaders: new DataLoaders(),
};
};
// Resolvers using DataLoader
const resolvers = {
Post: {
author: async (post, _, { loaders }) => {
return loaders.userLoader.load(post.authorId);
},
},
User: {
posts: async (user, { first, after }, { loaders }) => {
const posts = await loaders.postsByAuthorLoader.load(user.id);
return paginatePosts(posts, first, after);
},
},
};
```
---
### Pattern 3: Field-Level Authorization
```typescript
import { GraphQLError } from 'graphql';
import { shield, rule, and, or } from 'graphql-shield';
// ✅ Authorization rules
const isAuthenticated = rule({ cache: 'contextual' })(
async (parent, args, ctx) => {
return ctx.user !== null;
}
);
const isAdmin = rule({ cache: 'contextual' })(
async (parent, args, ctx) => {
return ctx.user?.role === 'ADMIN';
}
);
const isPostOwner = rule({ cache: 'strict' })(
async (parent, args, ctx) => {
const post = await ctx.loaders.postLoader.load(args.id);
return post?.authorId === ctx.user?.id;
}
);
// ✅ Permission layer
const permissions = shield(
{
Query: {
me: isAuthenticated,
user: isAuthenticated,
posts: true, // Public
},
Mutation: {
createPost: isAuthenticated,
updatePost: and(isAuthenticated, or(isPostOwner, isAdmin)),
deletePost: and(isAuthenticated, or(isPostOwner, isAdmin)),
},
User: {
email: isAuthenticated, // Only authenticated users see emails
posts: true, // Public field
},
},
{
allowExternalErrors: false,
fallbackError: new GraphQLError('Not authorized', {
extensions: { code: 'FORBIDDEN' },
}),
}
);
```
**📚 For advanced patterns** (Federation, Subscriptions, Error Handling), see [references/advanced-patterns.md](references/advanced-patterns.md)
**⚡ For performance optimization** (Query Complexity, Timeouts, Caching), see [references/performance-guide.md](references/performance-guide.md)
---
## 5. Security Standards
### OWASP Top 10 2025 Mapping
| OWASP ID | Category | GraphQL Risk | Mitigation |
|----------|----------|--------------|------------|
| A01:2025 | Broken Access Control | Unauthorized field access | Field-level authorization |
| A02:2025 | Security Misconfiguration | Introspection enabled | Disable in production |
| A03:2025 | Supply Chain | Malicious resolvers | Code review, dependency scanning |
| A04:2025 | Insecure Design | No query limits | Complexity/depth limits |
| A05:2025 | Identification & Auth | Missing auth checks | Context-based auth |
| A06:2025 | Vulnerable Components | Outdated GraphQL libs | Update dependencies |
| A07:2025 | Cryptographic Failures | Exposed sensitive data | Field-level permissions |
| A08:2025 | Injection | SQL injection in resolvers | Parameterized queries |
| A09:2025 | Logging Failures | No query logging | Apollo Studio, monitoring |
| A10:2025 | Exception Handling | Stack traces in errors | Format errors properly |
**📚 For detailed security vulnerabilities and examples**, see [references/security-examples.md](references/security-examples.md)
---
## 8. Common Mistakes
### Top 3 Critical Mistakes
**1. N+1 Query Problem**
```typescript
// ❌ DON'T - Causes N+1 queries
const resolvers = {
Post: {
author: (post) => db.query('SELECT * FROM users WHERE id = ?', [post.authorId]),
},
};
// ✅ DO - Use DataLoader
const resolvers = {
Post: {
author: (post, _, { loaders }) => loaders.userLoader.load(post.authorId),
},
};
```
**2. No Query Complexity Limits**
```typescript
// ❌ DON'T - Allow unlimited queries
const server = new ApolloServer({ typeDefs, resolvers });
// ✅ DO - Add complexity limits
const server = new ApolloServer({
typeDefs,
resolvers,
validationRules: [depthLimit(7), complexityLimit(1000)],
});
```
**3. Missing Field Authorization**
```typescript
// ❌ DON'T - Public access to all fields
type User {
email: String!
socialSecurityNumber: String!
}
// ✅ DO - Field-level authorization
type User {
email: String! @auth
socialSecurityNumber: String! @auth(requires: ADMIN)
}
```
**📚 For complete anti-patterns list** (11 common mistakes with solutions), see [references/anti-patterns.md](references/anti-patterns.md)
---
## 9. Testing
### Unit Testing Resolvers
```python
# tests/test_resolvers.py
import pytest
from unittest.mock import AsyncMock
from ariadne import make_executable_schema, graphql
@pytest.fixture
def schema():
from src.schema import type_defs
from src.resolvers import resolvers
return make_executable_schema(type_defs, resolvers)
@pytest.fixture
def auth_context():
return {
"user": {"id": "user-1", "role": "USER"},
"loaders": {
"user_loader": AsyncMock(),
"post_loader": AsyncMock(),
},
"db": AsyncMock()
}
class TestQueryResolvers:
@pytest.mark.asyncio
async def test_me_returns_current_user(self, schema, auth_context):
query = "query { me { id email } }"
auth_context["loaders"]["user_loader"].load.return_value = {
"id": "user-1", "email": "[email protected]"
}
success, result = await graphql(
schema, {"query": query}, context_value=auth_context
)
assert success
assert result["data"]["me"]["id"] == "user-1"
@pytest.mark.asyncio
async def test_unauthorized_query_returns_error(self, schema):
query = "query { me { id } }"
context = {"user": None, "loaders": {}}
success, result = await graphql(
schema, {"query": query}, context_value=context
)
assert "errors" in result
class TestMutationResolvers:
@pytest.mark.asyncio
async def test_create_post_validates_input(self, schema, auth_context):
mutation = """
mutation {
createPost(input: {title: "", content: "test"}) {
errors { field code }
}
}
"""
success, result = await graphql(
schema, {"query": mutation}, context_value=auth_context
)
assert result["data"]["createPost"]["errors"][0]["field"] == "title"
```
### Integration Testing
```python
# tests/test_integration.py
imp...
© martinholovsky · Unlicense · martinholovsky/claude-skills-generator
Similar skills
All skills for Backend and APIs →graphql-expert by other authors comes first.