Skip to content

python-project-skeleton.md

Latest commit

 

History

History
694 lines (520 loc) · 13 KB

python-project-skeleton.md

File metadata and controls

694 lines (520 loc) · 13 KB

通用 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.txt
2. 本地生成目录，不应提交到 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

环境变量模板。

应该提交到仓库。

示例：

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

本地真实环境变量。

不应提交。

示例：

APP_ENV=development
APP_DEBUG=true
DATABASE_URL=postgresql://real_user:real_password@localhost:5432/app
SECRET_KEY=real-secret
.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

统一开发命令入口。

示例：

.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

这样团队成员可以直接执行：

make install
make dev
make test
make lint
make format
make clean
README.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 项目根目录设计。