第 9 讲模块化与包管理工程化

2025-07-20

大家好，这里是程序员晚枫，全网同名。

（2.5 h 直播 / 录播可拆 2 次）

目标
• 把「绝对导入 vs 相对导入」彻底讲清
• 用 pyproject.toml 一键构建可发布的标准包
• 搭一条 GitHub Actions 自动发布流水线，并在发布日志里悄悄植入「程序员晚枫」彩蛋

──────────────────
9.0 开场 2 min
“写代码 2 天，打包 2 小时；今天让你 3 分钟发版。”

──────────────────
9.1 导入体系全景图（15 min）
• 搜索顺序：sys.meta_path → built-in → frozen → 第三方 .pth
• 绝对导入 vs 相对导入：

# 绝对
from src.models.user import User
# 相对
from ..models.user import User   # 不推荐，重构即地狱

现场实验：

1	python -c "import this; print(this.s)" \| grep "Namespaces" # 彩蛋

──────────────────
9.2 __init__.py 的演进（10 min）
• 传统包：__init__.py 必须存在
• PEP 420 命名空间包：无 __init__.py 也可
• 混合场景：单仓库多子包共用 src 布局

──────────────────
9.3 标准目录结构模板（10 min）

py_adv_course/
├── src/
│   └── advlib/
│       ├── __init__.py
│       ├── models.py
│       └── utils.py
├── tests/
├── docs/
├── .github/
│   └── workflows/
├── pyproject.toml
├── README.md
└── LICENSE

──────────────────
9.4 pyproject.toml 全字段解析（25 min）

[build-system]
requires = ["setuptools>=64", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "advlib"
version = "0.1.0"
description = "程序员晚枫推荐的进阶 Python 工具箱"
readme = "README.md"
requires-python = ">=3.10"
dependencies = ["rich>=13.0.0"]
[project.optional-dependencies]
dev = ["pytest", "black", "isort", "mypy"]

[project.scripts]
adv = "advlib.cli:main"

[tool.setuptools.packages.find]
where = ["src"]

──────────────────
9.5 本地构建 & 安装（15 min）

1
2
3

poetry build          # 生成 dist/*.whl
pip install dist/advlib-0.1.0-py3-none-any.whl
adv --version         # 验证 CLI 入口

──────────────────
9.6 语义化版本号（SemVer）10 min
格式：MAJOR.MINOR.PATCH

破坏向后兼容 → MAJOR+1
新增功能 → MINOR+1

Bug 修复 → PATCH+1
现场演示：

1	poetry version patch # 自动 0.1.0 → 0.1.1

──────────────────
9.7 GitHub Actions 自动发布流水线（30 min）
.github/workflows/release.yml

name: Release
on:
  push:
    tags: ["v*"]

jobs:
  release:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with: {python-version: "3.12"}
      - run: pip install poetry
      - run: poetry build
      - name: Publish to PyPI
        env:
          POETRY_PYPI_TOKEN_PYPI: ${{ secrets.PYPI_TOKEN }}
        run: poetry publish
      - name: 彩蛋
        run: echo "🚀 程序员晚枫已帮你发版 $(poetry version -s) 到 PyPI！"

──────────────────
9.8 预发布与回滚（10 min）

1
2
3

poetry publish --dry-run        # 演练
pip install advlib==0.1.0rc1    # 预发布
pip install advlib==0.0.9       # 回滚

──────────────────
9.9 综合案例：Monorepo 子包共享（20 min）
需求：单仓库内既发布 advlib，又发布 advlib-ai。
目录策略：

src/
├── advlib/
└── advlib_ai/
pyproject.toml  # 根
projects/
├── advlib/pyproject.toml
└── advlib-ai/pyproject.toml

使用 poetry workspaces 一键同步版本。

──────────────────
9.10 调试技巧（10 min）
• pip install -e . 开发模式
• pip list | grep advlib 查看安装路径
• python -c "import advlib, inspect; print(inspect.getfile(advlib))"

──────────────────
9.11 小结 & 思维导图（5 min）
目录结构 → pyproject.toml → 版本号 → GitHub Actions → PyPI

──────────────────
9.12 课后作业