将 uv 与 FastAPI 结合使用

FastAPI 是一款现代的高性能 Python 网络框架。你可以使用 uv 来管理你的 FastAPI 项目，包括安装依赖项、管理环境、运行 FastAPI 应用程序等。

注意

你可以在 uv-fastapi-example 代码仓库中查看本指南的源代码。

迁移现有 FastAPI 项目

例如，以 FastAPI 文档中定义的示例应用程序为例，其结构如下：

project
└── app
    ├── __init__.py
    ├── main.py
    ├── dependencies.py
    ├── routers
    │   ├── __init__.py
    │   ├── items.py
    │   └── users.py
    └── internal
        ├── __init__.py
        └── admin.py

要在该应用程序中使用 uv，在 project 目录内运行：

$ uv init --app

这将创建一个具有应用程序布局的项目以及一个 pyproject.toml 文件。

然后，添加对 FastAPI 的依赖：

$ uv add fastapi --extra standard

此时，你应该拥有以下结构：

project
├── pyproject.toml
└── app
    ├── __init__.py
    ├── main.py
    ├── dependencies.py
    ├── routers
    │   ├── __init__.py
    │   ├── items.py
    │   └── users.py
    └── internal
        ├── __init__.py
        └── admin.py

pyproject.toml 文件的内容应如下所示：

pyproject.toml

[project]
name = "uv-fastapi-example"
version = "0.1.0"
description = "FastAPI project"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "fastapi[standard]",
]

从这一步开始，你可以使用以下命令运行 FastAPI 应用程序：

$ uv run fastapi dev

uv run 将自动解析并锁定项目依赖项（即在 pyproject.toml 旁边创建一个 uv.lock），创建一个虚拟环境，并在该环境中运行命令。

在 Web 浏览器中打开 http://127.0.0.1:8000/?token=jessica 来测试应用程序。

部署

要使用 Docker 部署 FastAPI 应用程序，可以使用以下 Dockerfile：

Dockerfile

FROM python:3.12-slim

# 安装 uv。
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

将应用程序复制到容器中。

COPY . /app

安装应用程序依赖项。

WORKDIR /app RUN uv sync --frozen --no-cache

运行应用程序。

CMD ["/app/.venv/bin/fastapi", "run", "app/main.py", "--port", "80", "--host", "0.0.0.0"]

使用以下命令构建 Docker 镜像：

```console
$ docker build -t fastapi-app .

使用以下命令在本地运行 Docker 容器：

$ docker run -p 8000:80 fastapi-app

在浏览器中访问 http://127.0.0.1:8000/?token=jessica ，验证应用程序是否正常运行。

Tip

有关在 Docker 中使用 uv 的更多信息，请参阅 Docker 指南。