graphql-expert · martinholovsky — скилл для Claude Code: GraphQL и установка
Скилл graphql-expert для Claude Code помогает проектировать GraphQL-схемы, писать резолверы и настраивать федерацию. Он включается при разработке API, работе с Apollo Server и оптимизации запросов.
Unlicense 220 установок ★ 48 обновлён 2025-12-06
npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a claude-codeЧто делает graphql-expert
graphql-expert задаёт процесс разработки GraphQL API: сначала проектировать схему и писать тесты, затем реализовывать резолверы. Для типобезопасности он предлагает GraphQL Code Generator, а для пакетной загрузки данных — DataLoader. Также описаны ограничения сложности запросов, проверка прав на поля и валидация входных данных.
Перед написанием кода скилл предписывает сверять конфигурацию с документацией Apollo Server, проверять директивы по спецификации GraphQL и искать существующие решения в проекте. Для проверки предлагаются инструменты чтения кода и поиска по документации. Ошибки схемы могут нарушить работу всего API.
Какие задачи решает
- спроектировать типы GraphQL до написания резолверов
- покрыть резолверы и интеграции тестами
- снизить риск N+1 запросов с DataLoader
- ограничить сложность запросов и доступ к полям
- проверить директивы и настройки Apollo Server по документации
Примеры запросов агенту
- Спроектируй GraphQL-схему для этого API и сначала напиши тесты для резолверов.
- Проверь резолверы на N+1 запросы и предложи вариант с DataLoader.
- Настрой федерацию GraphQL и сверь директивы с документацией Apollo.
Как установить graphql-expert
1Через Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a claude-code2Вручную: положить файлы
~/.claude/skills/graphql-expert/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/graphql-expert/
1Через Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a codex2Вручную: положить файлы
.agents/skills/graphql-expert/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a cursor2Вручную: положить файлы
.cursor/skills/graphql-expert/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install martinholovsky/claude-skills-generator skills/graphql-expert2Вручную: положить файлы
.github/skills/graphql-expert/SKILL.md1Через Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a gemini-cli2Командой платформы
gemini skills install https://github.com/martinholovsky/claude-skills-generator --path skills/graphql-expertВручную: положить файлы
.devin/skills/graphql-expert/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о graphql-expert
Как установить graphql-expert в Claude Code?
Выполни npx skills add martinholovsky/claude-skills-generator --skill graphql-expert -a claude-code. Файл скилла находится по пути ~/.claude/skills/graphql-expert/SKILL.md.
Что делает graphql-expert?
Помогает создавать GraphQL API: проектировать схемы, писать тесты для резолверов, настраивать типобезопасность и работать с производительностью и безопасностью запросов.
Как graphql-expert проверяет решения для Apollo Server и GraphQL?
Скилл требует сверять настройки Apollo Server с официальной документацией, а директивы — со спецификацией GraphQL. При сомнениях агенту предлагается сначала проверить API, а затем писать код.
Исходный текст
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
Похожие скиллы
Все скиллы по теме «Бэкенд и API» →Сначала — graphql-expert от других авторов.