fastapi-development

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

FastAPI Development

FastAPI 开发

A comprehensive skill for building modern, high-performance Python APIs with FastAPI. Master async/await patterns, Pydantic data validation, dependency injection, authentication, database integration, and production-ready deployment strategies.
这是一项使用FastAPI构建现代高性能Python API的全面技能。掌握async/await模式、Pydantic数据验证、依赖注入、身份验证、数据库集成以及可用于生产环境的部署策略。

When to Use This Skill

何时使用该技能

Use this skill when:
  • Building RESTful APIs with Python for web, mobile, or microservices
  • Developing high-performance, asynchronous backend services
  • Creating APIs with automatic interactive documentation (OpenAPI/Swagger)
  • Implementing OAuth2, JWT authentication, or other security patterns
  • Integrating with SQL or NoSQL databases in Python applications
  • Building APIs that require strong data validation and type safety
  • Developing microservices with automatic request/response validation
  • Creating APIs with WebSocket support for real-time features
  • Migrating from Flask, Django REST Framework, or other Python frameworks
  • Building production-ready APIs with proper error handling and testing
在以下场景使用该技能:
  • 为Web、移动应用或微服务构建基于Python的RESTful API
  • 开发高性能的异步后端服务
  • 创建带有自动交互式文档(OpenAPI/Swagger)的API
  • 实现OAuth2、JWT身份验证或其他安全模式
  • 在Python应用中集成SQL或NoSQL数据库
  • 构建需要强数据验证和类型安全的API
  • 开发带有自动请求/响应验证的微服务
  • 创建支持WebSocket的实时功能API
  • 从Flask、Django REST Framework或其他Python框架迁移
  • 构建具备完善错误处理和测试的生产级API

Core Concepts

核心概念

FastAPI Philosophy

FastAPI 设计理念

FastAPI is built on three foundational principles:
  • Fast to Code: Reduce development time with automatic validation and documentation
  • Fast to Run: High performance comparable to NodeJS and Go (via Starlette and Pydantic)
  • Fewer Bugs: Automatic validation reduces human errors by about 40%
  • Standards-Based: Built on OpenAPI and JSON Schema standards
  • Editor Support: Full autocomplete, type checking, and inline documentation
FastAPI基于三个核心原则构建:
  • 编码快速:通过自动验证和文档减少开发时间
  • 运行快速:性能可与NodeJS和Go媲美(基于Starlette和Pydantic)
  • 更少Bug:自动验证可减少约40%的人为错误
  • 基于标准:构建在OpenAPI和JSON Schema标准之上
  • 编辑器支持:完整的自动补全、类型检查和内联文档

Key FastAPI Features

FastAPI 关键特性

  1. Type Hints: Python 3.6+ type hints for validation and documentation
  2. Async Support: Native async/await for high-performance I/O operations
  3. Pydantic Models: Automatic request/response validation and serialization
  4. Dependency Injection: Elegant system for sharing logic across endpoints
  5. OpenAPI Docs: Automatic interactive API documentation
  6. Security: Built-in support for OAuth2, JWT, API keys, and more
  7. Testing: Easy to test with TestClient and async test support
  1. 类型提示:使用Python 3.6+类型提示实现验证和文档生成
  2. 异步支持:原生支持async/await以实现高性能I/O操作
  3. Pydantic 模型:自动完成请求/响应验证和序列化
  4. 依赖注入:用于在端点间共享逻辑的优雅系统
  5. OpenAPI 文档:自动生成交互式API文档
  6. 安全机制:内置支持OAuth2、JWT、API密钥等
  7. 测试支持:可通过TestClient轻松测试,支持异步测试

Core Architecture Components

核心架构组件

  1. FastAPI App: The main application instance
  2. Path Operations: Endpoint definitions with HTTP methods
  3. Pydantic Models: Data validation and serialization schemas
  4. Dependencies: Reusable logic for authentication, database, etc.
  5. Routers: Organize endpoints into modules
  6. Middleware: Process requests/responses globally
  7. Background Tasks: Execute code after returning responses
  1. FastAPI App:主应用实例
  2. 路径操作:带有HTTP方法的端点定义
  3. Pydantic 模型:数据验证和序列化模式
  4. 依赖项:用于身份验证、数据库等的可复用逻辑
  5. 路由器:将端点组织为模块
  6. 中间件:全局处理请求/响应
  7. 后台任务:返回响应后执行代码

Getting Started

快速开始

Installation

安装

bash
undefined
bash
undefined

Basic installation

基础安装

pip install fastapi
pip install fastapi

With ASGI server for production

安装用于生产环境的ASGI服务器

pip install "fastapi[all]"
pip install "fastapi[all]"

Or install separately

或单独安装

pip install fastapi uvicorn[standard]
pip install fastapi uvicorn[standard]

Additional dependencies

额外依赖

pip install python-multipart # For form data pip install python-jose[cryptography] # For JWT pip install passlib[bcrypt] # For password hashing pip install sqlalchemy # For SQL databases pip install databases # For async database support
undefined
pip install python-multipart # 用于表单数据 pip install python-jose[cryptography] # 用于JWT pip install passlib[bcrypt] # 用于密码哈希 pip install sqlalchemy # 用于SQL数据库 pip install databases # 用于异步数据库支持
undefined

Minimal FastAPI Application

最小FastAPI应用

python
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}
python
from fastapi import FastAPI

app = FastAPI()

@app.get("/")
async def root():
    return {"message": "Hello World"}

Run with: uvicorn main:app --reload

运行命令: uvicorn main:app --reload

undefined
undefined

Pydantic Models for Data Validation

用于数据验证的Pydantic模型

Basic Model Definition

基础模型定义

python
from pydantic import BaseModel, Field, EmailStr, HttpUrl
from typing import Optional, List
from datetime import datetime

class User(BaseModel):
    id: int
    username: str = Field(..., min_length=3, max_length=50)
    email: EmailStr
    full_name: Optional[str] = None
    is_active: bool = True
    created_at: datetime = Field(default_factory=datetime.utcnow)

class UserCreate(BaseModel):
    username: str = Field(..., min_length=3, max_length=50)
    email: EmailStr
    password: str = Field(..., min_length=8)
    full_name: Optional[str] = None

class UserResponse(BaseModel):
    id: int
    username: str
    email: EmailStr
    full_name: Optional[str]
    is_active: bool

    class Config:
        orm_mode = True  # For SQLAlchemy models
python
from pydantic import BaseModel, Field, EmailStr, HttpUrl
from typing import Optional, List
from datetime import datetime

class User(BaseModel):
    id: int
    username: str = Field(..., min_length=3, max_length=50)
    email: EmailStr
    full_name: Optional[str] = None
    is_active: bool = True
    created_at: datetime = Field(default_factory=datetime.utcnow)

class UserCreate(BaseModel):
    username: str = Field(..., min_length=3, max_length=50)
    email: EmailStr
    password: str = Field(..., min_length=8)
    full_name: Optional[str] = None

class UserResponse(BaseModel):
    id: int
    username: str
    email: EmailStr
    full_name: Optional[str]
    is_active: bool

    class Config:
        orm_mode = True  # 适配SQLAlchemy模型

Nested Models

嵌套模型

python
class Image(BaseModel):
    url: HttpUrl
    name: str

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float = Field(..., gt=0)
    tax: Optional[float] = None
    tags: List[str] = []
    images: Optional[List[Image]] = None
python
class Image(BaseModel):
    url: HttpUrl
    name: str

class Item(BaseModel):
    name: str
    description: Optional[str] = None
    price: float = Field(..., gt=0)
    tax: Optional[float] = None
    tags: List[str] = []
    images: Optional[List[Image]] = None

Request example:

请求示例:

{

{

"name": "Laptop",

"name": "Laptop",

"price": 999.99,

"price": 999.99,

"tags": ["electronics", "computers"],

"tags": ["electronics", "computers"],

"images": [

"images": [

{"url": "http://example.com/img1.jpg", "name": "Front view"}

{"url": "http://example.com/img1.jpg", "name": "Front view"}

]

]

}

}

undefined
undefined

Model Validation and Examples

模型验证与示例

python
from pydantic import BaseModel, Field, validator

class Product(BaseModel):
    name: str = Field(..., example="MacBook Pro")
    price: float = Field(..., gt=0, example=1999.99)
    discount: Optional[float] = Field(None, ge=0, le=100, example=10.0)

    @validator('discount')
    def discount_check(cls, v, values):
        if v and 'price' in values:
            discounted = values['price'] * (1 - v/100)
            if discounted < 0:
                raise ValueError('Discounted price cannot be negative')
        return v

    class Config:
        schema_extra = {
            "example": {
                "name": "MacBook Pro 16",
                "price": 2499.99,
                "discount": 15.0
            }
        }
python
from pydantic import BaseModel, Field, validator

class Product(BaseModel):
    name: str = Field(..., example="MacBook Pro")
    price: float = Field(..., gt=0, example=1999.99)
    discount: Optional[float] = Field(None, ge=0, le=100, example=10.0)

    @validator('discount')
    def discount_check(cls, v, values):
        if v and 'price' in values:
            discounted = values['price'] * (1 - v/100)
            if discounted < 0:
                raise ValueError('Discounted price cannot be negative')
        return v

    class Config:
        schema_extra = {
            "example": {
                "name": "MacBook Pro 16",
                "price": 2499.99,
                "discount": 15.0
            }
        }

Path Operations and Routing

路径操作与路由

HTTP Methods and Path Parameters

HTTP方法与路径参数

python
from fastapi import FastAPI, Path, Query, Body
from typing import Optional

app = FastAPI()
python
from fastapi import FastAPI, Path, Query, Body
from typing import Optional

app = FastAPI()

GET with path parameter

带路径参数的GET请求

@app.get("/items/{item_id}") async def read_item( item_id: int = Path(..., title="The ID of the item", ge=1), q: Optional[str] = Query(None, max_length=50) ): return {"item_id": item_id, "q": q}
@app.get("/items/{item_id}") async def read_item( item_id: int = Path(..., title="物品的ID", ge=1), q: Optional[str] = Query(None, max_length=50) ): return {"item_id": item_id, "q": q}

POST with request body

带请求体的POST请求

@app.post("/items/") async def create_item(item: Item): return {"item": item, "message": "Item created"}
@app.post("/items/") async def create_item(item: Item): return {"item": item, "message": "物品已创建"}

PUT for updates

用于更新的PUT请求

@app.put("/items/{item_id}") async def update_item( item_id: int, item: Item = Body(...), ): return {"item_id": item_id, "item": item}
@app.put("/items/{item_id}") async def update_item( item_id: int, item: Item = Body(...), ): return {"item_id": item_id, "item": item}

DELETE

DELETE请求

@app.delete("/items/{item_id}") async def delete_item(item_id: int): return {"message": f"Item {item_id} deleted"}
@app.delete("/items/{item_id}") async def delete_item(item_id: int): return {"message": f"物品 {item_id} 已删除"}

PATCH for partial updates

用于部分更新的PATCH请求

@app.patch("/items/{item_id}") async def partial_update_item( item_id: int, item: dict = Body(...) ): return {"item_id": item_id, "updated_fields": item}
undefined
@app.patch("/items/{item_id}") async def partial_update_item( item_id: int, item: dict = Body(...) ): return {"item_id": item_id, "updated_fields": item}
undefined

Query Parameters with Validation

带验证的查询参数

python
from fastapi import Query
from typing import List, Optional

@app.get("/search/")
async def search_items(
    q: str = Query(..., min_length=3, max_length=50),
    skip: int = Query(0, ge=0),
    limit: int = Query(10, ge=1, le=100),
    sort_by: Optional[str] = Query(None, regex="^(name|price|date)$"),
    tags: List[str] = Query([], description="Filter by tags")
):
    return {
        "q": q,
        "skip": skip,
        "limit": limit,
        "sort_by": sort_by,
        "tags": tags
    }
python
from fastapi import Query
from typing import List, Optional

@app.get("/search/")
async def search_items(
    q: str = Query(..., min_length=3, max_length=50),
    skip: int = Query(0, ge=0),
    limit: int = Query(10, ge=1, le=100),
    sort_by: Optional[str] = Query(None, regex="^(name|price|date)$"),
    tags: List[str] = Query([], description="按标签过滤")
):
    return {
        "q": q,
        "skip": skip,
        "limit": limit,
        "sort_by": sort_by,
        "tags": tags
    }

Response Models

响应模型

python
from typing import List

@app.post("/users/", response_model=UserResponse)
async def create_user(user: UserCreate):
    # Hash password, save to DB
    db_user = {
        "id": 1,
        "username": user.username,
        "email": user.email,
        "full_name": user.full_name,
        "is_active": True
    }
    return db_user

@app.get("/users/", response_model=List[UserResponse])
async def list_users(skip: int = 0, limit: int = 100):
    users = [...]  # Fetch from database
    return users
python
from typing import List

@app.post("/users/", response_model=UserResponse)
async def create_user(user: UserCreate):
    # 哈希密码,保存到数据库
    db_user = {
        "id": 1,
        "username": user.username,
        "email": user.email,
        "full_name": user.full_name,
        "is_active": True
    }
    return db_user

@app.get("/users/", response_model=List[UserResponse])
async def list_users(skip: int = 0, limit: int = 100):
    users = [...]  # 从数据库获取
    return users

Exclude fields from response

从响应中排除字段

class UserInDB(User): hashed_password: str
@app.get("/users/{user_id}", response_model=UserResponse) async def get_user(user_id: int): user = get_user_from_db(user_id) # Returns UserInDB return user # Password excluded automatically
undefined
class UserInDB(User): hashed_password: str
@app.get("/users/{user_id}", response_model=UserResponse) async def get_user(user_id: int): user = get_user_from_db(user_id) # 返回UserInDB return user # 密码会自动被排除
undefined

Async/Await Patterns

Async/Await 模式

When to Use async vs def

何时使用async vs def

python
undefined
python
undefined

Use async def when:

当以下情况时使用async def:

- Making database queries with async driver

- 使用异步驱动进行数据库查询

- Calling external APIs with httpx/aiohttp

- 使用httpx/aiohttp调用外部API

- Using async I/O operations

- 执行异步I/O操作

- Working with async libraries

- 使用异步库

@app.get("/async-example") async def async_endpoint(): # Can use await inside result = await async_database_query() external_data = await async_http_call() return {"result": result, "external": external_data}
@app.get("/async-example") async def async_endpoint(): # 内部可以使用await result = await async_database_query() external_data = await async_http_call() return {"result": result, "external": external_data}

Use def when:

当以下情况时使用def:

- Working with synchronous libraries

- 使用同步库

- Performing CPU-bound operations

- 执行CPU密集型操作

- No async operations needed

- 不需要异步操作

@app.get("/sync-example") def sync_endpoint(): # Regular synchronous code result = synchronous_database_query() return {"result": result}
undefined
@app.get("/sync-example") def sync_endpoint(): # 常规同步代码 result = synchronous_database_query() return {"result": result}
undefined

Async Database Operations

异步数据库操作

python
import asyncio
from databases import Database

DATABASE_URL = "postgresql://user:password@localhost/dbname"
database = Database(DATABASE_URL)

@app.on_event("startup")
async def startup():
    await database.connect()

@app.on_event("shutdown")
async def shutdown():
    await database.disconnect()

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    query = "SELECT * FROM users WHERE id = :user_id"
    user = await database.fetch_one(query, {"user_id": user_id})
    return user

@app.post("/users/")
async def create_user(user: UserCreate):
    query = """
        INSERT INTO users (username, email, hashed_password)
        VALUES (:username, :email, :password)
        RETURNING *
    """
    hashed_password = hash_password(user.password)
    new_user = await database.fetch_one(
        query,
        {
            "username": user.username,
            "email": user.email,
            "password": hashed_password
        }
    )
    return new_user
python
import asyncio
from databases import Database

DATABASE_URL = "postgresql://user:password@localhost/dbname"
database = Database(DATABASE_URL)

@app.on_event("startup")
async def startup():
    await database.connect()

@app.on_event("shutdown")
async def shutdown():
    await database.disconnect()

@app.get("/users/{user_id}")
async def get_user(user_id: int):
    query = "SELECT * FROM users WHERE id = :user_id"
    user = await database.fetch_one(query, {"user_id": user_id})
    return user

@app.post("/users/")
async def create_user(user: UserCreate):
    query = """
        INSERT INTO users (username, email, hashed_password)
        VALUES (:username, :email, :password)
        RETURNING *
    """
    hashed_password = hash_password(user.password)
    new_user = await database.fetch_one(
        query,
        {
            "username": user.username,
            "email": user.email,
            "password": hashed_password
        }
    )
    return new_user

Concurrent Operations

并发操作

python
import asyncio
import httpx

async def fetch_user(user_id: int):
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com/users/{user_id}")
        return response.json()

@app.get("/users/batch")
async def get_multiple_users(user_ids: List[int] = Query(...)):
    # Fetch all users concurrently
    users = await asyncio.gather(*[fetch_user(uid) for uid in user_ids])
    return {"users": users}
python
import asyncio
import httpx

async def fetch_user(user_id: int):
    async with httpx.AsyncClient() as client:
        response = await client.get(f"https://api.example.com/users/{user_id}")
        return response.json()

@app.get("/users/batch")
async def get_multiple_users(user_ids: List[int] = Query(...)):
    # 并发获取所有用户
    users = await asyncio.gather(*[fetch_user(uid) for uid in user_ids])
    return {"users": users}

Dependency Injection

依赖注入

Basic Dependencies

基础依赖项

python
from fastapi import Depends
from typing import Optional
python
from fastapi import Depends
from typing import Optional

Simple dependency function

简单的依赖函数

async def common_parameters( q: Optional[str] = None, skip: int = 0, limit: int = 100 ): return {"q": q, "skip": skip, "limit": limit}
@app.get("/items/") async def read_items(commons: dict = Depends(common_parameters)): return commons
@app.get("/users/") async def read_users(commons: dict = Depends(common_parameters)): return commons
undefined
async def common_parameters( q: Optional[str] = None, skip: int = 0, limit: int = 100 ): return {"q": q, "skip": skip, "limit": limit}
@app.get("/items/") async def read_items(commons: dict = Depends(common_parameters)): return commons
@app.get("/users/") async def read_users(commons: dict = Depends(common_parameters)): return commons
undefined

Class-Based Dependencies

基于类的依赖项

python
class Pagination:
    def __init__(
        self,
        skip: int = Query(0, ge=0),
        limit: int = Query(100, ge=1, le=100)
    ):
        self.skip = skip
        self.limit = limit

@app.get("/items/")
async def list_items(pagination: Pagination = Depends()):
    return {
        "skip": pagination.skip,
        "limit": pagination.limit,
        "items": []  # Fetch with pagination
    }
python
class Pagination:
    def __init__(
        self,
        skip: int = Query(0, ge=0),
        limit: int = Query(100, ge=1, le=100)
    ):
        self.skip = skip
        self.limit = limit

@app.get("/items/")
async def list_items(pagination: Pagination = Depends()):
    return {
        "skip": pagination.skip,
        "limit": pagination.limit,
        "items": []  # 按分页获取数据
    }

Database Session Dependency

数据库会话依赖项

python
from sqlalchemy.orm import Session
from typing import Generator

def get_db() -> Generator[Session, None, None]:
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.get("/users/{user_id}")
async def get_user(
    user_id: int,
    db: Session = Depends(get_db)
):
    user = db.query(User).filter(User.id == user_id).first()
    if not user:
        raise HTTPException(status_code=404, detail="User not found")
    return user
python
from sqlalchemy.orm import Session
from typing import Generator

def get_db() -> Generator[Session, None, None]:
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

@app.get("/users/{user_id}")
async def get_user(
    user_id: int,
    db: Session = Depends(get_db)
):
    user = db.query(User).filter(User.id == user_id).first()
    if not user:
        raise HTTPException(status_code=404, detail="用户未找到")
    return user

Sub-Dependencies

子依赖项

python
from fastapi import Header, HTTPException

async def verify_token(x_token: str = Header(...)):
    if x_token != "secret-token":
        raise HTTPException(status_code=400, detail="Invalid token")
    return x_token

async def verify_key(x_key: str = Header(...)):
    if x_key != "secret-key":
        raise HTTPException(status_code=400, detail="Invalid key")
    return x_key

async def verify_credentials(
    token: str = Depends(verify_token),
    key: str = Depends(verify_key)
):
    return {"token": token, "key": key}

@app.get("/protected/")
async def protected_route(credentials: dict = Depends(verify_credentials)):
    return {"message": "Access granted", "credentials": credentials}
python
from fastapi import Header, HTTPException

async def verify_token(x_token: str = Header(...)):
    if x_token != "secret-token":
        raise HTTPException(status_code=400, detail="无效令牌")
    return x_token

async def verify_key(x_key: str = Header(...)):
    if x_key != "secret-key":
        raise HTTPException(status_code=400, detail="无效密钥")
    return x_key

async def verify_credentials(
    token: str = Depends(verify_token),
    key: str = Depends(verify_key)
):
    return {"token": token, "key": key}

@app.get("/protected/")
async def protected_route(credentials: dict = Depends(verify_credentials)):
    return {"message": "访问已授权", "credentials": credentials}

Global Dependencies

全局依赖项

python
async def log_requests():
    print("Request received")

app = FastAPI(dependencies=[Depends(log_requests)])
python
async def log_requests():
    print("收到请求")

app = FastAPI(dependencies=[Depends(log_requests)])

This dependency runs for ALL endpoints

该依赖项会在所有端点执行

undefined
undefined

Authentication and Security

身份验证与安全

OAuth2 Password Bearer with JWT

基于JWT的OAuth2密码模式

python
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from jose import JWTError, jwt
from passlib.context import CryptContext
from datetime import datetime, timedelta
from typing import Optional

SECRET_KEY = "your-secret-key-here"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

class Token(BaseModel):
    access_token: str
    token_type: str

class TokenData(BaseModel):
    username: Optional[str] = None

def verify_password(plain_password, hashed_password):
    return pwd_context.verify(plain_password, hashed_password)

def get_password_hash(password):
    return pwd_context.hash(password)

def create_access_token(data: dict, expires_delta: Optional[timedelta] = None):
    to_encode = data.copy()
    if expires_delta:
        expire = datetime.utcnow() + expires_delta
    else:
        expire = datetime.utcnow() + timedelta(minutes=15)
    to_encode.update({"exp": expire})
    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
    return encoded_jwt

async def get_current_user(token: str = Depends(oauth2_scheme)):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if username is None:
            raise credentials_exception
        token_data = TokenData(username=username)
    except JWTError:
        raise credentials_exception

    user = get_user_from_db(username=token_data.username)
    if user is None:
        raise credentials_exception
    return user

async def get_current_active_user(
    current_user: User = Depends(get_current_user)
):
    if not current_user.is_active:
        raise HTTPException(status_code=400, detail="Inactive user")
    return current_user

@app.post("/token", response_model=Token)
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(form_data.username, form_data.password)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect username or password",
            headers={"WWW-Authenticate": "Bearer"},
        )
    access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    access_token = create_access_token(
        data={"sub": user.username}, expires_delta=access_token_expires
    )
    return {"access_token": access_token, "token_type": "bearer"}

@app.get("/users/me", response_model=User)
async def read_users_me(current_user: User = Depends(get_current_active_user)):
    return current_user
python
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
from jose import JWTError, jwt
from passlib.context import CryptContext
from datetime import datetime, timedelta
from typing import Optional

SECRET_KEY = "your-secret-key-here"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 30

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")

class Token(BaseModel):
    access_token: str
    token_type: str

class TokenData(BaseModel):
    username: Optional[str] = None

def verify_password(plain_password, hashed_password):
    return pwd_context.verify(plain_password, hashed_password)

def get_password_hash(password):
    return pwd_context.hash(password)

def create_access_token(data: dict, expires_delta: Optional[timedelta] = None):
    to_encode = data.copy()
    if expires_delta:
        expire = datetime.utcnow() + expires_delta
    else:
        expire = datetime.utcnow() + timedelta(minutes=15)
    to_encode.update({"exp": expire})
    encoded_jwt = jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)
    return encoded_jwt

async def get_current_user(token: str = Depends(oauth2_scheme)):
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="无法验证凭据",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if username is None:
            raise credentials_exception
        token_data = TokenData(username=username)
    except JWTError:
        raise credentials_exception

    user = get_user_from_db(username=token_data.username)
    if user is None:
        raise credentials_exception
    return user

async def get_current_active_user(
    current_user: User = Depends(get_current_user)
):
    if not current_user.is_active:
        raise HTTPException(status_code=400, detail="用户未激活")
    return current_user

@app.post("/token", response_model=Token)
async def login(form_data: OAuth2PasswordRequestForm = Depends()):
    user = authenticate_user(form_data.username, form_data.password)
    if not user:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="用户名或密码错误",
            headers={"WWW-Authenticate": "Bearer"},
        )
    access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    access_token = create_access_token(
        data={"sub": user.username}, expires_delta=access_token_expires
    )
    return {"access_token": access_token, "token_type": "bearer"}

@app.get("/users/me", response_model=User)
async def read_users_me(current_user: User = Depends(get_current_active_user)):
    return current_user

API Key Authentication

API密钥身份验证

python
from fastapi import Security
from fastapi.security import APIKeyHeader

API_KEY = "your-api-key"
api_key_header = APIKeyHeader(name="X-API-Key")

async def verify_api_key(api_key: str = Security(api_key_header)):
    if api_key != API_KEY:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="Invalid API Key"
        )
    return api_key

@app.get("/secure-data")
async def get_secure_data(api_key: str = Depends(verify_api_key)):
    return {"data": "This is secure data"}
python
from fastapi import Security
from fastapi.security import APIKeyHeader

API_KEY = "your-api-key"
api_key_header = APIKeyHeader(name="X-API-Key")

async def verify_api_key(api_key: str = Security(api_key_header)):
    if api_key != API_KEY:
        raise HTTPException(
            status_code=status.HTTP_403_FORBIDDEN,
            detail="无效API密钥"
        )
    return api_key

@app.get("/secure-data")
async def get_secure_data(api_key: str = Depends(verify_api_key)):
    return {"data": "这是安全数据"}

OAuth2 with Scopes

带作用域的OAuth2

python
from fastapi.security import OAuth2PasswordBearer, SecurityScopes

oauth2_scheme = OAuth2PasswordBearer(
    tokenUrl="token",
    scopes={
        "items:read": "Read items",
        "items:write": "Create and update items",
        "users:read": "Read user information"
    }
)

async def get_current_user_with_scopes(
    security_scopes: SecurityScopes,
    token: str = Depends(oauth2_scheme)
):
    # Verify token and check scopes
    if security_scopes.scopes:
        authenticate_value = f'Bearer scope="{security_scopes.scope_str}"'
    else:
        authenticate_value = "Bearer"

    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="Could not validate credentials",
        headers={"WWW-Authenticate": authenticate_value},
    )

    # Decode JWT and verify scopes...
    return user

@app.get("/items/", dependencies=[Security(get_current_user_with_scopes, scopes=["items:read"])])
async def read_items():
    return [{"item": "Item 1"}, {"item": "Item 2"}]

@app.post("/items/", dependencies=[Security(get_current_user_with_scopes, scopes=["items:write"])])
async def create_item(item: Item):
    return {"item": item}
python
from fastapi.security import OAuth2PasswordBearer, SecurityScopes

oauth2_scheme = OAuth2PasswordBearer(
    tokenUrl="token",
    scopes={
        "items:read": "读取物品",
        "items:write": "创建和更新物品",
        "users:read": "读取用户信息"
    }
)

async def get_current_user_with_scopes(
    security_scopes: SecurityScopes,
    token: str = Depends(oauth2_scheme)
):
    # 验证令牌并检查作用域
    if security_scopes.scopes:
        authenticate_value = f'Bearer scope="{security_scopes.scope_str}"'
    else:
        authenticate_value = "Bearer"

    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="无法验证凭据",
        headers={"WWW-Authenticate": authenticate_value},
    )

    # 解码JWT并验证作用域...
    return user

@app.get("/items/", dependencies=[Security(get_current_user_with_scopes, scopes=["items:read"])])
async def read_items():
    return [{"item": "物品1"}, {"item": "物品2"}]

@app.post("/items/", dependencies=[Security(get_current_user_with_scopes, scopes=["items:write"])])
async def create_item(item: Item):
    return {"item": item}

Database Integration

数据库集成

SQLAlchemy Setup

SQLAlchemy 设置

python
from sqlalchemy import create_engine, Column, Integer, String, Boolean
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

SQLALCHEMY_DATABASE_URL = "postgresql://user:password@localhost/dbname"

engine = create_engine(SQLALCHEMY_DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

Base = declarative_base()
python
from sqlalchemy import create_engine, Column, Integer, String, Boolean
from sqlalchemy.ext.declarative import declarative_base
from sqlalchemy.orm import sessionmaker

SQLALCHEMY_DATABASE_URL = "postgresql://user:password@localhost/dbname"

engine = create_engine(SQLALCHEMY_DATABASE_URL)
SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)

Base = declarative_base()

Models

模型

class UserModel(Base): tablename = "users"
id = Column(Integer, primary_key=True, index=True)
username = Column(String, unique=True, index=True)
email = Column(String, unique=True, index=True)
hashed_password = Column(String)
is_active = Column(Boolean, default=True)
Base.metadata.create_all(bind=engine)
undefined
class UserModel(Base): tablename = "users"
id = Column(Integer, primary_key=True, index=True)
username = Column(String, unique=True, index=True)
email = Column(String, unique=True, index=True)
hashed_password = Column(String)
is_active = Column(Boolean, default=True)
Base.metadata.create_all(bind=engine)
undefined

CRUD Operations

CRUD 操作

python
from sqlalchemy.orm import Session
python
from sqlalchemy.orm import Session

Create

创建

@app.post("/users/", response_model=UserResponse) async def create_user(user: UserCreate, db: Session = Depends(get_db)): db_user = UserModel( username=user.username, email=user.email, hashed_password=get_password_hash(user.password) ) db.add(db_user) db.commit() db.refresh(db_user) return db_user
@app.post("/users/", response_model=UserResponse) async def create_user(user: UserCreate, db: Session = Depends(get_db)): db_user = UserModel( username=user.username, email=user.email, hashed_password=get_password_hash(user.password) ) db.add(db_user) db.commit() db.refresh(db_user) return db_user

Read

读取

@app.get("/users/{user_id}", response_model=UserResponse) async def read_user(user_id: int, db: Session = Depends(get_db)): user = db.query(UserModel).filter(UserModel.id == user_id).first() if not user: raise HTTPException(status_code=404, detail="User not found") return user
@app.get("/users/{user_id}", response_model=UserResponse) async def read_user(user_id: int, db: Session = Depends(get_db)): user = db.query(UserModel).filter(UserModel.id == user_id).first() if not user: raise HTTPException(status_code=404, detail="用户未找到") return user

Update

更新

@app.put("/users/{user_id}", response_model=UserResponse) async def update_user( user_id: int, user_update: UserCreate, db: Session = Depends(get_db) ): user = db.query(UserModel).filter(UserModel.id == user_id).first() if not user: raise HTTPException(status_code=404, detail="User not found")
user.username = user_update.username
user.email = user_update.email
if user_update.password:
    user.hashed_password = get_password_hash(user_update.password)

db.commit()
db.refresh(user)
return user
@app.put("/users/{user_id}", response_model=UserResponse) async def update_user( user_id: int, user_update: UserCreate, db: Session = Depends(get_db) ): user = db.query(UserModel).filter(UserModel.id == user_id).first() if not user: raise HTTPException(status_code=404, detail="用户未找到")
user.username = user_update.username
user.email = user_update.email
if user_update.password:
    user.hashed_password = get_password_hash(user_update.password)

db.commit()
db.refresh(user)
return user

Delete

删除

@app.delete("/users/{user_id}") async def delete_user(user_id: int, db: Session = Depends(get_db)): user = db.query(UserModel).filter(UserModel.id == user_id).first() if not user: raise HTTPException(status_code=404, detail="User not found")
db.delete(user)
db.commit()
return {"message": "User deleted successfully"}
undefined
@app.delete("/users/{user_id}") async def delete_user(user_id: int, db: Session = Depends(get_db)): user = db.query(UserModel).filter(UserModel.id == user_id).first() if not user: raise HTTPException(status_code=404, detail="用户未找到")
db.delete(user)
db.commit()
return {"message": "用户已成功删除"}
undefined

Background Tasks

后台任务

python
from fastapi import BackgroundTasks

def send_email(email: str, message: str):
    # Simulate sending email
    print(f"Sending email to {email}: {message}")

def process_file(filename: str):
    # Simulate file processing
    print(f"Processing file: {filename}")

@app.post("/send-notification/")
async def send_notification(
    email: str,
    background_tasks: BackgroundTasks
):
    background_tasks.add_task(send_email, email, "Welcome!")
    return {"message": "Notification scheduled"}

@app.post("/upload/")
async def upload_file(
    file: str,
    background_tasks: BackgroundTasks
):
    # Save file first
    background_tasks.add_task(process_file, file)
    return {"message": "File uploaded, processing in background"}
python
from fastapi import BackgroundTasks

def send_email(email: str, message: str):
    # 模拟发送邮件
    print(f"正在向 {email} 发送邮件: {message}")

def process_file(filename: str):
    # 模拟文件处理
    print(f"正在处理文件: {filename}")

@app.post("/send-notification/")
async def send_notification(
    email: str,
    background_tasks: BackgroundTasks
):
    background_tasks.add_task(send_email, email, "欢迎!")
    return {"message": "通知已安排"}

@app.post("/upload/")
async def upload_file(
    file: str,
    background_tasks: BackgroundTasks
):
    # 先保存文件
    background_tasks.add_task(process_file, file)
    return {"message": "文件已上传,正在后台处理"}

Error Handling

错误处理

Custom Exception Handlers

自定义异常处理器

python
from fastapi import Request, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError

class CustomException(Exception):
    def __init__(self, name: str):
        self.name = name

@app.exception_handler(CustomException)
async def custom_exception_handler(request: Request, exc: CustomException):
    return JSONResponse(
        status_code=418,
        content={"message": f"Oops! {exc.name} did something wrong."},
    )

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={"detail": exc.errors()},
    )

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id == "error":
        raise CustomException(name="Item")
    return {"item_id": item_id}
python
from fastapi import Request, status
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError

class CustomException(Exception):
    def __init__(self, name: str):
        self.name = name

@app.exception_handler(CustomException)
async def custom_exception_handler(request: Request, exc: CustomException):
    return JSONResponse(
        status_code=418,
        content={"message": f"糟糕!{exc.name} 出现了错误。"},
    )

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    return JSONResponse(
        status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
        content={"detail": exc.errors()},
    )

@app.get("/items/{item_id}")
async def read_item(item_id: str):
    if item_id == "error":
        raise CustomException(name="Item")
    return {"item_id": item_id}

Testing

测试

Basic Tests with TestClient

使用TestClient进行基础测试

python
from fastapi.testclient import TestClient

client = TestClient(app)

def test_read_main():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello World"}

def test_create_item():
    response = client.post(
        "/items/",
        json={"name": "Test Item", "price": 10.5}
    )
    assert response.status_code == 200
    assert response.json()["name"] == "Test Item"

def test_authentication():
    response = client.post(
        "/token",
        data={"username": "testuser", "password": "testpass"}
    )
    assert response.status_code == 200
    assert "access_token" in response.json()
python
from fastapi.testclient import TestClient

client = TestClient(app)

def test_read_main():
    response = client.get("/")
    assert response.status_code == 200
    assert response.json() == {"message": "Hello World"}

def test_create_item():
    response = client.post(
        "/items/",
        json={"name": "测试物品", "price": 10.5}
    )
    assert response.status_code == 200
    assert response.json()["name"] == "测试物品"

def test_authentication():
    response = client.post(
        "/token",
        data={"username": "testuser", "password": "testpass"}
    )
    assert response.status_code == 200
    assert "access_token" in response.json()

Async Tests

异步测试

python
import pytest
from httpx import AsyncClient

@pytest.mark.anyio
async def test_read_items():
    async with AsyncClient(app=app, base_url="http://test") as ac:
        response = await ac.get("/items/")
    assert response.status_code == 200
    assert isinstance(response.json(), list)

@pytest.mark.anyio
async def test_create_user():
    async with AsyncClient(app=app, base_url="http://test") as ac:
        response = await ac.post(
            "/users/",
            json={
                "username": "newuser",
                "email": "new@example.com",
                "password": "securepass123"
            }
        )
    assert response.status_code == 200
    assert response.json()["username"] == "newuser"
python
import pytest
from httpx import AsyncClient

@pytest.mark.anyio
async def test_read_items():
    async with AsyncClient(app=app, base_url="http://test") as ac:
        response = await ac.get("/items/")
    assert response.status_code == 200
    assert isinstance(response.json(), list)

@pytest.mark.anyio
async def test_create_user():
    async with AsyncClient(app=app, base_url="http://test") as ac:
        response = await ac.post(
            "/users/",
            json={
                "username": "newuser",
                "email": "new@example.com",
                "password": "securepass123"
            }
        )
    assert response.status_code == 200
    assert response.json()["username"] == "newuser"

Routers and Organization

路由器与代码组织

APIRouter for Modular Code

使用APIRouter实现模块化代码

python
undefined
python
undefined

routers/users.py

routers/users.py

from fastapi import APIRouter, Depends
router = APIRouter( prefix="/users", tags=["users"], dependencies=[Depends(verify_token)], responses={404: {"description": "Not found"}}, )
@router.get("/") async def list_users(): return [{"username": "user1"}, {"username": "user2"}]
@router.get("/{user_id}") async def get_user(user_id: int): return {"user_id": user_id}
from fastapi import APIRouter, Depends
router = APIRouter( prefix="/users", tags=["users"], dependencies=[Depends(verify_token)], responses={404: {"description": "未找到"}}, )
@router.get("/") async def list_users(): return [{"username": "user1"}, {"username": "user2"}]
@router.get("/{user_id}") async def get_user(user_id: int): return {"user_id": user_id}

main.py

main.py

from routers import users
app = FastAPI() app.include_router(users.router)
undefined
from routers import users
app = FastAPI() app.include_router(users.router)
undefined

Best Practices

最佳实践

1. Project Structure

1. 项目结构

my_fastapi_project/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── item.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── item.py
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── users.py
│   │   └── items.py
│   ├── dependencies/
│   │   ├── __init__.py
│   │   ├── auth.py
│   │   └── database.py
│   └── utils/
│       ├── __init__.py
│       └── security.py
├── tests/
│   ├── __init__.py
│   ├── test_users.py
│   └── test_items.py
├── requirements.txt
├── .env
└── README.md
my_fastapi_project/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── models/
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── item.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── user.py
│   │   └── item.py
│   ├── routers/
│   │   ├── __init__.py
│   │   ├── users.py
│   │   └── items.py
│   ├── dependencies/
│   │   ├── __init__.py
│   │   ├── auth.py
│   │   └── database.py
│   └── utils/
│       ├── __init__.py
│       └── security.py
├── tests/
│   ├── __init__.py
│   ├── test_users.py
│   └── test_items.py
├── requirements.txt
├── .env
└── README.md

2. Configuration Management

2. 配置管理

python
from pydantic import BaseSettings

class Settings(BaseSettings):
    app_name: str = "My FastAPI App"
    database_url: str
    secret_key: str
    algorithm: str = "HS256"
    access_token_expire_minutes: int = 30

    class Config:
        env_file = ".env"

settings = Settings()
python
from pydantic import BaseSettings

class Settings(BaseSettings):
    app_name: str = "My FastAPI App"
    database_url: str
    secret_key: str
    algorithm: str = "HS256"
    access_token_expire_minutes: int = 30

    class Config:
        env_file = ".env"

settings = Settings()

3. Documentation

3. 文档

python
app = FastAPI(
    title="My API",
    description="This is a very custom API",
    version="1.0.0",
    openapi_tags=[
        {
            "name": "users",
            "description": "Operations with users.",
        },
        {
            "name": "items",
            "description": "Manage items.",
        },
    ]
)

@app.post(
    "/items/",
    response_model=Item,
    tags=["items"],
    summary="Create an item",
    description="Create an item with all the information",
    response_description="The created item",
)
async def create_item(item: Item):
    return item
python
app = FastAPI(
    title="My API",
    description="这是一个高度定制化的API",
    version="1.0.0",
    openapi_tags=[
        {
            "name": "users",
            "description": "用户相关操作",
        },
        {
            "name": "items",
            "description": "物品管理",
        },
    ]
)

@app.post(
    "/items/",
    response_model=Item,
    tags=["items"],
    summary="创建物品",
    description="创建包含所有信息的物品",
    response_description="已创建的物品",
)
async def create_item(item: Item):
    return item

Production Deployment

生产环境部署

Docker Setup

Docker 设置

dockerfile
undefined
dockerfile
undefined

Dockerfile

Dockerfile

FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt
COPY ./app /app
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
undefined
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt
COPY ./app /app
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]
undefined

Run with Gunicorn and Uvicorn Workers

使用Gunicorn和Uvicorn Worker运行

bash
gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

Skill Version: 1.0.0 Last Updated: October 2025 Skill Category: Backend Development, API Development, Python Compatible With: FastAPI 0.100+, Python 3.7+, Pydantic 2.0+
bash
gunicorn main:app --workers 4 --worker-class uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000

技能版本: 1.0.0 最后更新: 2025年10月 技能分类: 后端开发、API开发、Python 兼容版本: FastAPI 0.100+, Python 3.7+, Pydantic 2.0+