软件开发目录规范
良好的目录结构与规范的编码风格同等重要，能显著提高项目的可读性和可维护性。本篇介绍 Python 项目的推荐目录结构以及现代工具链。
传统目录结构
适合中小型脚本/应用项目：
myapp/
├── core/ # 核心业务逻辑
│ └── engine.py
├── api/ # 对外接口层
│ └── routes.py
├── db/ # 数据库操作
│ └── models.py
├── lib/ # 内部公共库
│ └── utils.py
├── conf/ # 配置文件
│ └── settings.py
├── tests/ # 测试代码
│ ├── __init__.py
│ └── test_engine.py
├── run.py # 启动入口
├── requirements.txt # 依赖列表
└── README.md # 项目说明core/：存放业务逻辑，不包含 I/O 和网络代码，方便单元测试。api/：对外接口，调用core/中的逻辑。db/：数据库 ORM 模型和查询，与业务逻辑解耦。lib/：工具函数、装饰器、自定义异常等跨模块复用代码。conf/：集中存放所有配置，区分 dev/prod 环境。run.py：项目根目录的启动脚本，运行时会将其所在路径加入sys.path。
现代 Python 包结构（src 布局）
推荐用于正式发布的库或需要 pip install 的项目：
mypackage/
├── src/
│ └── mypackage/ # 包代码在 src/ 下，防止意外导入本地代码
│ ├── __init__.py
│ ├── core.py
│ └── utils.py
├── tests/
│ ├── conftest.py
│ └── test_core.py
├── pyproject.toml # 现代项目配置（替代 setup.py）
├── README.md
└── .gitignorepyproject.toml — 现代项目配置
Python 3.11+ 推荐用 pyproject.toml 统一管理项目元数据、依赖和工具配置：
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "mypackage"
version = "0.1.0"
description = "一个示例 Python 包"
readme = "README.md"
requires-python = ">=3.11"
dependencies = [
"requests>=2.31",
"pydantic>=2.0",
]
[project.optional-dependencies]
dev = ["pytest>=8.0", "ruff>=0.4", "mypy>=1.9"]
[tool.ruff]
line-length = 88
[tool.ruff.lint]
select = ["E", "F", "I"] # pycodestyle, pyflakes, isort
[tool.mypy]
python_version = "3.12"
strict = truerequirements.txt
用于记录依赖，方便快速复现环境：
requests==2.31.0
pydantic==2.7.0
fastapi==0.111.0
uvicorn==0.29.0生成方式：
# 传统方式
pip freeze > requirements.txt
# 推荐：使用 uv（更快的 pip 替代品）
uv pip freeze > requirements.txt现代工具链
| 工具 | 用途 |
|---|---|
uv | 极速的包管理器和虚拟环境工具（Rust 实现） |
ruff | 极速的代码检查和格式化工具（替代 flake8 + isort + black） |
mypy / pyright | 静态类型检查 |
pytest | 测试框架 |
hatch / flit | 包构建工具 |
uv 快速上手
# 安装 uv
pip install uv
# 创建虚拟环境并安装依赖
uv venv
uv pip install -r requirements.txt
# 运行项目
uv run python run.py
# 添加依赖
uv add requests关键约定
- 一个项目一个虚拟环境，避免全局依赖污染。
- 配置与代码分离：敏感信息（密钥、数据库密码）通过环境变量或
.env文件注入，绝不提交到代码库。 __init__.py：包目录的标识文件，可为空，也可导出公共接口。if __name__ == "__main__":：将脚本逻辑放在此守卫下，使模块既可被导入也可直接运行。- README.md：每个项目必须包含：功能说明、安装步骤、快速上手示例、目录结构说明。
最后更新于