快速搭建Python项目（Vscode+uv+FastAPI）

前言

本来我是搞全栈开发的，后来微软落寞后原计划是只搞前端GIS开发，后台的包括数据处理的就不想再搞了，但现在时代太卷了，身边同事也偷偷的在学Python，于是自己摸索着学点儿，搜集了最新的资料，并咨询了下各个平台的AI，总结出了下面这一套流程，记录下来方便以后查阅，也希望能帮助到跟我一样要学Python的人。

项目技术栈

环节	主流工具	说明
Python 版本管理	uv	Rust 编写，极快，替代 pyenv
包管理 & 依赖	uv	替代 pip / poetry / pdm
项目配置	pyproject.toml	已全面取代 setup.py / requirements.txt
代码格式化	ruff format	替代 black
代码检查	ruff check	替代 flake8 + isort + pylint
类型检查	mypy / pyright	可选
测试	pytest	绝对主流
Git 钩子	pre-commit	提交前自动检查
CI/CD	GitHub Actions	最主流

项目搭建流程

安装 uv

bash 复制代码

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
# 验证安装
uv --version

初始化项目

bash 复制代码

# 创建项目（自动生成标准结构）
uv init ptgeo-service
cd ptgeo-service

调整目录结构

采用模块化架构设计，每个功能模块独立封装：

bash 复制代码

# 创建目录
mkdir src/app/api
mkdir src/app/config
mkdir src/app/core
mkdir src/app/modules/image
mkdir tests/api
# 创建文件
type nul > src\app\__init__.py
type nul > src\app\main.py
type nul > src\app\api\__init__.py
type nul > src\app\api\router.py
type nul > src\app\config\__init__.py
type nul > src\app\config\settings.py
type nul > src\app\core\__init__.py
type nul > src\app\core\config.py
type nul > src\app\modules\image\__init__.py
type nul > src\app\modules\image\router.py
type nul > src\app\modules\image\schemas.py
type nul > src\app\modules\image\services.py
type nul > tests\__init__.py
type nul > tests\api\__init__.py
type nul > tests\conftest.py
type nul > tests\test_main.py
type nul > tests\api\test_image.py

项目结构说明：

复制代码

ptgeo-service/
├── src/
│   └── app/
│       ├── __init__.py
│       ├── main.py              # FastAPI 应用入口
│       ├── api/
│       │   ├── __init__.py
│       │   └── router.py        # 路由注册中心
│       ├── config/
│       │   ├── __init__.py
│       │   └── settings.py      # 环境配置（自动读取 .env）
│       ├── core/
│       │   ├── __init__.py
│       │   └── config.py        # 核心配置
│       └── modules/             # 功能模块目录
│           └── image/           # 基础影像模块
│               ├── __init__.py
│               ├── router.py    # 模块路由定义
│               ├── schemas.py   # Pydantic 数据模型
│               └── services.py  # 业务逻辑层
├── tests/
│   ├── __init__.py
│   ├── conftest.py              # pytest fixtures
│   ├── test_main.py
│   └── api/
│       ├── __init__.py
│       └── test_image.py        # 影像模块测试
├── .env                         # 环境变量配置
├── .python-version
├── .gitignore
├── pyproject.toml               # 项目配置（依赖、脚本、工具配置）
└── uv.lock                      # 依赖锁文件

模块职责划分：

目录/文件	职责	说明
`api/router.py`	路由注册中心	汇总所有模块路由
`config/`	配置管理	环境变量、应用设置
`core/`	核心工具	公共工具函数、基础配置
`modules/`	功能模块	按业务划分的独立模块
`modules/image/router.py`	模块路由	定义模块的 API 端点
`modules/image/schemas.py`	数据模型	Pydantic 请求/响应模型
`modules/image/services.py`	业务逻辑	核心数据处理逻辑

新增模块流程：

在 modules/ 下创建新目录（如 modules/analysis/）
添加 router.py、schemas.py、services.py
在 api/router.py 中注册新模块路由

安装依赖

配置国内镜像加速：

toml 复制代码

[pyproject.toml]
[[tool.uv.index]]
name = "pypi"
url = "https://pypi.tuna.tsinghua.edu.cn/simple/"
default = true

安装核心依赖：

bash 复制代码

# 核心依赖
uv add fastapi
uv add "uvicorn[standard]"       # ASGI 服务器

# 开发依赖
uv add --dev pytest
uv add --dev httpx               # 异步 HTTP 客户端，用于测试
uv add --dev ruff
uv add --dev mypy
uv add --dev pre-commit
uv add --dev pytest-asyncio      # 异步测试支持

可选扩展依赖：

bash 复制代码

# 数据库
uv add sqlalchemy asyncpg aiosqlite

# 数据验证 & 设置
uv add pydantic pydantic-settings

# JWT 认证
uv add python-jose[cryptography] passlib[bcrypt] python-multipart

# Redis
uv add redis

# 日志
uv add loguru

# 数据库迁移
uv add alembic

# 环境变量
uv add python-dotenv

配置 pyproject.toml

项目核心配置文件：

toml 复制代码

[project]
name = "fastapi-demo"
version = "0.1.0"
description = "A modern FastAPI project"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
    "fastapi",
    "uvicorn[standard]",
]
[project.scripts]
dev = "app.main:run_dev"
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[tool.hatch.build.targets.wheel]
packages = ["src/app"]
# ===== Ruff =====
[tool.ruff]
target-version = "py311"
line-length = 88
src = ["src", "tests"]
[tool.ruff.lint]
select = ["E", "W", "F", "I", "B", "C4", "UP", "SIM", "ARG"]
ignore = ["E501"]
[tool.ruff.lint.isort]
known-first-party = ["app"]
# ===== Pytest =====
[tool.pytest.ini_options]
testpaths = ["tests"]
pythonpath = ["src"]
asyncio_mode = "auto"
# ===== Mypy =====
[tool.mypy]
python_version = "3.11"
strict = true
warn_return_any = true
warn_unused_configs = true

运行项目

开发模式启动：

bash 复制代码

uv run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

通过脚本启动：

bash 复制代码

uv run dev

直接运行：

bash 复制代码

python -m app.main

跑测试

bash 复制代码

# 跑全部测试
uv run pytest -v
# 带覆盖率
uv run pytest --cov=app --cov-report=term-missing
# 只跑某个文件
uv run pytest tests/test_main.py -v
# 看 print 输出
uv run pytest -v -s
# 跑单个测试用例
uv run pytest tests/test_main.py::test_function -v
# 生成覆盖率报告（HTML格式）
uv run pytest --cov=app --cov-report=html

代码质量检查

bash 复制代码

# 格式化
uv run ruff format src tests
# 检查 + 自动修复
uv run ruff check --fix src tests
# 类型检查（可选）
uv run mypy src
# 安全检查（依赖漏洞扫描）
uv run safety check
# 代码复杂度分析
uv run radon cc src -a
# 代码重复率检查
uv run flake8 --flake8-find-duplicated-code src

uv完整命令速查表

bash 复制代码

# 🏗️ 项目管理
uv init <name>              # 创建项目
uv add <package>            # 添加依赖
uv add --dev <package>      # 添加开发依赖
uv remove <package>         # 移除依赖
uv sync                     # 同步依赖
uv lock                     # 更新锁文件
uv show                     # 显示项目依赖树

# 🚀 运行
uv run uvicorn app.main:app --reload   # 开发模式
uv run dev                              # 脚本入口
uv run python src/app/main.py           # 直接运行
uv run gunicorn app.main:app -w 4       # 生产模式

# 🧪 测试
uv run pytest -v                        # 跑测试
uv run pytest --cov=app                 # 带覆盖率
uv run pytest -x                        # 遇到失败立即停止
uv run pytest --lf                      # 只跑上次失败的测试
uv run tox                              # 多环境测试

# 🔍 代码质量
uv run ruff format src tests            # 格式化
uv run ruff check --fix src tests       # 检查修复
uv run mypy src                         # 类型检查
uv run pre-commit run --all-files       # 全量检查
uv run bandit -r src                    # 安全扫描
uv run pylint src                       # 代码规范检查

# 📦 构建 & 发布
uv build                                # 构建
uv publish                              # 发布到 PyPI
uv docker-build                         # 构建Docker镜像
uv docker-push                          # 推送Docker镜像
uv docs-build                           # 构建文档