fastapi-templates

来源声明：本技能内容源自 wshobson/agents （MIT License, Copyright (c) 2024 Seth Hobson；完整许可文本见同目录 LICENSE.txt）。 使用、修改与再分发须遵守该 MIT 许可条款并保留版权声明。

中文描述

本技能提供全栈开发相关的最佳实践和模式指导。

---

name: fastapi-templates description: 使用异步模式、依赖注入和全面的错误处理，创建可用于生产环境的 FastAPI 项目。适用于构建新的 FastAPI 应用或搭建后端 API 项目。

FastAPI 项目模板

可用于生产环境的 FastAPI 项目结构，包含异步模式、依赖注入、中间件，以及构建高性能 API 的最佳实践。

适用场景

• 从头开始启动新的 FastAPI 项目
• 使用 Python 实现异步 REST API
• 构建高性能 Web 服务和微服务
• 使用 PostgreSQL、MongoDB 创建异步应用
• 搭建结构合理且包含测试的 API 项目

核心概念

1. 项目结构

推荐布局：

app/
├── api/                    # API routes
│   ├── v1/
│   │   ├── endpoints/
│   │   │   ├── users.py
│   │   │   ├── auth.py
│   │   │   └── items.py
│   │   └── router.py
│   └── dependencies.py     # Shared dependencies
├── core/                   # Core configuration
│   ├── config.py
│   ├── security.py
│   └── database.py
├── models/                 # Database models
│   ├── user.py
│   └── item.py
├── schemas/                # Pydantic schemas
│   ├── user.py
│   └── item.py
├── services/               # Business logic
│   ├── user_service.py
│   └── auth_service.py
├── repositories/           # Data access
│   ├── user_repository.py
│   └── item_repository.py
└── main.py                 # Application entry

2. 依赖注入

FastAPI 内置的 DI 系统使用 Depends：

• 数据库会话管理
• 身份验证／授权
• 共享业务逻辑
• 配置注入

3. 异步模式

正确使用 async/await：

• 异步路由处理程序
• 异步数据库操作
• 异步后台任务
• 异步中间件

详细示例与模式

详细章节（从 ## Implementation Patterns 开始）位于 references/details.md。如果上述导航摘要无法满足需要，请阅读该文件。

测试

# tests/conftest.py
import pytest
import asyncio
from httpx import AsyncClient
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

from app.main import app
from app.core.database import get_db, Base

TEST_DATABASE_URL = "sqlite+aiosqlite:///:memory:"

@pytest.fixture(scope="session")
def event_loop():
    loop = asyncio.get_event_loop_policy().new_event_loop()
    yield loop
    loop.close()

@pytest.fixture
async def db_session():
    engine = create_async_engine(TEST_DATABASE_URL, echo=True)
    async with engine.begin() as conn:
        await conn.run_sync(Base.metadata.create_all)

    AsyncSessionLocal = sessionmaker(
        engine, class_=AsyncSession, expire_on_commit=False
    )

    async with AsyncSessionLocal() as session:
        yield session

@pytest.fixture
async def client(db_session):
    async def override_get_db():
        yield db_session

    app.dependency_overrides[get_db] = override_get_db

    async with AsyncClient(app=app, base_url="http://test") as client:
        yield client

# tests/test_users.py
import pytest

@pytest.mark.asyncio
async def test_create_user(client):
    response = await client.post(
        "/api/v1/users/",
        json={
            "email": "[email protected]",
            "password": "testpass123",
            "name": "Test User"
        }
    )
    assert response.status_code == 201
    data = response.json()
    assert data["email"] == "[email protected]"
    assert "id" in data

能力边界

✅ 擅长处理

• 全栈开发相关的最佳实践
• 代码架构设计指导
• 性能优化建议

⚠️ 需要素材

• 具体的项目上下文
• 技术栈信息

❌ 超出范围

• 非技术领域的业务决策
• 具体的代码实现（仅提供指导）

工作流程

第 1 步：需求分析

理解项目需求和技术约束

第 2 步：架构设计

设计系统架构和组件划分

第 3 步：实现指导

提供具体的实现建议和代码模式

第 4 步：代码审查

审查代码质量和最佳实践遵循情况

第 5 步：优化建议

提供性能优化和改进建议

注意事项

1. 过度设计

避免在简单场景中使用复杂的设计模式

2. 忽视性能

不要忽视性能优化，特别是在生产环境中

3. 安全考虑

始终考虑安全性和数据保护

4. 测试覆盖

确保有足够的测试覆盖，特别是边界情况

5. 文档维护

保持文档与代码同步更新