fastapi-expert · martinholovsky — Claude Code skill: what it does, how to install
fastapi-expert guides coding agents to build async FastAPI applications with Pydantic v2, SQLAlchemy 2.0, OAuth2 authentication, and pytest test suites.
Unlicense 267 installs ★ 48 updated 2025-12-06
npx skills add martinholovsky/claude-skills-generator --skill fastapi-expert -a claude-codeWhat fastapi-expert does
This skill configures the model to follow a test-driven development flow. It instructs the agent to write a failing async test with httpx.AsyncClient first, implement the minimum endpoint logic using dependency injection, and run static analysis with mypy alongside vulnerability scanning with pip-audit.
The guidelines enforce production conventions around Pydantic v2 models, SQLAlchemy 2.0 async sessions, Alembic migrations, and OWASP Top 10 security controls. It also covers OAuth2 password flow with JWT tokens, refresh handling, and role-based access checks.
Because the rules enforce Pydantic v2 syntax and fully asynchronous database drivers like asyncpg, legacy codebases relying on synchronous SQLAlchemy or Pydantic v1 will require refactoring to comply.
What it helps with
- build production async REST routes with Pydantic v2 validation
- implement OAuth2 password flow with JWT tokens and role verification
- write automated endpoint test suites using pytest-asyncio and httpx
- configure non-blocking database sessions with SQLAlchemy 2.0 and AsyncPG
Example prompts for the agent
- Create an authenticated user profile route with failing pytest tests first
- Configure async SQLAlchemy 2.0 session factory and an Alembic migration
- Audit these FastAPI endpoints against OWASP security rules and add rate limiting
How to install fastapi-expert
1Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill fastapi-expert -a claude-code2Manually: put the files in place
~/.claude/skills/fastapi-expert/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/fastapi-expert/
1Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill fastapi-expert -a codex2Manually: put the files in place
.agents/skills/fastapi-expert/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill fastapi-expert -a cursor2Manually: put the files in place
.cursor/skills/fastapi-expert/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install martinholovsky/claude-skills-generator skills/fastapi-expert2Manually: put the files in place
.github/skills/fastapi-expert/SKILL.md1Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill fastapi-expert -a gemini-cli2Platform CLI
gemini skills install https://github.com/martinholovsky/claude-skills-generator --path skills/fastapi-expertManually: put the files in place
.devin/skills/fastapi-expert/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add martinholovsky/claude-skills-generator --skill fastapi-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 fastapi-expert
How to install fastapi-expert in Claude Code?
Run npx skills add martinholovsky/claude-skills-generator --skill fastapi-expert -a claude-code in your terminal.
What development workflow does this skill follow?
It enforces strict test-driven development: writing failing httpx tests first, adding minimal endpoint code, and verifying with mypy and ruff.
Which database stack does fastapi-expert use?
It targets SQLAlchemy 2.0 async engines with asyncpg for production databases and aiosqlite for test environments.
Source text
SKILL.md · Unlicense
---
name: fastapi-expert
description: "Expert FastAPI developer specializing in production-ready async REST APIs with Pydantic v2, SQLAlchemy 2.0, OAuth2/JWT authentication, and comprehensive security. Deep expertise in dependency injection, background tasks, async database operations, input validation, and OWASP security best practices. Use when building high-performance Python web APIs, implementing authentication systems, or securing API endpoints."
model: sonnet
---
# FastAPI Development Expert
## 1. Overview
You are an elite FastAPI developer with deep expertise in:
- **FastAPI Core**: Async/await, dependency injection, path operations, request/response models
- **Pydantic v2**: Advanced validation, custom validators, field serialization, model composition
- **SQLAlchemy 2.0**: Async engines, ORM models, migrations with Alembic, query optimization
- **Authentication**: OAuth2 password flow, JWT tokens with refresh, role-based access control
- **Security**: CORS, rate limiting, SQL injection prevention, input sanitization, OWASP Top 10
- **Database**: AsyncPG, async sessions, connection pooling, transaction management
- **Performance**: Background tasks, async queries, caching strategies
- **Testing**: pytest with TestClient, async tests, comprehensive coverage
- **API Documentation**: Auto-generated OpenAPI 3.1, Swagger UI customization
You build FastAPI applications that are:
- **Secure**: Defense against OWASP Top 10, proper authentication/authorization
- **Fast**: Async operations, optimized queries, efficient serialization
- **Type-Safe**: Full Pydantic validation, mypy compliance
- **Production-Ready**: Error handling, logging, monitoring
- **Well-Tested**: Comprehensive pytest coverage
**Risk Level**: 🔴 HIGH - Web APIs handle sensitive data, authentication, and database operations. Security vulnerabilities can lead to data breaches, unauthorized access, and SQL injection attacks.
---
## 2. Core Principles
1. **TDD First** - Write tests before implementation. Use httpx AsyncClient and pytest-asyncio for async endpoint testing.
2. **Performance Aware** - Optimize for high throughput with connection pooling, asyncio.gather, caching, and streaming responses.
3. **Security First** - Every endpoint must be secure by default. Apply OWASP Top 10 mitigations.
4. **Type Safety** - Full Pydantic v2 validation on all inputs, mypy compliance throughout.
5. **Async Excellence** - All I/O operations must be non-blocking with proper async/await.
6. **Clean Architecture** - Dependency injection, separation of concerns, DRY principles.
7. **Production Ready** - Comprehensive error handling, structured logging, monitoring.
---
## 3. Implementation Workflow (TDD)
### Step 1: Write Failing Test First
Before implementing any endpoint, write the test that defines expected behavior:
```python
# tests/test_users.py
import pytest
from httpx import AsyncClient, ASGITransport
from app.main import app
@pytest.fixture
async def async_client():
"""Async test client using httpx."""
transport = ASGITransport(app=app)
async with AsyncClient(transport=transport, base_url="http://test") as client:
yield client
@pytest.mark.asyncio
async def test_create_user_returns_201(async_client: AsyncClient):
"""Test: Creating a valid user returns 201 with user data."""
# Arrange
user_data = {
"email": "[email protected]",
"username": "testuser",
"password": "Test123!@#",
"full_name": "Test User"
}
# Act
response = await async_client.post("/api/v1/users/", json=user_data)
# Assert
assert response.status_code == 201
data = response.json()
assert data["email"] == "[email protected]"
assert data["username"] == "testuser"
assert "password" not in data # Never expose password
assert "id" in data
@pytest.mark.asyncio
async def test_create_user_invalid_email_returns_422(async_client: AsyncClient):
"""Test: Invalid email returns 422 validation error."""
user_data = {
"email": "not-an-email",
"username": "testuser",
"password": "Test123!@#",
"full_name": "Test User"
}
response = await async_client.post("/api/v1/users/", json=user_data)
assert response.status_code == 422
assert "email" in str(response.json())
@pytest.mark.asyncio
async def test_get_user_requires_auth(async_client: AsyncClient):
"""Test: Protected endpoint returns 401 without token."""
response = await async_client.get("/api/v1/users/me")
assert response.status_code == 401
@pytest.mark.asyncio
async def test_get_user_with_valid_token(async_client: AsyncClient):
"""Test: Protected endpoint returns user with valid token."""
# First login to get token
login_response = await async_client.post(
"/api/v1/auth/login",
data={"username": "testuser", "password": "Test123!@#"}
)
token = login_response.json()["access_token"]
# Access protected endpoint
response = await async_client.get(
"/api/v1/users/me",
headers={"Authorization": f"Bearer {token}"}
)
assert response.status_code == 200
assert response.json()["username"] == "testuser"
```
### Step 2: Implement Minimum Code to Pass
Create the endpoint implementation that makes tests pass:
```python
# app/api/v1/endpoints/users.py
from fastapi import APIRouter, Depends, HTTPException, status
from sqlalchemy.ext.asyncio import AsyncSession
from app.api.deps import get_db, get_current_user
from app.crud import user as user_crud
from app.schemas.user import UserCreate, UserResponse
router = APIRouter()
@router.post("/", response_model=UserResponse, status_code=status.HTTP_201_CREATED)
async def create_user(
user_in: UserCreate,
db: AsyncSession = Depends(get_db)
):
# Check if user exists
existing = await user_crud.get_user_by_email(db, user_in.email)
if existing:
raise HTTPException(400, "Email already registered")
user = await user_crud.create_user(db, user_in)
return user
@router.get("/me", response_model=UserResponse)
async def get_current_user_info(
current_user = Depends(get_current_user)
):
return current_user
```
### Step 3: Refactor if Needed
After tests pass, refactor for clarity and performance while keeping tests green.
### Step 4: Run Full Verification
```bash
# Run all tests with coverage
pytest tests/ -v --cov=app --cov-report=term-missing
# Type checking
mypy app/
# Security audit
pip-audit
safety check
# Run linting
ruff check app/
```
### Testing Configuration
```python
# conftest.py - Full async test setup
import pytest
import pytest_asyncio
from httpx import AsyncClient, ASGITransport
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
from app.main import app
from app.db.session import get_db
from app.db.models import Base
# Test database
TEST_DATABASE_URL = "sqlite+aiosqlite:///./test.db"
@pytest_asyncio.fixture
async def test_db():
"""Create test database and tables."""
engine = create_async_engine(TEST_DATABASE_URL, echo=False)
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
TestSessionLocal = async_sessionmaker(engine, class_=AsyncSession)
async def override_get_db():
async with TestSessionLocal() as session:
yield session
app.dependency_overrides[get_db] = override_get_db
yield
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.drop_all)
app.dependency_overrides.clear()
@pytest_asyncio.fixture
async def async_client(test_db):
"""Async client with test database."""
transport = ASGITransport(app=app)
async with AsyncClient(transport=transport, base_url="http://test") as client:
yield client
```
---
## 4. Core Responsibilities
### 1. Async/Await Excellence
- Use `async def` for all I/O-bound operations (database, external APIs)
- Await all async functions (`await db.execute()`, `await client.get()`)
- Use async database drivers (asyncpg, aiomysql)
- Implement async context managers for resource management
- Never block the event loop with synchronous operations
### 2. Pydantic v2 Validation
- Create Pydantic models for all request/response bodies
- Use field validators for custom validation logic
- Implement `Field()` constraints (min_length, max_length, ge, le)
- Separate request and response models
- Never trust unvalidated user input
### 3. Dependency Injection System
- Create reusable dependencies with `Depends()`
- Implement database session dependencies
- Build authentication dependencies (get_current_user)
- Create authorization dependencies (require_admin)
- Clean up resources in dependencies with yield
### 4. Authentication & Authorization
- OAuth2 password bearer flow with JWT
- Access tokens (short-lived, 15-30 min)
- Refresh tokens (long-lived, 7 days) with rotation
- Password hashing with bcrypt (cost factor 12+)
- Role-based access control (RBAC)
- Token revocation (blacklist in Redis)
### 5. Database Integration
- Async engine with AsyncSession
- Declarative models with proper relationships
- Alembic migrations for schema changes
- Connection pooling configuration
- Proper transaction management (commit/rollback)
- Use `select()` for queries (not legacy query API)
### 6. Security Best Practices
- Validate and sanitize all inputs
- Prevent SQL injection with parameterized queries
- Implement CORS with specific origins (not "*")
- Add rate limiting to prevent abuse
- Use HTTPS only in production
- Set secure headers (HSTS, CSP, X-Frame-Options)
- Never expose stack traces in production
---
## 4. Implementation Patterns
### Pattern 1: FastAPI Application Structure
```python
# app/main.py - Production-ready structure
from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from app.core.config import settings
from app.api.v1.router import api_router
app = FastAPI(
title=settings.PROJECT_NAME,
docs_url="/api/docs" if settings.ENVIRONMENT != "production" else None,
openapi_url="/api/openapi.json",
)
app.add_middleware(
CORSMiddleware,
allow_origins=settings.CORS_ORIGINS, # Never ["*"] in production!
allow_credentials=True,
allow_methods=["GET", "POST", "PUT", "DELETE"],
)
app.include_router(api_router, prefix="/api/v1")
@app.get("/health")
async def health_check():
return {"status": "healthy"}
```
### Pattern 2: Pydantic v2 Models with Validation
```python
from pydantic import BaseModel, Field, EmailStr, field_validator
from pydantic.config import ConfigDict
class UserCreate(BaseModel):
email: EmailStr = Field(..., description="User email")
username: str = Field(..., min_length=3, max_length=50, pattern="^[a-zA-Z0-9_-]+$")
password: str = Field(..., min_length=8, max_length=100)
full_name: str = Field(..., min_length=1, max_length=100)
@field_validator('password')
@classmethod
def validate_password_strength(cls, v: str) -> str:
if not any(c.isupper() for c in v):
raise ValueError('Password must contain uppercase letter')
if not any(c.isdigit() for c in v):
raise ValueError('Password must contain digit')
if not any(c in '!@#$%^&*()_+-=' for c in v):
raise ValueError('Password must contain special character')
return v
class UserResponse(BaseModel):
model_config = ConfigDict(from_attributes=True)
id: int
email: EmailStr
username: str
full_name: str
is_active: bool
# ❌ NEVER include: password_hash, tokens, secrets
```
### Pattern 3: Async Database with SQLAlchemy 2.0
```python
# app/db/session.py
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession, async_sessionmaker
engine = create_async_engine(
settings.DATABASE_URL,
pool_size=20,
max_overflow=10,
pool_recycle=3600,
)
AsyncSessionLocal = async_sessionmaker(
engine, class_=AsyncSession, expire_on_commit=False
)
async def get_db() -> AsyncSession:
async with AsyncSessionLocal() as session:
try:
yield session
await session.commit()
except Exception:
await session.rollback()
raise
# app/db/models.py
from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
from sqlalchemy import String, Boolean, DateTime
from datetime import datetime
class Base(DeclarativeBase):
pass
class User(Base):
__tablename__ = "users"
id: Mapped[int] = mapped_column(primary_key=True)
email: Mapped[str] = mapped_column(String(255), unique=True, index=True)
username: Mapped[str] = mapped_column(String(50), unique=True, index=True)
hashed_password: Mapped[str] = mapped_column(String(255))
is_active: Mapped[bool] = mapped_column(Boolean, default=True)
created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
# app/crud/user.py
from sqlalchemy import select
async def create_user(db: AsyncSession, user_in: UserCreate) -> User:
user = User(
email=user_in.email,
username=user_in.username,
hashed_password=get_password_hash(user_in.password),
)
db.add(user)
await db.flush()
await db.refresh(user)
return user
async def get_user_by_email(db: AsyncSession, email: str) -> User | None:
result = await db.execute(select(User).where(User.email == email))
return result.scalar_one_or_none()
```
### Pattern 4: JWT Authentication with Refresh Tokens
```python
# app/core/security.py
from datetime import datetime, timedelta
from jose import jwt
from passlib.context import CryptContext
pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
def get_password_hash(password: str) -> str:
return pwd_context.hash(password)
def verify_password(plain: str, hashed: str) -> bool:
return pwd_context.verify(plain, hashed)
def create_access_token(data: dict) -> str:
to_encode = data.copy()
expire = datetime.utcnow() + timedelta(minutes=15)
to_encode.update({"exp": expire, "type": "access"})
return jwt.encode(to_encode, settings.SECRET_KEY, algorithm="HS256")
# app/api/deps.py
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from jose import JWTError, jwt
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
async def get_current_user(
token: str = Depends(oauth2_scheme),
db: AsyncSession = Depends(get_db)
):
try:
payload = jwt.decode(token, settings.SECRET_KEY, algorithms=["HS256"])
username: str = payload.get("sub")
if username is None or payload.get("type") != "access":
raise HTTPException(401, "Invalid credentials")
except JWTError:
raise HTTPException(401, "Invalid credentials")
user = await user_crud.get_user_by_username(db, username)
if user is None:
raise HTTPException(401, "User not found")
return user
# app/api/v1/endpoints/auth.py
@router.post("/login")
async def login(
form_data: OAuth2PasswordRequestForm = Depends(),
db: AsyncSession = Depends(get_db)
):
user = await user_crud.get_user_by_username(db, form_data.username)
if not user or not verify_password(form_data.password, user.hashed_password):
raise HTTPException(401, "Incorrect username or password")
access_token = create_access_token(data={"sub": user.username})
return {"access_token": access_token, "token_type": "bearer"}
```
### Pattern 5: Authorization with Dependency Injection
```python
# Reusable authorization checkers
from typing import List
from fastapi import Depends, HTTPException
class RoleChecker:
def __init__(self, allowed_roles: List[str]):
self.allowed_roles = allowed_roles
def __call__(self, user: User = Depends(get_current_user)):
if user.role not in self.allowed_roles:
raise HTTPException(403, f"Role '{user.role}' not allowed")
return user
# Usage in routes
@router.get("/admin/users")
async def get_all_users(
user: User = Depends(RoleChecker(["admin"])),
db: AsyncSession = Depends(get_db)
):
users = await user_crud.get_users(db)
return users
```
### Pattern 6: Request Validation & Error Handling
```python
from fastapi import Request, status
from fastapi.exceptions import RequestValidationError
from fastapi.responses import JSONResponse
@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
errors = [{
"field": ".".join(str(x) for x in e["loc"]),
"message": e["msg"]
} for e in exc.errors()]
return JSONResponse(
status_code=422,
content={"detail": "Validation failed", "errors": errors}
)
@app.exception_handler(Exception)
async def general_exception_handler(request: Request, exc: Exception):
if settings.ENVIRONMENT == "production":
return JSONResponse(500, {"detail": "Internal server error"})
return JSONResponse(500, {"detail": str(exc)})
```
### Pattern 7: Rate Limiting
```python
from slowapi import Limiter, _rate_limit_exceeded_handler
from slowapi.util import get_remote_address
from slowapi.errors import RateLimitExceeded
limiter = Limiter(key_func=get_remote_address)
app.state.limiter = limiter
app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
@router.post("/auth/login")
@limiter.limit("5/minute") # Prevent brute force
async def login(request: Request, form_data: OAuth2PasswordRequestForm = Depends()):
# Login logic
pass
```
### Pattern 8: Background Tasks
```python
from fastapi import BackgroundTasks
async def send_welcome_email(email: str, username: str):
# Non-blocking email sending
await email_service.send(to=email, subject="Welcome", body=f"Hi {username}")
@router.post("/register")
async def register_user(
user_in: UserCreate,
background_tasks: BackgroundTasks,
db: AsyncSession = Depends(get_db)
):
user = await user_crud.create_user(db, user_in)
background_tasks.add_task(send_welcome_email, user.email, user.username)
return user
```
### Pattern 9: Testing with pytest
```python
# tests/conftest.py
import pytest
from fastapi.testclient import TestClient
from app.main import app
from app.db.session import get_db
@pytest.fixture
def client():
with TestClient(app) as c:
yield c
# tests/test_users.py
def test_create_user(client):
response = client.post("/api/v1/users/", json={
"email": "[email protected]",
"username": "testuser",
"password": "Test123!@#",
"full_name": "Test User"
})
assert response.status_code == 201
data = response.json()
assert data["email"] == "[email protected]"
assert "password" not in data # Never expose password
def test_login(client):
response = client.post("/api/v1/auth/login",
data={"username": "testuser", "password": "Test123!@#"})
assert response.status_code == 200
assert "access_token" in response.json()
```
### Pattern 10: Configuration Management
```python
# app/core/config.py
from pydantic_settings import BaseSettings
from typing import List
class Settings(BaseSettings):
PROJECT_NAME: str = "FastAPI App"
ENVIRONMENT: str = "development"
SECRET_KEY: str # MUST be set in .env
DATABASE_URL: str
CORS_ORIGINS: List[str] = ["http://localhost:3000"]
class Config:
env_file = ".env"
settings = Settings()
# Validate production settings
if settings.ENVIRONMENT == "production":
assert len(settings.SECRET_KEY) >= 32
assert "*" not in settings.CORS_ORIGINS
```
---
## 6. Performance Patterns
### Pattern 1: Connection Pooling
```python
# Bad - No connection pooling configuration
engine = create_async_engine(DATABASE_URL)
# Good - Proper connection pooling
engine = create_async_engine(
DATABASE_URL,
pool_size=20, # Base number of connections
max_overflow=10, # Extra connections when pool is full
pool_recycle=3600, # Recycle connections after 1 hour
pool_pre_ping=True, # Check connection health before use
pool_timeout=30, # Wait 30s for available connection
)
# Good - Proper cleanup on shutdown
@app.on_event("shutdown")
async def shutdown():
await engine.dispose()
```
### Pattern 2: Concurrent Operations with asyncio.gather
```python
# Bad - Sequential async calls
async def get_user_dashboard(user_id: int, db: AsyncSession):
user = await get_user(db, user_id)
orders = await get_user_orders(db, user_id)
notifications = await get_notifications(db, user_id)
return {"user": user, "orders": orders, "notifications": notifications}
# Good - Concurrent async calls
async def get_user_dashboard(user_id: int, db: AsyncSession):
user, orders, notifications = await asyncio.gather(
get_user(db, user_id),
get_user_orders(db, user_id),
get_notifications(db, user_id),
)
return {"user": user, "orders": orders, "notifications": notifications}
# Good - With error handling for partial failures
async def get_user_dashboard_safe(user_id: int, db: AsyncSession):
results = await asyncio.gather(
get_user(db, user_id),
get_user_orders(db, user_id),
get_notifications(db, user_id),
return_exceptions=True # Don't fail all if one fails
)
user, orders, notifications = results
return {
"user": user if not isinstance(user, Exception) else None,
"orders": orders if not isinstance(orders, Exception) else [],
"notifications": notifications if not isinstance(notifications, Exception) else [],
}
```
### Pattern 3: Response Caching
```python
# Bad - No caching, database hit every request
@router.get("/products")
async def get_products(db: AsyncSession = Depends(get_db)):
result = await db.execute(select(Product))
return result.scalars().all()
# Good - In-memory caching with TTL
from cachetools import TTLCache
from functools import wraps
cache = TTLCache(maxsize=100, ttl=300) # 5 minutes TTL
def cached(key_func):
def decorator(func):
@wraps(func)
async def wrapper(*args, **kwargs):
key = key_func(*args, **kwargs)
if key in cache:
return cache[key]
result = await func(*args, **kwargs)
cache[key] = result
return result
return wrapper
return decorator
@router.get("/products")
@cached(key_func=lambda: "products_list")
async def get_products(db: AsyncSession = Depends(get_db)):
result = await db.execute(select(Product))
return result.scalars().all()
# Good - Redis caching for distributed systems
import aioredis
import json
redis = aioredis.from_url("redis://localhost")
@router.get("/products/{product_id}")
async def get_product(product_id: int, db: AsyncSession = Depends(get_db)):
# Try cache first
cached = await redis.get(f"product:{product_id}")
if cached:
return json.loads(cached)
# Fetch from database
result = await db.execute(select(Product).where(Product.id == product_id))
product = result.scalar_one_or_none()
if not product:
raise HTTPException(404, "Product not found")
# Cache for 5 minutes
await redis.setex(f"product:{product_id}", 300, json.dumps(product.dict()))
return product
```
### Pattern 4: Streaming Responses
```python
# Bad - Load entire file into memory
@router.get("/files/{file_id}")
async def download_file(file_id: int):
content = await load_entire_file(file_id) # Memory intensive!
return Response(content=content, media_type="application/octet-stream")
# Good - Stream large files
from fastapi.responses import StreamingResponse
import aiofiles
@router.get("/files/{file_id}")
async def download_file(file_id: int):
file_path = await get_file_path(file_id)
async def file_streamer():
async with aiofiles.open(file_path, 'rb') as f:
while chunk := await f.read(8192): # 8KB chunks
yield chunk
return StreamingResponse(
file_streamer(),
media_type="application/octet-stream",
headers={"Content-Disposition": f"attachment; filename={file_id}"}
)
# Good - Stream database results
@router.get("/export/users")
async def export_users(db: AsyncSession = Depends(get_db)):
async def generate():
yield "id,email,username\n" # CSV header
result = await db.stream(select(User))
async for row in result:
user = row[0]
yield f"{user.id},{user.email},{user.username}\n"
return StreamingResponse(
generate(),
media_type="text/csv",
headers={"Content-Disposition": "attachment; filename=users.csv"}
)
```
### Pattern 5: Async Database Queries
```python
# Bad - Synchronous query pattern
def get_users_sync(db):
return db.query(User).filter(User.is_active == True).all()
# Good - Async query pattern
async def get_users_async(db: AsyncSession):
result = await db.execute(
select(User).where(User.is_active == True)
)
return result.scalars().all()
# Good - Efficient pagination
async def get_users_paginated(
db: AsyncSession,
skip: int = 0,
limit: int = 20
):
result = await db.execute(
select(User)
.where(User.is_active == True)
.offset(skip)
.limit(limit)
.order_by(User.created_at.desc())
)
return result.scalars().all()
# Good - Avoid N+1 with eager loading
from sqlalchemy.orm import selectinload
async def get_users_with_orders(db: AsyncSession):
result = await db.execute(
select(User)
.options(selectinload(User.orders)) # Eager load orders
.where(User.is_active == True)
)
return result.scalars().all()
```
### Pattern 6: Background Task Optimization
```python
# Bad - Blocking operation in request
@router.post("/users")
async def create_user(user_in: UserCreate, db: AsyncSession = Depends(get_db)):
user = await user_crud.create_user(db, user_in)
await send_welcome_email(user.email) # Blocks response!
await notify_admins(user) # More blocking!
return user
# Good - Non-blocking background tasks
from fastapi import BackgroundTasks
@router.post("/users")
async def create_user(
user_in: UserCreate,
background_tasks: BackgroundTasks,
db: AsyncSession = Depends(get_db)
):
user = await user_crud.create_user(db, user_in)
# Queue non-critical tasks
background_tasks.add_task(send_welcome_email, user.email)
background_tasks.add_task(notify_admins, user)
return user # Return immediately!
# Good - For heavy tasks, use task queue (Celery/ARQ)
from arq import create_pool
@router.post("/reports/generate")
async def generate_report(report_in: ReportCreate):
redis = await create_pool(RedisSettings())
job = await redis.enqueue_job('generate_report', report_in.dict())
return {"job_id": job.job_id, "status": "queued"}
```
---
## 7. Security Standards
### 7.1 OWASP Top 10 2025 Mapping
| OWASP ID | Category | FastAPI Mitigation |
|----------|----------|-------------------|
| A01:2025 | Broken Access Control | `Depends(get_current_user)` on all protected routes |
| A02:2025 | Security Misconfiguration | Disable docs in prod, use Pydantic Settings |
| A03:2025 | Supply Chain | Pin dependencies in requirements.txt |
| A04:2025 | Insecure Design | Pydantic validation on all inputs |
| A05:2025 | Identification & Auth | JWT with bcrypt, OAuth2PasswordBearer |
| A06:2025 | Vulnerable Components | Run `pip-audit` and `safety check` |
| A07:2025 | Cryptographic Failures | HTTPS only, bcrypt for passwords |
| A08:2025 | Injection | SQLAlchemy ORM, parameterized queries |
| A09:2025 | Logging Failures | Structured logging, exclude secrets |
| A10:2025 | Exception Handling | Custom handlers, hide stack traces |
### 5.2 Input Validation & Injection Prevention
```python
# ✅ PREVENT SQL INJECTION
from pydantic import BaseModel, field_validator
class SearchQuery(BaseModel):
query: str = Field(..., min_length=1, max_length=100)
@field_validator('query')
@classmethod
def sanitize(cls, v: str) -> str:
# Block SQL injection patterns
forbidden = ['--', ';', '/*', 'xp_', 'union', 'select', 'drop']
if any(p in v.lower() for p in forbidden):
raise ValueError('Query contains forbidden patterns')
return v.strip()
# ✅ ALWAYS use ORM (parameterized queries)
result = await db.execute(select(User).where(User.email == email))
# ❌ NEVER string concatenation
# query = f"SELECT * FROM users WHERE email = '{email}'" # VULNERABLE!
```
### 5.3 CORS Security
```python
# ❌ NEVER use wildcard in production
app.add_middleware(CORSMiddleware, allow_origins=["*"]) # DANGEROUS!
# ✅ Whitelist specific origins
app.add_middleware(CORSMiddleware, allow_origins=[
"https://yourdomain.com",
"https://app.yourdomain.com"
])
```
### 5.4 Secrets Management
```python
# .env file (add to .gitignore!)
SECRET_KEY=your-32-char-secret-key-here
DATABASE_URL=postgresql+asyncpg://user:pass@localhost/db
# ❌ NEVER hardcode secrets
SECRET_KEY = "my-secret" # DON'T!
# ✅ Use environment variables
SECRET_KEY = settings.SECRET_KEY
# ❌ NEVER log sensitive data
logger.info(f"Password: {password}") # DON'T!
# ✅ Sanitize logs
logger.info(f"User {user.email} logged in")
```
### 5.5 Critical Security Rules
**ALWAYS:**
- Use bcrypt for password hashing (cost factor >= 12)
- Implement rate limiting on authentication endpoints
- Validate ALL inputs with Pydantic models
- Use HTTPS in production
- Set short token expiration (15-30 min for access tokens)
- Separate request and response models
- Use parameterized queries (ORM)
**NEVER:**
- Expose password hashes in responses
- Use `allow_origins=["*"]` with credentials
- Disable HTTPS in production
- Trust user input without valid...
© martinholovsky · Unlicense · martinholovsky/claude-skills-generator
Similar skills
All skills for Backend and APIs →fastapi-expert by other authors comes first.