使用 uv 管理 Python + FastAPI 项目依赖项

安装 Uv

uv 是一个快速的 Python 包管理器，可以用来管理项目依赖。安装方式有多种：

使用脚本 (推荐): 在终端运行以下命令：
shell 复制代码
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```
这个命令会自动下载并安装 uv。
使用 pip: 如果你的环境中有 pip，也可以这样安装：
shell 复制代码
```
pip install uv
```
使用 pipx: 如果使用 pipx 管理工具，可以使用下面的命令:
shell 复制代码
```
pipx install uv
```

初始化项目

创建项目目录: 首先，创建一个新的文件夹作为你的项目目录。
初始化: 在项目目录中，运行以下命令来初始化项目并添加 FastAPI 作为依赖:
shell 复制代码
```
uv init && uv add "fastapi>=0.112"
```
这条命令会做两件事：
- uv init: 创建一个 pyproject.toml 文件，这个文件是项目的配置文件，用来记录项目的信息和依赖项。
- uv add "fastapi>=0.112": 添加 FastAPI 作为项目的依赖，并且指定版本大于等于 0.112。
查看 pyproject.toml: 打开 pyproject.toml 文件，你会看到类似下面的内容：
toml 复制代码
```
[project]
name = "my-fastapi-project"  # 项目名称
version = "0.1.0"           # 项目版本
description = "A simple FastAPI project" #项目描述
readme = "README.md"        # README 文件
dependencies = ["fastapi>=0.112"] # 项目依赖
```
uv 会根据 pyproject.toml 文件创建一个锁文件 (例如 uv.lock)，这个文件记录了所有依赖项的具体版本，确保在不同的电脑上，项目使用的依赖版本都是一样的，避免出现兼容性问题。

项目结构示例

一个典型的 FastAPI 项目结构可能如下所示：

csharp 复制代码

my-fastapi-project/    # 项目根目录
├── app/               # 存放项目代码
│   ├── __init__.py
│   ├── main.py        # 主程序入口
│   ├── dependencies.py# 依赖项定义
│   ├── routers/       # 存放路由
│   │   ├── __init__.py
│   │   ├── items.py   # 商品相关路由
│   │   └── users.py   # 用户相关路由
│   └── internal/      # 内部模块
│       ├── __init__.py
│       └── admin.py   # 管理员相关代码
├── pyproject.toml   # 项目配置文件
└── README.md          # 说明文件

如果想使用 uv 管理这种结构的程序，可以在 my-fastapi-project 目录下运行：

shell 复制代码

uv init --app

然后添加 FastAPI 依赖和额外的标准配置:

shell 复制代码

uv add fastapi --extra standard

这会在 pyproject.toml 文件中添加 FastAPI 依赖和标准配置。

运行 FastAPI 应用

使用下面的命令来运行 FastAPI 应用：

shell 复制代码

uv run fastapi dev

uv run 命令会自动完成以下步骤：

解析 pyproject.toml 文件，确定项目依赖。
创建一个虚拟环境 (如果还没有创建)。
在虚拟环境中安装所有依赖。
运行指定的命令 (这里是 fastapi dev)。

区分开发和生产环境

在实际开发中，我们可能需要在开发环境中使用一些额外的工具，比如调试器、测试框架等。可以使用 uv 的分组功能来区分不同环境的依赖。

例如，安装 pandas 到开发环境，安装 requests 到生产环境：

shell 复制代码

uv add --group dev pandas
uv add --group production requests

安装完成后，uv.lock 文件会自动记录每个包及其依赖。

main.py 示例

下面是一个简单的 main.py 示例，它依赖于 requests 和 rich 两个库：

python 复制代码

# app/main.py
import requests
from rich.pretty import pprint

resp = requests.get("https://www.baidu.com")
data = {"title": "hello world"}
pprint(data)

可以通过 uv add 命令自动将依赖声明嵌入到脚本中：

shell 复制代码

uv add --script app/main.py "requests<3" "rich"

然后，可以通过 uv run app/main.py 在隔离环境中执行脚本并自动安装依赖。

依赖注入

FastAPI 的一个重要特性是依赖注入，它允许你声明一些函数，这些函数可以在处理请求之前被调用，并将结果传递给你的路由函数。

python 复制代码

# app/dependencies.py
from typing import Union
from fastapi import Depends

async def common_parameters(
    q: Union[str, None] = None, skip: int = 0, limit: int = 100
):
    """
    通用查询参数依赖
    """
    return {"q": q, "skip": skip, "limit": limit}

python 复制代码

# app/main.py
from fastapi import FastAPI, Depends
from .dependencies import common_parameters

app = FastAPI()

@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

在这个例子中，common_parameters 函数就是一个依赖，它接收三个查询参数：q、skip 和 limit。read_items 和 read_users 两个路由函数都依赖于 common_parameters，FastAPI 会自动调用 common_parameters 函数，并将结果传递给这两个路由函数。

总结

使用 uv 可以更方便、更快速地管理 Python + FastAPI 项目的依赖。通过 uv init 初始化项目，uv add 添加依赖，uv run 运行项目，可以有效地管理项目的依赖关系，保证项目在不同环境中的一致性。同时，uv 提供的分组功能可以方便地区分开发环境和生产环境的依赖，满足不同的需求。依赖注入是 FastAPI 的一个重要特性，可以帮助我们更好地组织代码，提高代码的可维护性和可测试性。