主题
通用 Python 项目骨架
适合大多数应用型项目、服务型项目、脚本工具项目，也可以轻微调整后用于 Python 库项目
Python 通用项目骨架说明文档
1. 推荐目录结构示意图
文本
project/
├── src/
│ └── your_package/
│ ├── __init__.py
│ ├── main.py
│ ├── core/
│ │ ├── __init__.py
│ │ └── service.py
│ ├── api/
│ │ ├── __init__.py
│ │ └── routes.py
│ ├── models/
│ │ ├── __init__.py
│ │ └── user.py
│ ├── utils/
│ │ ├── __init__.py
│ │ └── helpers.py
│ └── config.py
│
├── tests/
│ ├── __init__.py
│ ├── test_main.py
│ ├── test_service.py
│ └── fixtures/
│ └── sample_data.json
│
├── scripts/
│ ├── dev.sh
│ ├── lint.sh
│ ├── test.sh
│ └── release.sh
│
├── config/
│ ├── default.toml
│ ├── development.toml
│ ├── production.toml
│ └── logging.yaml
│
├── docs/
│ ├── index.md
│ ├── architecture.md
│ ├── development.md
│ └── deployment.md
│
├── .github/
│ └── workflows/
│ └── ci.yml
│
├── .env.example
├── .gitignore
├── .python-version
├── AGENTS.md
├── Makefile
├── pyproject.toml
├── README.md
├── requirements.txt
├── requirements-dev.txt
└── requirements.lock.txt2. 本地生成目录，不应提交到 Git
这些文件或目录可以存在于项目根目录，但不属于仓库骨架的一部分：
文本
project/
├── .venv/
├── .env
├── .pytest_cache/
├── .ruff_cache/
├── __pycache__/
├── .coverage
├── htmlcov/
├── dist/
├── build/
└── *.egg-info/它们应该写进 .gitignore。
3. 各目录与文件说明
src/
项目源码目录。
推荐使用 src 布局，而不是把业务代码直接放在项目根目录。这样可以避免本地开发时错误导入根目录下的代码。
示例：
文本
src/
└── your_package/
├── __init__.py
├── main.py
├── core/
├── api/
├── models/
└── utils/其中：
| 路径 | 说明 |
|---|---|
your_package/ | 项目的主 Python 包名 |
main.py | 应用入口，可用于 CLI、服务启动或主流程 |
core/ | 核心业务逻辑 |
api/ | API 路由、接口层代码 |
models/ | 数据模型、领域模型、ORM 模型 |
utils/ | 工具函数、通用辅助模块 |
config.py | 配置读取与解析逻辑 |
tests/
测试目录。
文本
tests/
├── test_main.py
├── test_service.py
└── fixtures/
└── sample_data.json建议规则：
| 项 | 建议 |
|---|---|
| 测试框架 | pytest |
| 测试文件命名 | test_*.py |
| 测试函数命名 | test_* |
| 测试数据 | 放入 tests/fixtures/ |
| 覆盖率 | 可使用 pytest-cov |
scripts/
项目辅助脚本目录。
文本
scripts/
├── dev.sh
├── lint.sh
├── test.sh
└── release.sh常见用途：
| 脚本 | 说明 |
|---|---|
dev.sh | 启动开发环境 |
lint.sh | 执行代码检查 |
test.sh | 执行测试 |
release.sh | 发布或打包流程 |
如果项目简单，也可以只用 Makefile，不一定需要 scripts/。
config/
配置文件目录。
文本
config/
├── default.toml
├── development.toml
├── production.toml
└── logging.yaml注意：
| 文件 | 是否提交 | 说明 |
|---|---|---|
| 默认配置 | 是 | 可以提交 |
| 环境模板配置 | 是 | 可以提交 |
| 密钥、Token、密码 | 否 | 不应提交 |
.env | 否 | 本地私密配置 |
.env.example | 是 | 环境变量示例 |
docs/
项目文档目录。
文本
docs/
├── index.md
├── architecture.md
├── development.md
└── deployment.md推荐至少包含：
| 文档 | 说明 |
|---|---|
index.md | 文档首页 |
architecture.md | 架构说明 |
development.md | 开发说明 |
deployment.md | 部署说明 |
小项目可以只保留 README.md，不用单独建 docs/。
.github/workflows/
GitHub Actions 自动化目录。
文本
.github/
└── workflows/
└── ci.yml常见用途：
| 文件 | 说明 |
|---|---|
ci.yml | 自动测试、Lint、构建 |
release.yml | 自动发布 |
docs.yml | 自动构建文档 |
如果项目不用 GitHub，可以没有这个目录。
4. 根目录核心文件说明
pyproject.toml
现代 Python 项目的核心配置文件。
建议把这些工具配置集中放在里面：
文本
[project]
[build-system]
[tool.pytest.ini_options]
[tool.ruff]
[tool.mypy]
[tool.coverage]它可以统一管理：
| 内容 | 说明 |
|---|---|
| 项目元数据 | 名称、版本、作者、描述 |
| 构建系统 | setuptools、hatchling、poetry、uv 等 |
| 依赖声明 | 运行依赖、可选依赖 |
| 测试配置 | pytest |
| Lint 配置 | ruff |
| 类型检查 | mypy、pyright |
| 覆盖率配置 | coverage |
requirements.txt
运行依赖文件。
适合应用型项目，例如：
文本
fastapi
uvicorn
pydantic
requests如果项目依赖已经完全放进 pyproject.toml，这个文件可以由工具导出，而不是手写维护。
requirements-dev.txt
开发依赖文件。
例如：
文本
pytest
pytest-cov
ruff
mypy
pre-commit用于开发、测试、格式化、类型检查。
requirements.lock.txt
锁定依赖版本的文件。
例如：
文本
fastapi==0.115.0
uvicorn==0.30.6
pydantic==2.8.2作用是保证不同机器、不同环境安装到一致的依赖版本。
如果使用 uv、poetry、pdm 等工具，也可以换成：
文本
uv.lock
poetry.lock
pdm.lock
pylock.toml.env.example
环境变量模板。
应该提交到仓库。
示例：
.env
APP_ENV=development
APP_DEBUG=true
DATABASE_URL=postgresql://user:password@localhost:5432/app
REDIS_URL=redis://localhost:6379/0
SECRET_KEY=change-me注意：这里可以放假值、示例值，但不能放真实密钥。
.env
本地真实环境变量。
不应提交。
示例：
.env
APP_ENV=development
APP_DEBUG=true
DATABASE_URL=postgresql://real_user:real_password@localhost:5432/app
SECRET_KEY=real-secret.gitignore
推荐内容：
.gitignore
#### Python cache
__pycache__/
*.py[cod]
*$py.class
#### Virtual environments
.venv/
venv/
env/
#### Environment variables
.env
.env.*
!.env.example
#### Test / coverage
.pytest_cache/
.coverage
htmlcov/
#### Ruff
.ruff_cache/
#### Build artifacts
build/
dist/
*.egg-info/
#### IDE
.vscode/
.idea/
#### OS files
.DS_Store
Thumbs.db
#### Logs
*.log
logs/.python-version
用于声明项目推荐 Python 版本。
示例：
文本
3.12适合团队统一 Python 版本，尤其是使用 pyenv、uv 等工具时。
Makefile
统一开发命令入口。
示例：
Makefile
.PHONY: install dev test lint format clean
install:
pip install -r requirements.txt
dev:
pip install -r requirements-dev.txt
test:
pytest
lint:
ruff check src tests
format:
ruff format src tests
clean:
rm -rf .pytest_cache .ruff_cache .coverage htmlcov dist build这样团队成员可以直接执行：
Bash
make install
make dev
make test
make lint
make format
make cleanREADME.md
项目入口说明文档。
建议包含：
文本
#### Project Name
##### Introduction
项目简介。
##### Features
核心功能。
##### Requirements
运行要求。
##### Installation
安装方法。
##### Usage
使用方法。
##### Development
开发说明。
##### Testing
测试说明。
##### Deployment
部署说明。
##### License
许可证。AGENTS.md
给 AI 编程助手、自动化代理或协作工具看的项目说明。
不是 Python 官方标准文件，但现在越来越常见。
建议内容包括：
文本
#### AGENTS.md
##### Project Overview
本项目的目标、技术栈、代码边界。
##### Coding Rules
代码风格、命名规范、禁止事项。
##### Test Commands
如何运行测试。
##### Lint Commands
如何运行代码检查。
##### Project Structure
目录说明。
##### Notes
开发注意事项。5. 推荐的最小可用版本
如果项目不复杂，可以使用这个精简版：
文本
project/
├── src/
│ └── your_package/
│ ├── __init__.py
│ └── main.py
├── tests/
│ └── test_main.py
├── .env.example
├── .gitignore
├── .python-version
├── Makefile
├── pyproject.toml
├── README.md
├── requirements.txt
└── requirements-dev.txt这个版本适合：
| 类型 | 是否适合 |
|---|---|
| 小型工具项目 | 是 |
| 内部脚本项目 | 是 |
| FastAPI 小服务 | 是 |
| 数据处理项目 | 是 |
| 命令行工具 | 是 |
| 大型平台项目 | 需要扩展 |
6. 推荐的完整企业/团队版本
如果是团队协作、后端服务、AI 应用、数据平台或长期维护项目，推荐使用完整版本：
文本
project/
├── src/
│ └── your_package/
│ ├── __init__.py
│ ├── main.py
│ ├── core/
│ ├── api/
│ ├── models/
│ ├── services/
│ ├── repositories/
│ ├── schemas/
│ ├── utils/
│ └── config.py
├── tests/
│ ├── unit/
│ ├── integration/
│ └── fixtures/
├── scripts/
├── config/
├── docs/
├── .github/
│ └── workflows/
├── .env.example
├── .gitignore
├── .python-version
├── AGENTS.md
├── Makefile
├── pyproject.toml
├── README.md
├── requirements.txt
├── requirements-dev.txt
└── requirements.lock.txt额外模块说明：
| 目录 | 说明 |
|---|---|
services/ | 应用服务层，组织业务流程 |
repositories/ | 数据访问层，封装数据库、外部存储 |
schemas/ | 请求、响应、校验模型 |
tests/unit/ | 单元测试 |
tests/integration/ | 集成测试 |
.github/workflows/ | CI/CD 自动化 |
7. 最终推荐原则
这套骨架遵循几个原则：
| 原则 | 说明 |
|---|---|
| 源码隔离 | 业务代码统一放入 src/ |
| 测试独立 | 测试代码统一放入 tests/ |
| 配置分层 | 示例配置进仓库，真实密钥不进仓库 |
| 工具集中 | 主要工具配置尽量放入 pyproject.toml |
| 本地文件不提交 | .venv/、.env、缓存目录全部忽略 |
| 命令统一 | 用 Makefile 或脚本统一开发命令 |
| 文档随仓库维护 | README.md 负责入口说明，docs/ 负责详细文档 |
| 可扩展 | 小项目可精简，大项目可扩展 |
8. 最终结论
这份项目骨架可以作为通用 Python 仓库模板：
文本
project/
├── src/
├── tests/
├── scripts/
├── config/
├── docs/
├── .github/
├── .env.example
├── .gitignore
├── .python-version
├── AGENTS.md
├── Makefile
├── pyproject.toml
├── README.md
├── requirements.txt
├── requirements-dev.txt
└── requirements.lock.txt其中：
文本
.venv/
.env
.pytest_cache/
.ruff_cache/
__pycache__/只属于本地环境，不应进入仓库。
这就是一个比较稳妥、通用、可维护的 Python 项目根目录设计。
本文改编自开源项目 vibe-coding-cn（MIT 许可，© 2025 Nicolas Zullo, tukuaiai, 123olp），AiCodeCat 做了删减与本地化。许可全文见 开源许可。