FastAPI 最佳实践：包含示例的简明指南

FastAPI是一个现代的、高性能的 Web 框架，用于基于标准 Python 类型提示使用 Python 构建 API。

它的设计目标是快速、易于使用，并且与其他 Web 框架和工具高度兼容。

FastAPI 利用 async/await 和 Python 3.7+ 类型提示的强大功能，为构建 Web 应用程序和 API 提供高效且开发人员友好的体验。

最佳实践的主要特点和重要性

FastAPI 的一些主要功能包括：

• 高性能：FastAPI 建立在 Starlette 和 Pydantic 之上，这使其成为 Python 上最快的 Web 框架之一。
• 易于学习和使用：FastAPI 设计简洁直观，让开发人员能够轻松上手并快速提高生产力。
• 自动文档：FastAPI 使用 OpenAPI（以前称为 Swagger）和 JSON Schema 自动生成交互式 API 文档。
• 类型安全：FastAPI 使用 Python 类型提示来强制执行类型安全，这有助于在开发时而不是运行时捕获错误和错误。
• Async/await 支持：FastAPI 支持异步编程，允许开发人员构建高度并发和可扩展的应用程序。

使用 FastAPI 时遵循最佳实践至关重要，原因如下：

• 可维护性：遵循最佳实践可确保您的代码组织良好、易于理解和可维护，从而使其他开发人员更容易为您的项目做出贡献。
• 可扩展性：实施最佳实践可帮助您为应用程序创建坚实的基础，使其能够随着复杂性和规模的增长而有效地扩展。
• 安全性：遵循最佳实践可以帮助您避免常见的安全陷阱和漏洞，确保您的应用程序更加安全和稳健。
• 性能：通过遵循最佳实践，您可以优化应用程序的性能，充分利用 FastAPI 的速度和效率。
• 社区标准：遵循最佳实践可以使您的代码与社区标准和期望保持一致，从而使其他人更容易协作、审查和对您的工作提供反馈。

设置和构建你的 FastAPI 项目

在启动 FastAPI 项目之前，必须设置一个虚拟环境，以将项目的依赖项与系统上的其他 Python 项目隔离。

venv您可以使用或等工具pipenv来创建虚拟环境。在本例中，我们将使用venv：

• 为您的项目创建一个新目录并在终端中导航到该目录。
• 使用以下命令创建虚拟环境：

python3 -m venv venv

此命令在您的项目目录中创建一个名为 venv 的新虚拟环境。

• 激活虚拟环境。激活命令取决于你的操作系统：

对于 Linux 和 macOS：

source venv/bin/activate

对于 Windows：

venv\Scripts\activate

激活虚拟环境后，安装 FastAPI 和 ASGI 服务器（例如 Uvicorn 或 Hypercorn）。在本例中，我们将使用 Uvicorn：

pip install fastapi uvicorn

构建项目以实现可扩展性

正确构建 FastAPI 项目对于维护可扩展且可维护的代码库至关重要。

以下是建议的项目结构，您可以根据自己的需要进行调整：

my_fastapi_project/
│
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── api/
│   │   ├── __init__.py
│   │   ├── v1/
│   │   │   ├── __init__.py
│   │   │   ├── users.py
│   │   │   ├── posts.py
│   │   │   └── ...
│   │   └── v2/
│   │       └── ...
│   ├── models/
│   │   ├── __init__.py
│   │   ├── user.py
│   │   ├── post.py
│   │   └── ...
│   ├── config.py
│   ├── database.py
│   └── utils.py
│
├── tests/
│   ├── __init__.py
│   ├── test_users.py
│   ├── test_posts.py
│   └── ...
│
├── .env
├── requirements.txt
├── Dockerfile
└── README.md

项目结构的关键组成部分：

• app/：包含主要应用程序逻辑，包括 API 路由、模型、配置、数据库和实用程序功能。
• app/main.py：FastAPI 应用程序的入口点，您可以在此初始化应用程序并挂载 API 路由。
• app/api/：包含按版本组织的 API 路由（例如 v1、v2）。
• app/models/：包含用于数据验证和序列化的 Pydantic 数据模型。
• app/config.py：包含应用程序配置设置。
• app/database.py：包含数据库连接和相关功能。
• app/utils.py：包含整个应用程序使用的实用函数。
• tests/：包含应用程序的单元测试。.env：包含应用程序的环境变量。
• requirements.txt：列出应用程序的 Python 依赖项。
• Dockerfile：用于构建应用程序的 Docker 镜像。
• README.md：为您的项目提供概述和文档。

数据验证和处理 HTTP 请求

FastAPI 使用 Pydantic 进行数据验证和序列化。Pydantic
强制执行类型安全，并在提交无效数据时提供有用的错误消息。

要使用 Pydantic 定义数据模型，请创建一个具有所需属性及其相应类型的类：

from pydantic import BaseModel

class UserIn(BaseModel):
    username: str
    email: str
    password: str

class UserOut(BaseModel):
    id: int
    username: str
    email: str
    class Config:
        orm_mode = True

在这个例子中，我们定义了两个 Pydantic 模型，UserIn 和 UserOut，分别用于处理输入和输出用户数据。

实现路径和查询参数

FastAPI 允许您为 API 端点定义路径和查询参数。

路径参数是 URL 路径的一部分，而查询参数则以键值对的形式添加到 URL 中。
例如：

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    description: str

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str | None = None):
    return {"item_id": item_id, "q": q}

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

在此示例中，我们定义了两个 API 端点：

• /items/{item_id}：接受 item_id 路径参数和可选 q 查询参数的 GET 端点。
• /items/{item_id}：一个 PUT 端点，接受 item_id 路径参数和 Pydantic Item 模型作为请求主体。

处理 HTTP 请求和响应

FastAPI 简化了处理 HTTP 请求和响应。

您可以为每个端点定义所需的 HTTP 方法（例如，GET、POST、PUT、DELETE），设置状态代码，并使用自定义标头返回响应。

例子：

from fastapi import FastAPI, HTTPException
from fastapi.responses import JSONResponse

app = FastAPI()

@app.get("/users", response_model=List[UserOut])
async def get_users():
    users = await get_users_from_db()
    return users

@app.post("/users", response_model=UserOut, status_code=201)
async def create_user(user: UserIn):
    user_id = await create_user_in_db(user)
    return await get_user_by_id_from_db(user_id)

@app.delete("/users/{user_id}", response_class=JSONResponse)
async def delete_user(user_id: int):
    result = await delete_user_from_db(user_id)
    if not result:
        raise HTTPException(status_code=404, detail="User not found")
    return {"detail": "User deleted"}

在此示例中，我们定义了三个 API 端点：

• /users：一个 GET 端点，返回具有 200 OK 状态代码的用户列表。
• /users：一个 POST 端点，用于创建新用户并使用 201 Created 状态代码返回所创建的用户。
• /users/{user_id}：一个 DELETE 端点，用于删除用户并返回带有 200 OK 状态码的自定义响应。如果未找到用户，则会引发带有 404 Not Found 状态码的 HTTPException。

异常处理、中间件和 CORS

FastAPI 提供对异常和错误处理的内置支持。

您可以定义自定义异常处理程序来集中应用程序处理特定异常的方式，并且可以为不同的状态代码设置 HTTP 错误响应。

例子：

from fastapi import FastAPI, HTTPException
from fastapi.exceptions import RequestValidationError

app = FastAPI()

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

@app.response_exception_handler(HTTPException)
async def http_exception_handler(request, exc):
    return JSONResponse(
        status_code=exc.status_code,
        content={"detail": exc.detail}
    )

在这个例子中，我们定义了两个自定义异常处理程序：

• validation_exception_handler：处理 RequestValidationError 异常并返回 422 Unprocessable Entity 状态代码以及验证错误。
• http_exception_handler：处理HTTPException异常并返回相应的状态码和错误详情。

创建并注册自定义中间件

FastAPI 允许您创建和注册自定义中间件以在处理请求之前或之后执行操作。

中间件对于日志记录、身份验证和速率限制等任务很有用。

例子：

from fastapi import FastAPI, Request

app = FastAPI()

async def log_request_middleware(request: Request, call_next):
    request_start_time = time.monotonic()
    response = await call_next(request)
    request_duration = time.monotonic() - request_start_time
    log_data = {
        "method": request.method,
        "path": request.url.path,
        "duration": request_duration
    }
    log.info(log_data)
    return response

app.middleware("http")(log_request_middleware)

在这个例子中，我们定义了一个名为log_request_middleware的自定义中间件。

该中间件记录每个传入请求的请求方法、路径和持续时间。

然后使用 app.middleware() 将中间件注册到 FastAPI 应用程序中。

启用跨域资源共享 (CORS)

FastAPI 提供对跨域资源共享 (CORS) 的内置支持，使您可以控制哪些域可以访问您的 API。

对于依赖 API 来获取和操作数据的现代 Web 应用程序来说，启用 CORS 至关重要。

例子：

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI()

origins = [
    "http://localhost",
    "http://localhost:8080",
    "https://example.com"
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

在此示例中，我们通过添加 CORSMiddleware 中间件为 FastAPI 应用启用 CORS。

allow_origins 参数指定允许访问 API 的域列表。

allow_credentials、allow_methods 和 allow_headers 参数配置额外的 CORS 设置。

测试、调试和部署

测试和调试是软件开发过程的重要部分。

FastAPI 提供内置的测试和调试支持，使您更容易确保
应用程序的质量和可靠性。

使用 FastAPI 进行测试的示例：

# tests/test_users.py
from fastapi.testclient import TestClient
from app.main import app

client = TestClient(app)

def test_create_user():
    user_data = {"username": "testuser", "email": "test@example.com", "password": "test123"}
    response = client.post("/users", json=user_data)
    assert response.status_code == 201
    assert response.json()["username"] == user_data["username"]
    assert response.json()["email"] == user_data["email"]

def test_get_users():
    response = client.get("/users")
    assert response.status_code == 200
    assert len(response.json()) >= 1

在此示例中，我们使用 FastAPI 的 TestClient 为 /users 端点创建两个测试用例。

test_create_user 函数测试新用户的创建，而 test_get_users 函数测试用户列表的检索。

使用交互式调试器进行调试

要在 FastAPI 中启用交互式调试器，您可以在使用 Uvicorn 运行应用程序时使用 --reload 和 --debug 标志：

uvicorn app.main:app --reload --debug

启用这些标志后，应用程序将在代码更改时自动重新加载，并且在发生未处理的异常时将激活交互式调试器。

部署和扩展注意事项

部署 FastAPI 应用程序时，必须考虑性能、可扩展性和安全性等因素。

部署和扩展 FastAPI 应用程序的一些最佳实践包括：

• 使用适合生产的 ASGI 服务器，例如 Gunicorn 或 Hypercorn。
• 配置像 Nginx 这样的反向代理来处理 SSL 终止、静态文件服务和请求路由。
• 使用像 systemd 或 supervisor 这样的进程管理器来管理和监控您的应用程序。
• 实施缓存和/或使用内容分发网络 (CDN) 来提高性能。
• 通过在负载均衡器后面运行多个实例来水平扩展您的应用程序。
• 使用 Gunicorn 和 Nginx 部署 FastAPI 应用程序 Gunicorn 和 Nginx 是在生产中部署 FastAPI 应用程序的热门选择。

Gunicorn 是一款适用于 UNIX 的 Python WSGI HTTP 服务器，而 Nginx 是一款高性能开源 Web 服务器和反向代理。Gunicorn
配置示例：

# gunicorn.conf.py
workers = 4
worker_class = "uvicorn.workers.UvicornWorker"

在这个例子中，我们创建一个 gunicorn.conf.py 文件来配置 Gunicorn 服务器。

我们将工作者数量设置为 4，并指定 UvicornWorker 类来处理 ASGI 应用程序。

Nginx 配置示例：

# nginx.conf
server {
    listen 80;
    server_name example.com;
    location / {
        include uwsgi_params;
        uwsgi_pass unix:/path/to/your/project/my_fastapi_project.sock;
    }
}

在这个例子中，我们创建一个 nginx.conf 文件来配置 Nginx 服务器。

我们设置服务器监听80端口，指定域名，配置/location为代理。

结论

本指南介绍了构建 FastAPI 应用程序的基本最佳实践。

通过设置和构建可扩展性项目、使用 Pydantic 进行数据验证、处理 HTTP 请求和响应、实现异常和错误处理、自定义中间件和 CORS 以及测试和调试应用程序，您可以创建健壮且可维护的 FastAPI 应用程序。

使用 Gunicorn 和 Nginx 部署您的应用程序可确保提高性能和可扩展性。

为了了解最新的 FastAPI 功能和最佳实践，请继续学习和参与 FastAPI 社区，探索开源项目，并尝试新的工具和技术。

遵循这些最佳实践将帮助您构建满足用户需求并支持您的开发目标的高质量 API。