Fastapi Patterns

作者 affaan-mef648e01899b无许可证275K 个星标收录于 2026年10月8日更新于 2026年10月8日仓库3天前更新

FastAPI patterns for async APIs, dependency injection, Pydantic request and response models, OpenAPI docs, tests, security, and production readiness.

仅含说明Software Development
AI 生成的概览

提供面向生产环境的 FastAPI 模式，涵盖异步 API、依赖注入、Pydantic 模型、测试、安全与部署。

功能
该技能提供参考指导和可直接复制的代码模式，用于组织 FastAPI 服务，涵盖应用工厂、路由布局、Pydantic 请求与响应模型、依赖注入、异步端点、错误处理、OpenAPI 定制、测试，以及安全和性能检查清单。它产出的是书面模式和示例片段，而不是运行脚本或生成文件。它还说明了如何审查 FastAPI 拉取请求中的生产风险。
适用场景
适用于构建或审查 FastAPI 应用、拆分路由、模式、依赖和数据库访问，或编写调用数据库或外部服务的异步端点。它也用于添加身份验证、授权、OpenAPI 文档、测试或部署设置，以及检查 FastAPI 拉取请求中的生产风险。
运行要求
仅为说明性内容，不附带脚本。示例假定使用 Python 以及 FastAPI、Pydantic、SQLAlchemy 异步、httpx 和 pytest，但该技能本身不安装或执行任何内容。

FastAPI Patterns

Production-oriented patterns for FastAPI services.

When to Use

  • Building or reviewing a FastAPI app.
  • Splitting routers, schemas, dependencies, and database access.
  • Writing async endpoints that call a database or external service.
  • Adding authentication, authorization, OpenAPI docs, tests, or deployment settings.
  • Checking a FastAPI PR for copy-pasteable examples and production risks.

How It Works

Treat the FastAPI app as a thin HTTP layer over explicit dependencies and service code:

  • main.py owns app construction, middleware, exception handlers, and router registration.
  • schemas/ owns Pydantic request and response models.
  • dependencies.py owns database, auth, pagination, and request-scoped dependencies.
  • services/ or crud/ owns business and persistence operations.
  • tests/ overrides dependencies instead of opening production resources.

Prefer small routers and explicit response_model declarations. Keep raw ORM objects, secrets, and framework globals out of response schemas.

Project Layout

text
app/|-- main.py|-- config.py|-- dependencies.py|-- exceptions.py|-- api/|   `-- routes/|       |-- users.py|       `-- health.py|-- core/|   |-- security.py|   `-- middleware.py|-- db/|   |-- session.py|   `-- crud.py|-- models/|-- schemas/`-- tests/

Application Factory

Use a factory so tests and workers can build the app with controlled settings.

python
from contextlib import asynccontextmanager
from fastapi import FastAPIfrom fastapi.middleware.cors import CORSMiddleware
from app.api.routes import health, usersfrom app.config import settingsfrom app.db.session import close_db, init_dbfrom app.exceptions import register_exception_handlers
@asynccontextmanagerasync def lifespan(app: FastAPI):    await init_db()    yield    await close_db()
def create_app() -> FastAPI:    app = FastAPI(        title=settings.api_title,        version=settings.api_version,        lifespan=lifespan,    )
    app.add_middleware(        CORSMiddleware,        allow_origins=settings.cors_origins,        allow_credentials=bool(settings.cors_origins),        allow_methods=["GET", "POST", "PUT", "PATCH", "DELETE"],        allow_headers=["Authorization", "Content-Type"],    )
    register_exception_handlers(app)    app.include_router(health.router, prefix="/health", tags=["health"])    app.include_router(users.router, prefix="/api/v1/users", tags=["users"])    return app
app = create_app()

Do not use allow_origins=["*"] with allow_credentials=True; browsers reject that combination and Starlette disallows it for credentialed requests.

Pydantic Schemas

Keep request, update, and response models separate.

python
from datetime import datetimefrom typing import Annotatedfrom uuid import UUID
from pydantic import BaseModel, ConfigDict, EmailStr, Field
class UserBase(BaseModel):    email: EmailStr    full_name: Annotated[str, Field(min_length=1, max_length=100)]
class UserCreate(UserBase):    password: Annotated[str, Field(min_length=12, max_length=128)]
class UserUpdate(BaseModel):    email: EmailStr | None = None    full_name: Annotated[str | None, Field(min_length=1, max_length=100)] = None
class UserResponse(UserBase):    model_config = ConfigDict(from_attributes=True)
    id: UUID    created_at: datetime    updated_at: datetime

Response models must never include password hashes, access tokens, refresh tokens, or internal authorization state.

Dependencies

Use dependency injection for request-scoped resources.

python
from collections.abc import AsyncIteratorfrom uuid import UUID
from fastapi import Depends, HTTPException, statusfrom fastapi.security import OAuth2PasswordBearerfrom sqlalchemy.ext.asyncio import AsyncSession
from app.core.security import decode_tokenfrom app.db.session import session_factoryfrom app.models.user import User
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/v1/auth/login")
async def get_db() -> AsyncIterator[AsyncSession]:    async with session_factory() as session:        try:            yield session            await session.commit()        except Exception:            await session.rollback()            raise
async def get_current_user(    token: str = Depends(oauth2_scheme),    db: AsyncSession = Depends(get_db),) -> User:    payload = decode_token(token)    user_id = UUID(payload["sub"])    user = await db.get(User, user_id)    if user is None:        raise HTTPException(status_code=status.HTTP_401_UNAUTHORIZED, detail="Invalid token")    return user

Avoid creating sessions, clients, or credentials inline inside route handlers.

Async Endpoints

Keep route handlers async when they perform I/O, and use async libraries inside them.

python
from fastapi import APIRouter, Depends, Queryfrom sqlalchemy import selectfrom sqlalchemy.ext.asyncio import AsyncSession
from app.dependencies import get_current_user, get_dbfrom app.models.user import Userfrom app.schemas.user import UserResponse
router = APIRouter()
@router.get("/", response_model=list[UserResponse])async def list_users(    limit: int = Query(default=50, ge=1, le=100),    offset: int = Query(default=0, ge=0),    db: AsyncSession = Depends(get_db),    current_user: User = Depends(get_current_user),):    result = await db.execute(        select(User).order_by(User.created_at.desc()).limit(limit).offset(offset)    )    return result.scalars().all()

Use httpx.AsyncClient for external HTTP calls from async handlers. Do not call requests in an async route.

Error Handling

Centralize domain exceptions and keep response shapes stable.

python
from fastapi import FastAPI, Requestfrom fastapi.responses import JSONResponse
class ApiError(Exception):    def __init__(self, status_code: int, code: str, message: str):        self.status_code = status_code        self.code = code        self.message = message
def register_exception_handlers(app: FastAPI) -> None:    @app.exception_handler(ApiError)    async def api_error_handler(request: Request, exc: ApiError):        return JSONResponse(            status_code=exc.status_code,            content={"error": {"code": exc.code, "message": exc.message}},        )

OpenAPI Customization

Assign the custom OpenAPI callable to app.openapi; do not just call the function once.

python
from fastapi import FastAPIfrom fastapi.openapi.utils import get_openapi
def install_openapi(app: FastAPI) -> None:    def custom_openapi():        if app.openapi_schema:            return app.openapi_schema        app.openapi_schema = get_openapi(            title="Service API",            version="1.0.0",            routes=app.routes,        )        return app.openapi_schema
    app.openapi = custom_openapi

Testing

Override the dependency used by Depends, not an internal helper that route handlers never reference.

python
import pytestfrom httpx import ASGITransport, AsyncClientfrom sqlalchemy.ext.asyncio import AsyncSession
from app.dependencies import get_dbfrom app.main import create_app
@pytest.fixtureasync def client(test_session: AsyncSession):    app = create_app()
    async def override_get_db():        yield test_session
    app.dependency_overrides[get_db] = override_get_db    async with AsyncClient(        transport=ASGITransport(app=app),        base_url="http://test",    ) as test_client:        yield test_client    app.dependency_overrides.clear()

Security Checklist

  • Hash passwords with argon2-cffi, bcrypt, or a current passlib-compatible hasher.
  • Validate JWT issuer, audience, expiry, and signing algorithm.
  • Keep CORS origins environment-specific.
  • Put rate limits on auth and write-heavy endpoints.
  • Use Pydantic models for all request bodies.
  • Use ORM parameter binding or SQLAlchemy Core expressions; never build SQL with f-strings.
  • Redact tokens, authorization headers, cookies, and passwords from logs.
  • Run dependency audit tooling in CI.

Performance Checklist

  • Configure database connection pooling explicitly.
  • Add pagination to list endpoints.
  • Watch for N+1 queries and use eager loading intentionally.
  • Use async HTTP/database clients in async paths.
  • Add compression only after checking payload size and CPU tradeoffs.
  • Cache stable expensive reads behind explicit invalidation.

Examples

Use these examples as patterns, not as project-wide templates:

  • Application factory: configure middleware and routers once in create_app.
  • Schema split: UserCreate, UserUpdate, and UserResponse have different responsibilities.
  • Dependency override: tests override get_db directly.
  • OpenAPI customization: assign app.openapi = custom_openapi.

See Also

  • Agent: fastapi-reviewer
  • Command: /fastapi-review
  • Skill: python-patterns
  • Skill: python-testing
  • Skill: api-design

来源与署名

来源：affaan-m/ecc位于.kiro/skills/fastapi-patterns提交ef648e0

许可证： 无许可证

内容归原作者所有。SourceWeft 从公开仓库中收录这些内容。

举报或申请下架

更多来自 affaan-m/ecc 的技能

Vue Patterns

affaan-m

Vue 3 Composition API、组件架构、Pinia 状态管理、Vue Router 与 Nuxt SSR 模式的参考指南。

Software Development275K3天前更新

Uncloud

affaan-m

使用 uc CLI 管理 Uncloud 集群的参考指南：部署服务、Caddy 入口、端口、扩缩容与日志。

DevOps & Cloud275K3天前更新

Team Agent Orchestration

affaan-m

以团队方式协调多个 AI 智能体，使用工作项、看板状态、分支隔离与合并门禁。

AI & Agents275K3天前更新

Tasteforge Video

affaan-m

Use for file-driven multimodal image, video, and 3D-asset discovery; taste interviews; distill or apply workflows; style-pack validation; editable EDL/FCPXML export; provenance audits; and offline planning that must fail closed before provider generation.

待分类275K3天前更新

Taste

affaan-m

为音乐视频和短视频剪辑定义 angelcore / cloud-trance / hyperpop 视觉方向，包含氛围、剪辑语法与按节拍映射的分镜方案。

Design & Creative275K3天前更新

Social Publisher

affaan-m

通过 SocialClaw 工作区 API 在 13 个平台上安排和发布社交媒体帖子。

Marketing & Sales275K3天前更新

更多Software Development技能

Playground

anthropics

精选

构建自包含的交互式 HTML 演练场，包含控件、实时预览和可复制的提示词输出。

Software Development37K今天更新

M5 Onboard

anthropics

精选

通过 USB 检测 M5Stack ESP32 开发板，刷写 UIFlow 2.0 固件并安装 MicroPython 应用包。

Software Development37K今天更新

Cardputer Buddy

anthropics

精选

指导迭代 Cardputer-Adv 的 MicroPython 应用包：添加应用、通过 USB 串口推送文件、查看日志并运行 REPL 命令。

Software Development37K今天更新

Testing Strategy

anthropics

精选

设计测试策略与测试计划，涵盖测试类型、覆盖率目标与示例测试用例。

Software Development27K今天更新

Tech Debt

anthropics

精选

识别、分类并排序技术债务，产出评分后的待办清单与分阶段整改计划。

Software Development27K今天更新

System Design

anthropics

精选

通过需求、高层设计、深入设计、扩展与权衡分析来指导系统与架构设计。

Software Development27K今天更新