随着 pyproject.toml 成为现代 Python 项目的标准配置文件，加上 uv 作为极速、全能的依赖管理与执行工具，Python 打包与项目结构变得比以往更简单、清晰。

本篇文章展示一个精炼但可用于生产的示例项目结构，包括：

• 清晰的 package 目录
• 可运行的 Python 脚本
• 一个 FastAPI 服务
• 使用 uv 完成安装、运行与构建

---

📁 推荐项目结构

myproject/
├─ src/
│  └─ myproject/
│     ├─ __init__.py
│     ├─ core.py
│     ├─ script.py
│     └─ api.py
├─ tests/
│  └─ test_core.py
├─ pyproject.toml
└─ README.md

两个可运行组件：

• script.py → 简单的命令行脚本
• api.py → 一个最小化 FastAPI 服务

---

⚙️ 最小可用的 pyproject.toml

[project]
name = "myproject"
version = "0.1.0"
description = "一个包含脚本与 FastAPI 服务的简单 Python 示例项目。"
readme = "README.md"
requires-python = ">=3.9"
authors = [
  { name="Your Name", email="you@example.com" }
]

dependencies = [
  "fastapi",
  "uvicorn"
]

[project.optional-dependencies]
dev = ["pytest"]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project.scripts]
myproject-script = "myproject.script:main"

[project.entry-points."uvicorn.run"]
myproject-api = "myproject.api:app"

---

📝 示例脚本

src/myproject/script.py

def main():
    print("Hello from my project script!")

if __name__ == "__main__":
    main()

创建Python 虚拟环境

uv venv --seed .venv

使用 uv 运行脚本

uv run myproject-script

或直接运行源码：

uv run src/myproject/script.py

---

🚀 最小 FastAPI 服务

src/myproject/api.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def root():
    return {"message": "Hello from FastAPI!"}

使用 uv 运行 API 服务

uv run uvicorn myproject.api:app --reload

或使用我们定义的 entry point：

uv run uvicorn myproject-api

---

🧪 运行测试

uv run pytest

---

🧱 安装依赖

uv pip install -e .[dev]

---

🏗️ 构建与发布

构建：

uv build

发布：

uv publish

---

🎯 总结

使用 pyproject.toml + uv 的好处

• 清晰的 Python 包结构
• 快速运行脚本（uv run）
• 简洁的 FastAPI 服务入口
• 更简单、可复现的依赖管理
• 从开发到发布只需一个工具