Python FastAPI 实战：构建现代化 Web API – wiki大全

作者： /

Python FastAPI 实战：构建现代化 Web API

在当今快速发展的 Web 服务领域，高效、高性能且易于维护的 API 是成功的关键。Python FastAPI 正是为满足这些需求而生的一款现代 Web 框架。它以其卓越的性能、自动化的文档生成、强大的数据验证以及对异步编程的原生支持，迅速成为了开发者们构建 Web API 的首选工具。

1. 什么是 FastAPI？为何选择它？

FastAPI 是一个用于构建 API 的现代、快速（高性能）的 Web 框架，基于标准的 Python 类型提示。它的灵感来源于 Starlette（用于 Web 部分）和 Pydantic（用于数据部分），并在此基础上提供了许多开箱即用的特性。

选择 FastAPI 的主要优势包括：

  • 极高的性能: 与 Node.js 和 Go 并驾齐驱，是目前最快的 Python Web 框架之一。
  • 快速的开发速度: 显著提高开发速度，减少 20% 到 40% 的开发时间。
  • 减少 Bug: 减少 40% 的人为错误。
  • 直观: 优秀的用户体验和自动补全功能。
  • 健壮: 生产就绪的代码，拥有自动交互式文档。
  • 标准化: 基于开放标准，如 OpenAPI（以前称为 Swagger）和 JSON Schema。
  • 异步支持: 原生支持 async/await，可以处理高并发请求。
  • Pydantic: 强大的数据验证和序列化工具，基于 Python 类型提示。
  • 依赖注入: 易于使用且功能强大的依赖注入系统。

2. 核心特性一览

FastAPI 的核心特性使其在众多 Python Web 框架中脱颖而出：

  • 基于 Starlette 和 Pydantic: 继承了 Starlette 的轻量级和高性能，以及 Pydantic 的数据验证和模型定义能力。
  • 自动交互式 API 文档 (Swagger UI / ReDoc): 仅通过编写 Python 代码，FastAPI 就能自动生成符合 OpenAPI 规范的交互式 API 文档，大大简化了文档维护工作。
  • 类型提示: 利用 Python 的类型提示进行数据验证、自动补全和代码检查，提高代码质量和可维护性。
  • 依赖注入系统: 允许您在路径操作函数中声明依赖项，FastAPI 会自动解析并注入这些依赖项，使得代码更加模块化和可测试。

3. 搭建 FastAPI 项目

开始一个 FastAPI 项目非常简单。首先，您需要安装 FastAPI 和一个 ASGI 服务器（如 Uvicorn）：

bash
pip install fastapi uvicorn[standard]

创建一个 main.py 文件：

“`python

main.py

from fastapi import FastAPI

app = FastAPI()

@app.get(“/”)
async def read_root():
return {“message”: “Hello, FastAPI!”}
“`

运行应用程序：

bash
uvicorn main:app --reload

现在，您可以在浏览器中访问 http://127.0.0.1:8000 看到 “Hello, FastAPI!”，访问 http://127.0.0.1:8000/docs 或 http://127.0.0.1:8000/redoc 查看自动生成的 API 文档。

4. 推荐的项目结构

随着项目的增长，良好的项目结构对于代码的维护性和可扩展性至关重要。以下是一个推荐的 FastAPI 项目结构：

my_fastapi_project/
├── app/
│ ├── __init__.py
│ ├── main.py # FastAPI 应用程序的入口点
│ ├── api/ # API 路由定义，可按版本划分
│ │ ├── v1/ # API 版本 1
│ │ │ ├── __init__.py
│ │ │ └── endpoints/ # 具体端点定义，按资源分组
│ │ │ ├── users.py
│ │ │ └── items.py
│ │ └── __init__.py
│ ├── core/ # 核心配置、设置和安全逻辑
│ │ ├── __init__.py
│ │ └── config.py # 应用程序设置（如数据库 URL, 密钥）
│ │ └── security.py # 认证和授权逻辑
│ ├── db/ # 数据库配置、会话管理和迁移
│ │ ├── __init__.py
│ │ ├── database.py # 数据库引擎和会话创建
│ │ └── base.py # SQLAlchemy 模型基类
│ ├── models/ # SQLAlchemy 模型，定义数据库表
│ │ ├── __init__.py
│ │ └── user.py # 用户数据库模型示例
│ ├── schemas/ # Pydantic 模型，用于数据验证、序列化和 OpenAPI 模式生成
│ │ ├── __init__.py
│ │ └── user.py # 用户输入/输出的 Pydantic 模式示例
│ ├── services/ # 业务逻辑和操作，与 API 路由分离
│ │ ├── __init__.py
│ │ └── user_service.py # 用户相关操作的服务示例
│ ├── dependencies/ # 跨路由的通用依赖项（如数据库会话、当前用户）
│ │ ├── __init__.py
│ │ └── auth.py # 认证依赖项
│ └── utils/ # 实用函数和辅助模块
│ ├── __init__.py
│ └── helpers.py
├── tests/ # 应用程序的单元和集成测试
│ ├── __init__.py
│ ├── test_users.py
│ └── conftest.py # Pytest fixture
├── .env # 环境变量 (不应提交到版本控制)
├── requirements.txt # 项目依赖项
├── Dockerfile # (可选) 用于容器化应用程序
├── README.md # 项目文档

这种模块化方法促进了关注点分离，使代码库更易于理解、测试和扩展。

5. 构建 API 端点

FastAPI 使用装饰器来定义路径操作。您可以为不同的 HTTP 方法（GET, POST, PUT, DELETE 等）创建路径操作：

“`python

app/api/v1/endpoints/items.py

from fastapi import APIRouter, HTTPException
from typing import List

router = APIRouter()

假设这是一个简单的内存数据库

items_db = []

@router.post(“/items/”, response_model=dict)
async def create_item(item: dict):
items_db.append(item)
return {“message”: “Item created successfully”, “item”: item}

@router.get(“/items/”, response_model=List[dict])
async def read_items():
return items_db

@router.get(“/items/{item_id}”, response_model=dict)
async def read_item(item_id: int):
if item_id >= len(items_db) or item_id < 0:
raise HTTPException(status_code=404, detail=”Item not found”)
return items_db[item_id]
“`

在 app/main.py 中引入这些路由：

“`python

app/main.py

from fastapi import FastAPI
from app.api.v1.endpoints import items

app = FastAPI()

app.include_router(items.router, prefix=”/v1″, tags=[“items”])
“`

6. 数据验证与序列化 (Pydantic)

Pydantic 是 FastAPI 的核心组成部分，它使用 Python 类型提示来定义数据模型，并自动进行数据验证、序列化和反序列化。

“`python

app/schemas/item.py

from pydantic import BaseModel

class ItemBase(BaseModel):
name: str
description: str | None = None
price: float
tax: float | None = None

class ItemCreate(ItemBase):
pass

class Item(ItemBase):
id: int

class Config:
    orm_mode = True # 兼容 ORM 模型

“`

在路径操作中使用 Pydantic 模型：

“`python

app/api/v1/endpoints/items.py (更新后)

from fastapi import APIRouter, HTTPException
from typing import List
from app.schemas.item import Item, ItemCreate # 导入 Pydantic 模型

router = APIRouter()

items_db: List[Item] = [] # 使用 Item 模型定义数据库

@router.post(“/items/”, response_model=Item)
async def create_item(item: ItemCreate):
new_item = Item(id=len(items_db), **item.dict())
items_db.append(new_item)
return new_item

@router.get(“/items/”, response_model=List[Item])
async def read_items():
return items_db

@router.get(“/items/{item_id}”, response_model=Item)
async def read_item(item_id: int):
if item_id >= len(items_db) or item_id < 0:
raise HTTPException(status_code=404, detail=”Item not found”)
return items_db[item_id]
“`

FastAPI 会自动验证传入的请求体数据，并在响应中将 Python 对象序列化为 JSON。

7. 依赖注入

FastAPI 强大的依赖注入系统允许您声明可复用的依赖项，这些依赖项可以是函数、类或任何可调用对象。

“`python

app/dependencies/auth.py

from fastapi import Header, HTTPException

async def get_token_header(x_token: str = Header()):
if x_token != “fake-super-secret-token”:
raise HTTPException(status_code=400, detail=”X-Token header invalid”)
return x_token

app/api/v1/endpoints/items.py (使用依赖注入)

from fastapi import APIRouter, Depends, HTTPException
from typing import List
from app.schemas.item import Item, ItemCreate
from app.dependencies.auth import get_token_header

router = APIRouter()

items_db: List[Item] = []

@router.post(“/items/”, response_model=Item, dependencies=[Depends(get_token_header)])
async def create_item(item: ItemCreate):
new_item = Item(id=len(items_db), **item.dict())
items_db.append(new_item)
return new_item
“`

这里，get_token_header 依赖项会在 /items/ 路径操作函数执行前被调用，验证 X-Token 请求头。

8. 测试

FastAPI 与 pytest 配合使用，可以方便地进行单元测试和集成测试。您可以使用 httpx 或 TestClient 来模拟请求。

“`python

tests/test_items.py

from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_create_item():
response = client.post(
“/v1/items/”,
headers={“X-Token”: “fake-super-secret-token”},
json={“name”: “Foo”, “description”: “A very nice Item”, “price”: 12.3, “tax”: 0.5},
)
assert response.status_code == 200
assert response.json()[“item”][“name”] == “Foo”
“`

9. 部署考量

部署 FastAPI 应用程序通常涉及以下步骤：

  • 容器化: 使用 Dockerfile 将应用程序及其依赖项打包到 Docker 镜像中。
  • WSGI/ASGI 服务器: 在生产环境中使用 Uvicorn、Gunicorn 等 ASGI 服务器运行应用程序。
  • 反向代理: 使用 Nginx 或 Caddy 等反向代理服务器将外部请求转发到您的 FastAPI 应用程序。
  • 监控与日志: 集成监控和日志系统，以便跟踪应用程序的性能和错误。

10. 总结

FastAPI 是一个功能强大、性能卓越且开发友好的 Python Web 框架，非常适合构建现代化的 Web API。它通过利用 Python 类型提示、Pydantic 和依赖注入，极大地提高了开发效率和代码质量。通过遵循推荐的项目结构和最佳实践，您可以构建出可维护、可扩展且高效的 API，从而应对不断变化的业务需求。

希望这篇实战文章能帮助您更好地理解和使用 FastAPI，开启您的现代化 Web API 构建之旅！

滚动至顶部