1. 初始化虚拟环境

# 创建虚拟环境 python -m venv .venv # 激活环境 # macOS/Linux source .venv/bin/activate # Windows PowerShell .venv\Scripts\activate # 升级 pip pip install --upgrade pip

---

2. 创建目录结构

mkdir -p backend/app/{core,db,routers,schemas,services,tasks} mkdir -p backend/tests mkdir -p infra/compose

目录说明：

• backend/app/core → 配置、启动逻辑（settings、logging）

• backend/app/db → 数据库连接、会话、迁移

• backend/app/routers → 路由层（FastAPI APIRouter）

• backend/app/schemas → Pydantic 模型

• backend/app/services → 业务逻辑服务

• backend/app/tasks → 异步任务、celery/apscheduler

• backend/tests → 单元测试与集成测试

• infra/compose → docker-compose 配置文件、相关脚本

---

3. 顶层文件

在项目根目录创建：

README.md

# 项目名称 ## 开发环境 ### 初始化 ```bash python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate pip install --upgrade pip

运行开发环境

make dev

目录结构

• backend/app/core: 配置与启动

• backend/app/db: 数据库

• backend/app/routers: 路由

• backend/app/schemas: 数据模型

• backend/app/services: 服务层

• backend/app/tasks: 异步任务

• backend/tests: 测试

• infra/compose: docker-compose 配置

### `.env.example` ```dotenv # Application APP_NAME=MyApp APP_ENV=development APP_DEBUG=true # Database DB_USER=postgres DB_PASSWORD=postgres DB_HOST=localhost DB_PORT=5432 DB_NAME=myapp

pyproject.toml（推荐用 poetry/pdm）

[tool.poetry] name = "myapp" version = "0.1.0" description = "FastAPI backend project" authors = ["Your Name <you@example.com>"] [tool.poetry.dependencies] python = "^3.11" fastapi = "^0.111.0" uvicorn = {extras = ["standard"], version = "^0.30.0"} [tool.poetry.group.dev.dependencies] pytest = "^8.3.0" black = "^24.3.0" ruff = "^0.5.0" [build-system] requires = ["poetry-core"] build-backend = "poetry.core.masonry.api"

👉 如果不用 poetry，可以先放 requirements.txt：

fastapi>=0.111.0 uvicorn[standard]>=0.30.0 # dev pytest>=8.3.0 black>=24.3.0 ruff>=0.5.0

---

4. 开发脚本（推荐 Makefile）

Makefile

.PHONY: dev lint test dev: uvicorn backend.app.core.main:app --reload lint: ruff check backend black --check backend test: pytest -v

---

5. Git 初始化

git init git add . git commit -m "chore: initialize project structure and environment"

---

✅ 验收标准：

• .venv 存在并可激活

• 目录结构创建完成

• README.md、.env.example、pyproject.toml 或 requirements.txt 在位

• make dev 可以启动一个空的 FastAPI 应用