第3章项目初始化

第3章：项目初始化——用Cookiecutter创建项目骨架

说实话，我见过太多团队在项目初期就栽了跟头。

不是目录结构乱成一锅粥，就是配置文件缺胳膊少腿。我自己刚带项目那会儿，也吃过这个亏——手动创建目录，结果漏了 tests/ 文件夹，CI 跑不起来，排查了半天。

后来我学乖了。用 Cookiecutter 吧，一劳永逸。

3.1 为什么选Cookiecutter？

Cookiecutter 是个命令行工具。它根据模板，自动生成项目骨架。

说白了，就是「项目脚手架生成器」。你写好模板，它帮你把目录、文件、配置一次性搞定。

核心优势：

一次定义，反复使用
团队统一规范，减少沟通成本
支持变量替换，灵活适配不同项目
纯 Python 实现，安装简单

我在团队里推行这套方案后，新人上手速度至少快了 30%。

3.2 安装Cookiecutter

先装工具。用 pip 就行：

pip install cookiecutter

嗯，这里要注意。如果你用的是 Python 3.10+，建议用 pipx 安装，避免污染全局环境：

pipx install cookiecutter

我个人习惯用 pipx。隔离干净，升级也方便。

3.3 创建项目骨架

假设我们要生成一个 Alpha 框架 的标准项目。模板我已经准备好了，放在 GitHub 上：

cookiecutter https://github.com/your-org/alpha-cookiecutter.git

运行后，它会问你几个问题：

参数	说明	示例值
`project_name`	项目名称	my-alpha-project
`author_name`	作者	Zhang San
`python_version`	Python 版本	3.11
`use_docker`	是否包含 Docker 配置	y

填完之后，项目就自动生成了。整个过程不到 10 秒。

小技巧： 如果你不想每次都手动输入，可以创建一个 cookiecutter.json 文件，把默认值写进去。这样直接 cookiecutter . 就能一键生成。

3.4 目录结构解析

生成后的项目长这样：

my-alpha-project/
├── .github/
│   └── workflows/
│       └── ci.yml
├── src/
│   └── alpha/
│       ├── __init__.py
│       ├── core.py
│       └── utils.py
├── tests/
│   ├── __init__.py
│   └── test_core.py
├── docs/
│   └── index.md
├── config/
│   ├── settings.py
│   └── logging.conf
├── scripts/
│   └── run.sh
├── .env.example
├── .gitignore
├── pyproject.toml
├── README.md
└── Makefile

我来逐个拆解一下。

3.4.1 `src/alpha/` —— 核心代码

所有业务逻辑都放在这里。为什么用 src/ 套一层？

我曾经踩过坑：直接把代码放在项目根目录，结果 import 的时候各种混乱。用 src/ 隔离后，包结构清晰多了。

core.py：框架核心逻辑
utils.py：工具函数
__init__.py：包初始化，可以暴露公共接口

3.4.2 `tests/` —— 测试代码

测试和源码一一对应。这是行业最佳实践。

你想想看，如果测试文件和源码混在一起，找起来多费劲？

我的原则： 每个 .py 文件，至少对应一个 test_*.py 文件。覆盖率低于 80% 的代码，我不会合并到主分支。

3.4.3 `config/` —— 配置文件

环境变量、日志配置、数据库连接……这些「环境相关」的东西，统一放这里。

注意：.env 文件不要提交到 Git。我们只提交 .env.example，里面写占位符。

3.4.4 `docs/` —— 文档

用 Markdown 写。配合 MkDocs 或 Sphinx，能自动生成漂亮的文档站。

我个人偏爱 MkDocs，配置简单，主题好看。

3.4.5 `scripts/` —— 脚本

部署脚本、数据迁移脚本、定时任务……这些「一次性或周期性」的操作，放这里。

别把它们塞进 src/，否则会污染业务代码。

3.4.6 根目录文件

文件	作用
`pyproject.toml`	项目元数据、依赖管理、构建配置
`Makefile`	常用命令快捷方式（如 `make test`）
`.gitignore`	Git 忽略规则
`README.md`	项目介绍、快速开始

警告： 不要手动修改 pyproject.toml 中的 version 字段。用 bumpversion 或 poetry version 自动管理版本号。我曾经手改过一次，结果版本号冲突，CI 发布失败……教训深刻。

3.5 核心逻辑流程图

下面这张图，展示了从模板到项目生成的完整流程：

流程很简单：模板仓库 → 用户输入 → 变量替换 → 生成项目。核心就是「模板 + 变量 = 项目」。

3.6 避坑指南

我曾经犯过的错：

模板里写死了路径，导致生成后目录不对。后来改用 cookiecutter.project_name 变量，问题解决。
忘记在 .gitignore 里排除 .env，结果密钥被提交到公开仓库。嗯，那晚我加班到凌晨三点。
模板中的 __init__.py 是空文件，但 Git 不跟踪空目录。记得在模板里加一个占位注释。

我的建议： 模板仓库也要做版本管理。每次更新模板后，用 cookiecutter 重新生成一个测试项目，验证无误再推送。

3.7 小结

Cookiecutter 不是什么黑科技。它就是一个「复制粘贴」的自动化工具。

但用好它，能让团队规范落地、新人快速上手、项目结构统一。说白了，就是省心。

我个人习惯把模板放在公司 GitLab 上，每个新项目都从模板生成。这样维护成本最低，一致性最高。

公众号：蓝海资料掘金营，微信 deep3321

📚 课程目录