项目结构、配置与发布

代码写完了，能跑了，但这只是开始。一个正经项目还要考虑：目录怎么组织、配置放哪、怎么打包、怎么部署。这一篇把项目工程化讲清楚——从小脚本走向正式项目的分水岭。

标准项目结构

一个 Python 项目的推荐布局：

myproject/
├── src/
│   └── myproject/          # 主代码包（包名和项目名一致）
│       ├── __init__.py
│       ├── app.py          # 入口
│       ├── config.py       # 配置
│       ├── db.py           # 数据库
│       └── utils.py        # 工具函数
├── tests/                  # 测试（和 src 对应）
│   ├── test_app.py
│   └── test_db.py
├── scripts/                # 一次性脚本（数据迁移等）
├── data/                   # 数据文件（不进 git）
├── docs/                   # 文档
├── requirements.txt        # 依赖清单
├── README.md               # 项目说明
├── .gitignore              # git 忽略规则
└── .env                    # 环境变量（敏感，不进 git！）

要点：

• src 布局：代码放 src/ 里，避免”import 路径混乱”问题
• 测试和代码分离：tests/ 目录，一眼能找到
• 入口清晰：一个 main 入口（app.py 或 main.py），别到处是入口

配置管理：环境变量

配置（数据库密码、API key、端口）不能写死在代码里——代码要进 git，密码不能进。用环境变量：

# config.py
import os

DB_HOST = os.getenv("DB_HOST", "127.0.0.1")       # 带默认值
DB_PORT = int(os.getenv("DB_PORT", "3306"))
API_KEY = os.getenv("API_KEY")                    # 没默认值，必须设置
DEBUG = os.getenv("DEBUG", "false").lower() == "true"

运行前设置：

# Linux/macOS
export API_KEY=sk-xxxx
python app.py

# 或写进 .env 文件（python-dotenv 自动加载）
# pip install python-dotenv
from dotenv import load_dotenv
load_dotenv()      # 自动读 .env 文件

# .env（绝不提交进 git！）
API_KEY=sk-xxxx
DB_PASSWORD=secret

铁律：密码和密钥永远不进代码、不进 git。.env 写进 .gitignore。

README：项目的脸面

一个好 README 让”三个月后的自己”和同事快速上手：

# 南山记账本

一个命令行记账工具，支持分类统计和 CSV 导出。

## 安装

pip install -r requirements.txt

## 使用

python app.py

## 测试

pytest

## 配置

环境变量：DB_PATH（默认 ./ledger.db）

至少包含：项目是干什么的、怎么装、怎么跑、怎么测。

git：版本管理基础

git 是每个程序员的必备技能，先记住最常用的几个命令：

# 初始化仓库（项目目录里执行一次）
git init

# 查看状态：改了哪些文件
git status

# 暂存 + 提交（提交信息写清楚干了啥）
git add .
git commit -m "添加记账功能"

# 查看历史
git log --oneline

# 回退到上一个版本（紧急救命用）
git reset --hard HEAD~1

# 分支：开新分支干活，干完合并
git branch feature-login
git checkout feature-login
# ...改代码...
git add .
git commit -m "实现登录"
git checkout main
git merge feature-login

日常流程就三件事：改代码 → git add → git commit。提交频繁点，提交信息写清楚，这就是版本管理。

.gitignore 至少写这些：

venv/
__pycache__/
*.pyc
.env
data/
*.db

打包：让项目能安装

项目要给别人用（或装到别的环境），写个 pyproject.toml：

[build-system]
requires = ["setuptools"]
build-backend = "setuptools.build_meta"

[project]
name = "myproject"
version = "0.1.0"
description = "南山记账本"
requires-python = ">=3.9"
dependencies = ["requests>=2.20"]

[project.scripts]
ledger = "myproject.app:main"     # 装完就有 ledger 命令

# 本地安装（开发模式：改代码立即生效）
pip install -e .

# 发布到 PyPI（供全世界安装）
pip install build
python -m build
# 然后 twine upload dist/*   （需注册 PyPI 账号）

个人项目用 pip install -e . 就够了，发布 PyPI 是可选进阶。

部署上线流程

完整走一遍（以 Flask 为例）：

# 1. 服务器上拉代码
git clone https://github.com/you/myproject.git
cd myproject

# 2. 建虚拟环境装依赖
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# 3. 配置环境变量
export DB_PASSWORD=xxxx
export API_KEY=xxxx

# 4. 跑测试（上线前必做）
pytest

# 5. 启动服务（gunicorn）
gunicorn -w 4 -b 127.0.0.1:8000 myproject.app:app

# 6. nginx 反向代理 + HTTPS（略，见 Flask 篇）

# 7. 更新时：pull → 重启
git pull
kill -HUP $(cat gunicorn.pid)   # 或 supervisorctl restart myproject

上线三件套永远不变：测试过了再上、配置用环境变量、更新要可回滚（git 就是你的回滚按钮）。

新手坑

坑 1：密钥提交进 git。一旦提交过，改密码都没用（git 历史里还留着）。发现提交了立刻轮换密钥。

坑 2：项目根目录放一堆散文件。入口、脚本、测试、数据全平铺，谁也找不到。按标准结构组织。

坑 3：不写 README。三个月后你自己都忘了怎么跑。README 是给未来的自己写的。

小结

• 标准结构：src/ 代码、tests/ 测试、requirements.txt、README.md、.gitignore
• 配置用环境变量（os.getenv + .env），密钥永不进 git
• git 三件事：改代码 → add → commit；分支干活、合并回主分支
• 打包：pyproject.toml + pip install -e .
• 部署：拉代码 → 装依赖 → 配环境变量 → 测试 → 启动 → 更新可回滚

练习

1. 把之前的记账本项目按标准结构重组（src/ tests/ README），加 .gitignore
2. 用 git 初始化项目，提交两次（不同功能），练习 git log 和回退
3. 思考：为什么密钥放环境变量而不是代码里？如果 .env 被提交进 git 会发生什么，怎么补救？