К основному содержанию
скилл CX Codex

fastapi-expert · martinholovsky — скилл для Claude Code: что делает и как установить

Скилл fastapi-expert настраивает агента на разработку асинхронных API на FastAPI с валидацией Pydantic v2, базой через SQLAlchemy 2.0 и тестами через pytest.

Unlicense 267 установок ★ 48 обновлён 2025-12-06

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add martinholovsky/claude-skills-generator --skill fastapi-expert -a claude-code
Открыть на GitHub

Что делает fastapi-expert

Скилл инструктирует модель строить серверные эндпоинты по методике TDD. Сначала ассистент пишет падающий тест с использованием httpx.AsyncClient и pytest-asyncio, затем реализует минимальный рабочий роут с внедрением зависимостей, а после проверяет типы через mypy и безопасность через pip-audit или safety.

В архитектуре упор сделан на стек Pydantic v2 и SQLAlchemy 2.0 с драйвером asyncpg. Скилл включает паттерны авторизации по OAuth2 с JWT и refresh-токенами, управление сессиями через async_sessionmaker, миграции Alembic и защиту по стандарту OWASP Top 10.

Поскольку скилл жёстко ориентирован на асинхронный стек и второй мажорный релиз Pydantic, он будет конфликтовать со старыми проектами на Pydantic v1 или синхронном SQLAlchemy.

Какие задачи решает

  • написать асинхронный эндпоинт на FastAPI с валидацией через Pydantic v2
  • настроить авторизацию по OAuth2 с выдачей JWT и проверкой ролей
  • покрыть API интеграционными тестами на базе httpx и pytest-asyncio
  • организовать пул соединений к базе данных через SQLAlchemy 2.0 и AsyncPG

Примеры запросов агенту

  • Спроектируй защищённый роут регистрации пользователя с валидацией пароля и тестом на httpx
  • Настрой асинхронную сессию SQLAlchemy 2.0 и модель пользователя с миграцией Alembic
  • Добавь rate limiting и CORS для эндпоинтов авторизации

Как установить fastapi-expert

1Через Skills CLI (Vercel)

npx skills add martinholovsky/claude-skills-generator --skill fastapi-expert -a claude-code

2Вручную: положить файлы

~/.claude/skills/fastapi-expert/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/fastapi-expert/

По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов

Вопросы о fastapi-expert

Как установить fastapi-expert в Claude Code?

Выполните команду npx skills add martinholovsky/claude-skills-generator --skill fastapi-expert -a claude-code в терминале.

Какой подход к разработке использует скилл?

Он требует строгого цикла TDD: сначала пишется падающий тест эндпоинта, затем минимальный код роута, после чего запускаются линтер ruff и тайпчекер mypy.

С какими библиотеками баз данных работает этот скилл?

Скилл рассчитан на асинхронный SQLAlchemy 2.0 в связке с asyncpg для PostgreSQL либо aiosqlite для тестового окружения.

Исходный текст

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

Похожие скиллы

Все скиллы по теме «Бэкенд и API» →

Сначала — fastapi-expert от других авторов.

fastapi-expert https://github.com/Jeffallan Скилл fastapi-expert для Claude Code помогает разрабатывать асинхронные API на FastAPI с моделями Pydantic V2. Охватывает маршруты, аутентификацию, работу с базой и тесты. CX Codex +1 6 600установок fastapi-expert personamanagmentlayer Скилл fastapi-expert для разработки API на FastAPI: модели Pydantic, JWT-авторизация, SQLAlchemy и фоновые задачи с готовыми примерами кода. CX Codex +1 218установок fastapi-patterns affaan-m Скилл fastapi-patterns задаёт структуру продакшен-проекта на FastAPI, схему валидации Pydantic v2 и внедрение зависимостей. Пригодится при проектировании сервисов, настройке JWT-авторизации и подготовке тестов. CX Codex +1 6 700установок FastAPI Service taste f Промпт FastAPI Service taste для ChatGPT и Claude.ai задаёт инженерные правила проектирования бэкенда на FastAPI. Фиксирует архитектурные соглашения перед генерацией сервисов. GP ChatGPT ★ 178 201звёзд репо fastapi PatrickJS Правило задаёт практики для FastAPI-проектов на Python: структура, API, модели, база данных, безопасность и тесты. Подключается к файлам по glob-шаблонам. CX Codex +1 ★ 41 178звёзд репо api-scaffolding-fastapi-pro Seth Hobson Субагент api-scaffolding-fastapi-pro для Claude Code помогает проектировать и писать асинхронные API на FastAPI. Подключается к задачам по FastAPI, оптимизации async-кода и архитектуре API. CX Codex ★ 42 780звёзд репо fastapi-python Mindrally Скилл fastapi-python для Claude Code, Codex, Cursor и других платформ: эксперт по FastAPI и асинхронному Python. Включается при разработке REST API, валидации через Pydantic и оптимизации производительности. CX Codex +1 14 100установок fastapi-development aj-geddes Скилл fastapi-development для ИИ-агента, который помогает писать Python-API на FastAPI: асинхронные роуты, валидация через Pydantic, JWT и автодокументация OpenAPI. CX Codex +1 627установок

Из того же набора50

Весь набор →
surrealdb-expert Скилл surrealdb-expert помогает проектировать схемы SurrealDB, настраивать графовые связи, писать запросы SurrealQL и защищать данные на уровне строк через TDD. CX Codex +1 276установок websocket Помогает закрыть WebSocket-эндпоинт от CSWSH: проверять Origin, токен до соединения и права на каждое сообщение. Защищает сокеты в проде и при проектировании. CX Codex +1 272установок graph-database-expert Скилл graph-database-expert помогает проектировать графовые схемы, составлять обходы и оптимизировать запросы. Сфокусирован на SurrealDB, но поддерживает Cypher и общие графовые паттерны. CX Codex +1 271установок rust Скилл rust для Claude Code помогает писать серверную часть настольных приложений на Tauri с учётом безопасности памяти и производительности. Подключается к задачам по Rust, асинхронному коду и командам Tauri. CX Codex +1 268установок fastapi Скилл fastapi для Claude Code помогает разрабатывать REST API и WebSocket-сервисы на FastAPI с проверкой входных данных и защитой. Он включается при задачах по созданию и настройке таких сервисов. CX Codex +1 265установок async-programming Скилл async-programming для Claude Code помогает писать асинхронный код на Python и Rust, защищать его от гонок и утечек ресурсов. Включается при работе с asyncio и Tokio. CX Codex +1 259установок api-expert Скилл api-expert проектирует API по стандартам OpenAPI 3.1 и OWASP. Помогает писать контракты, тесты на pytest и закрывать уязвимости BOLA. CX Codex +1 258установок threejs-tresjs Скилл threejs-tresjs для Claude Code создаёт 3D HUD-интерфейсы на Three.js и TresJS с Vue 3. Описывает панели показателей, индикаторы и эффекты частиц. CX Codex +1 255установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой