Build GraphQL APIs with schema design, resolvers, and subscriptions. Use when: creating GraphQL server, API with complex queries. Triggers: "graphql", "gql", "apollo", "async-graphql", "strawberry".
apm install @majiayu000/graphql-api---
name: graphql-api
description: |
Build GraphQL APIs with schema design, resolvers, and subscriptions.
Use when: creating GraphQL server, API with complex queries.
Triggers: "graphql", "gql", "apollo", "async-graphql", "strawberry".
---
# GraphQL API Development
## Project Protection Setup
**MANDATORY before writing any code:**
```bash
# 1. Create .gitignore
cat >> .gitignore << 'EOF'
# Build
target/
node_modules/
__pycache__/
dist/
# Secrets
.env
.env.*
!.env.example
*.key
# IDE
.idea/
.vscode/
.DS_Store
EOF
# 2. Setup pre-commit hooks
cat > .pre-commit-config.yaml << 'EOF'
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v5.0.0
hooks:
- id: detect-private-key
- id: check-added-large-files
- repo: https://github.com/gitleaks/gitleaks
rev: v8.21.2
hooks:
- id: gitleaks
EOF
pre-commit install
```
---
## Stack Options
| Language | Framework | Best For |
|----------|-----------|----------|
| **Rust** | async-graphql + axum | Performance, type safety |
| **Python** | strawberry / ariadne | Rapid development |
| **Node** | Apollo Server / Mercurius | JS ecosystem |
---
## Quick Start
### Rust (async-graphql + axum)
```toml
# Cargo.toml
[dependencies]
async-graphql = "7"
async-graphql-axum = "7"
axum = "0.7"
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
```
```rust
use async_graphql::{Object, Schema, EmptyMutation, EmptySubscription};
use async_graphql_axum::GraphQL;
use axum::{Router, routing::get};
struct Query;
#[Object]
impl Query {
async fn hello(&self, name: Option<String>) -> String {
format!("Hello, {}!", name.unwrap_or("World".to_string()))
}
}
type AppSchema = Schema<Query, EmptyMutation, EmptySubscription>;
#[tokio::main]
async fn main() {
let schema = Schema::build(Query, EmptyMutation, EmptySubscription).finish();
let app = Router::new()
.route("/", get(graphiql).post_service(GraphQL::new(schema)));
let listener = tokio::net::TcpListener::bind("0.0.0.0:8000").await.unwrap();
axum::serve(listener, app).await.unwrap();
}
async fn graphiql() -> impl axum::response::IntoResponse {
axum::response::Html(async_graphql::http::GraphiQLSource::build().endpoint("/").finish())
}
```
### Python (strawberry)
```python
# requirements.txt
strawberry-graphql[fastapi]
uvicorn
```
```python
import strawberry
from fastapi import FastAPI
from strawberry.fastapi import GraphQLRouter
@strawberry.type
class Query:
@strawberry.field
def hello(self, name: str = "World") -> str:
return f"Hello, {name}!"
schema = strawberry.Schema(query=Query)
graphql_app = GraphQLRouter(schema)
app = FastAPI()
app.include_router(graphql_app, prefix="/graphql")
```
### Node (Apollo Server)
```typescript
// package.json: "@apollo/server": "^4", "graphql": "^16"
import { ApolloServer } from '@apollo/server';
import { startStandaloneServer } from '@apollo/server/standalone';
const typeDefs = `#graphql
type Query {
hello(name: String): String!
}
`;
const resolvers = {
Query: {
hello: (_: unknown, { name }: { name?: string }) =>
`Hello, ${name ?? 'World'}!`,
},
};
const server = new ApolloServer({ typeDefs, resolvers });
const { url } = await startStandaloneServer(server, { listen: { port: 4000 } });
console.log(`Server ready at ${url}`);
```
---
## Schema Design
### Types & Fields
```rust
use async_graphql::{Object, SimpleObject, InputObject, ID};
#[derive(SimpleObject)]
struct User {
id: ID,
name: String,
email: String,
posts: Vec<Post>,
}
#[derive(SimpleObject)]
struct Post {
id: ID,
title: String,
content: String,
author_id: ID,
}
#[derive(InputObject)]
struct CreateUserInput {
name: String,
email: String,
}
```
### Python
```python
import strawberry
from typing import List
@strawberry.type
class User:
id: strawberry.ID
name: str
email: str
posts: List["Post"]
@strawberry.type
class Post:
id: strawberry.ID
title: str
content: str
@strawberry.input
class CreateUserInput:
name: str
email: str
```
---
## Queries & Mutations
### Rust
```rust
struct Query;
#[Object]
impl Query {
async fn user(&self, ctx: &Context<'_>, id: ID) -> Result<Option<User>> {
let db = ctx.data::<Database>()?;
db.get_user(id.parse()?).await
}
async fn users(&self, ctx: &Context<'_>, limit: Option<i32>) -> Result<Vec<User>> {
let db = ctx.data::<Database>()?;
db.list_users(limit.unwrap_or(10)).await
}
}
struct Mutation;
#[Object]
impl Mutation {
async fn create_user(&self, ctx: &Context<'_>, input: CreateUserInput) -> Result<User> {
let db = ctx.data::<Database>()?;
db.create_user(input).await
}
async fn delete_user(&self, ctx: &Context<'_>, id: ID) -> Result<bool> {
let db = ctx.data::<Database>()?;
db.delete_user(id.parse()?).await
}
}
```
### Python
```python
@strawberry.type
class Query:
@strawberry.field
async def user(self, info: Info, id: strawberry.ID) -> User | None:
db = info.context["db"]
return await db.get_user(id)
@strawberry.field
async def users(self, info: Info, limit: int = 10) -> list[User]:
db = info.context["db"]
return await db.list_users(limit)
@strawberry.type
class Mutation:
@strawberry.mutation
async def create_user(self, info: Info, input: CreateUserInput) -> User:
db = info.context["db"]
return await db.create_user(input)
```
---
## DataLoader (N+1 Problem)
### Rust
```rust
use async_graphql::dataloader::{DataLoader, Loader};
struct UserLoader(Database);
impl Loader<i32> for UserLoader {
type Value = User;
type Error = Error;
async fn load(&self, keys: &[i32]) -> Result<HashMap<i32, User>> {
self.0.get_users_by_ids(keys).await
}
}
// In schema setup
let schema = Schema::build(Query, Mutation, EmptySubscription)
.data(DataLoader::new(UserLoader(db.clone()), tokio::spawn))
.finish();
// In resolver
#[Object]
impl Post {
async fn author(&self, ctx: &Context<'_>) -> Result<User> {
let loader = ctx.data::<DataLoader<UserLoader>>()?;
loader.load_one(self.author_id).await?.ok_or("Not found".into())
}
}
```
### Python
```python
from strawberry.dataloader import DataLoader
async def load_users(keys: list[int]) -> list[User]:
users = await db.get_users_by_ids(keys)
return [users.get(key) for key in keys]
user_loader = DataLoader(load_fn=load_users)
@strawberry.type
class Post:
author_id: int
@strawberry.field
async def author(self, info: Info) -> User:
loader = info.context["user_loader"]
return await loader.load(self.author_id)
```
---
## Subscriptions (Real-time)
### Rust
```rust
use async_graphql::{Subscription, futures_util::Stream};
use tokio_stream::StreamExt;
struct Subscription;
#[Subscription]
impl Subscription {
async fn messages(&self, ctx: &Context<'_>) -> impl Stream<Item = Message> {
let mut rx = ctx.data::<broadcast::Sender<Message>>()?.subscribe();
async_stream::stream! {
while let Ok(msg) = rx.recv().await {
yield msg;
}
}
}
}
```
### WebSocket Setup
```rust
use async_graphql_axum::GraphQLSubscription;
let app = Router::new()
.route("/", get(graphiql).post_service(GraphQL::new(schema.clone())))
.route_service("/ws", GraphQLSubscription::new(schema));
```
---
## Authentication & Context
### Rust
```rust
use axum::{extract::State, http::HeaderMap};
async fn graphql_handler(
State(schema): State<AppSchema>,
headers: HeaderMap,
req: GraphQLRequest,
) -> GraphQLResponse {
let token = headers
.get("Authorization")
.and_then(|v| v.to_str().ok())
.map(|s| s.replace("Bearer ", ""));
let user = if let Some(token) = token {
verify_token(&token).ok()
} else {
None
};
schema.execute(req.into_inner().data(user)).await.into()
}
// In resolver
#[Object]
impl Mutation {
#[graphql(guard = "AuthGuard")]
async fn create_post(&self, ctx: &Context<'_>, input: CreatePostInput) -> Result<Post> {
let user = ctx.data::<Option<User>>()?
.as_ref()
.ok_or("Unauthorized")?;
// ...
}
}
```
---
## Error Handling
### Rust
```rust
use async_graphql::{Error, ErrorExtensions};
#[derive(Debug, thiserror::Error)]
enum ApiError {
#[error("Not found")]
NotFound,
#[error("Unauthorized")]
Unauthorized,
#[error("Validation failed: {0}")]
Validation(String),
}
impl ErrorExtensions for ApiError {
fn extend(&self) -> Error {
Error::new(self.to_string()).extend_with(|_, e| {
match self {
ApiError::NotFound => e.set("code", "NOT_FOUND"),
ApiError::Unauthorized => e.set("code", "UNAUTHORIZED"),
ApiError::Validation(_) => e.set("code", "VALIDATION_ERROR"),
}
})
}
}
```
---
## Testing
### Rust
```rust
#[tokio::test]
async fn test_hello_query() {
let schema = Schema::build(Query, EmptyMutation, EmptySubscription).finish();
let result = schema.execute("{ hello(name: \"Test\") }").await;
assert_eq!(
result.data,
async_graphql::Value::from_json(serde_json::json!({
"hello": "Hello, Test!"
})).unwrap()
);
}
```
---
## Common Pitfalls
| Pitfall | Solution |
|---------|----------|
| N+1 queries | Use DataLoader |
| Over-fetching | Design granular types |
| No rate limiting | Implement query complexity |
| Deep nesting | Set max depth limit |
| No caching | Use persisted queries |
---
## Query Complexity Limits
```rust
let schema = Schema::build(Query, Mutation, Subscription)
.limit_complexity(100) // Max query complexity
.limit_depth(10) // Max nesting depth
.finish();
```
---
## Testing
### Rust (async-graphql)
```rust
#[cfg(test)]
mod tests {
use super::*;
#[tokio::test]
async fn test_hello_query() {
let schema = Schema::build(Query, EmptyMutation, EmptySubscription).finish();
let result = schema
.execute(r#"{ hello(name: "Test") }"#)
.await;
assert!(result.errors.is_empty());
assert_eq!(
result.data,
async_graphql::Value::from_json(serde_json::json!({
"hello": "Hello, Test!"
})).unwrap()
);
}
#[tokio::test]
async fn test_create_user_mutation() {
let schema = create_test_schema().await;
let result = schema.execute(r#"
mutation {
createUser(input: { name: "Test", email: "test@example.com" }) {
id
name
}
}
"#).await;
assert!(result.errors.is_empty());
}
#[tokio::test]
async fn test_unauthorized_mutation_fails() {
let schema = create_schema_without_auth().await;
let result = schema.execute(r#"
mutation { deleteUser(id: "1") }
"#).await;
assert!(!result.errors.is_empty());
assert!(result.errors[0].message.contains("Unauthorized"));
}
}
```
### Python (strawberry)
```python
import pytest
from strawberry.test import GraphQLTestClient
@pytest.fixture
def client(app):
return GraphQLTestClient(app)
def test_hello_query(client):
response = client.query('{ hello(name: "Test") }')
assert response.data == {"hello": "Hello, Test!"}
def test_create_user(client):
response = client.query('''
mutation {
createUser(input: { name: "Test", email: "test@example.com" }) {
id
name
}
}
''')
assert response.errors is None
assert response.data["createUser"]["name"] == "Test"
```
### Node (Apollo)
```typescript
import { ApolloServer } from '@apollo/server';
import { describe, it, expect } from 'vitest';
describe('GraphQL API', () => {
it('hello query', async () => {
const server = new ApolloServer({ typeDefs, resolvers });
const response = await server.executeOperation({
query: '{ hello(name: "Test") }',
});
expect(response.body.singleResult.data).toEqual({ hello: 'Hello, Test!' });
});
});
```
---
## TDD Workflow
```
1. Task[tdd-test-writer]: "Create users query"
→ Writes test with expected response
→ cargo test → FAILS (RED)
2. Task[rust-developer]: "Implement users resolver"
→ Implements with DataLoader
→ cargo test → PASSES (GREEN)
3. Repeat for each query/mutation
4. Task[code-reviewer]: "Review GraphQL implementation"
→ Checks N+1, auth, complexity limits
```
---
## Security Checklist
- [ ] Query complexity limits set
- [ ] Query depth limits set
- [ ] Authentication on mutations
- [ ] Authorization per field (if needed)
- [ ] No sensitive data in error messages
- [ ] Rate limiting enabled
- [ ] Introspection disabled in production
- [ ] Input validation on all arguments
---
## Project Structure
```
graphql-api/
├── src/
│ ├── main.rs
│ ├── schema/
│ │ ├── mod.rs
│ │ ├── query.rs
│ │ ├── mutation.rs
│ │ └── subscription.rs
│ ├── models/
│ │ ├── mod.rs
│ │ └── user.rs
│ ├── loaders/ # DataLoaders
│ └── auth.rs
├── tests/
│ └── schema_tests.rs
├── Cargo.toml
├── .env.example
└── schema.graphql # SDL (optional)
```