罗罗编程学习记录
本页内容 展开查看

08.4 阶段 3:环境依赖与质量工具链

所属:全栈开发面试题库 / 学习路径 / 08 Python 全栈

本页目录

一、阶段定位

阶段 0 只用 venv 做了最简单的隔离,阶段 1、2 的代码还没有测试、没有 lint、没有类型门禁。本阶段把工程化工具链补齐:依赖从「全局 pip 装到哪算哪」升级为「锁文件可复现」;代码从「能跑」升级为「lint + 类型检查 + 测试全过」。阶段 4 写 FastAPI 时,这个工具链就是合并前的门禁;阶段 7 部署时,CI 流水线就是把这些命令串起来。

与前后阶段的衔接:因为阶段 2 已经写了类型注解,本阶段的 mypy 才有东西可查;因为阶段 1、2 的代码还没有测试,本阶段的 pytest 要回头补测试。跳过本阶段直接进 Web 开发,后面会出现「本地能跑、CI 红」「别人 clone 下来依赖装不上」「类型注解写了但没人检查」三类问题。

原有卡点及判断依据:

  • 全局环境安装依赖导致项目间冲突:判断现象是 pip list 里混着 requests、flask、pandas 等互不相关的包,且版本互相覆盖。本阶段用 uv 锁文件解决,见 5.1。
  • 类型检查一上来拉满严格模式,报错过多直接放弃:判断现象是 mypy --strict 后几百条错误,团队直接关掉。本阶段讲渐进式接入,见 5.4。
  • mock 过度导致测试与真实行为脱节:判断现象是测试全绿,但线上调用真实 API 报错。本阶段讲 mock 的边界,见 5.6。
  • 锁文件未纳入版本管理导致依赖不可复现:判断现象是别人 clone 后 uv sync 装出不同版本。见 5.1。

二、阶段目标与投入

能力目标(可验证的行为) 验证方式
能用 uv 创建工程并生成锁文件,在干净环境 uv sync 复现 删除 .venv 后 uv sync 结果与锁文件一致
能写标准 pyproject.toml,区分生产/开发/测试依赖分组 uv sync --group dev 与 uv sync 安装包集合不同
能用 ruff 检查与格式化代码,规则可配置 ruff check . 与 ruff format . 无输出
能在 mypy 默认配置下通过,逐步引入严格选项 mypy . 0 error
能写 pytest fixture 并按作用域复用,用参数化驱动多组用例 测试隔离正确,fixture 复用次数符合预期
能配置 coverage 门禁,外部协作对象全部 mock pytest --cov 覆盖率达阈值,CI 红即阻断

建议学时:

  • 全职:2 周,约 60 小时。uv 与 pyproject 15 小时、ruff 5 小时、mypy 15 小时、pytest 20 小时、pre-commit 5 小时。
  • 在职:5–6 周,约 70 小时。

学时分配建议:依赖管理与锁文件 20%、ruff 10%、mypy 20%、pytest 与 mock 35%、coverage 与 pre-commit 15%。

三、先修自检

先修项 合格标准 不合格时回到
venv 基础 会创建与激活虚拟环境 08.1 阶段 0
函数与类 能写函数与类 08.2 阶段 1
类型注解 能为函数写注解 08.3 阶段 2

四、知识地图

模块 知识点 掌握程度 对应题库章节
依赖管理 uv 安装/解析/锁文件、venv 隔离、版本管理 会用 06.1 通用后端工程
pyproject.toml PEP 621 字段、依赖分组、平台标记 会用 06.1 通用后端工程
ruff lint 规则集、自动修复、format、与 flake8/isort 关系 会用 06.1 通用后端工程
mypy 默认配置、--strict、渐进式接入、基线 会用 06.1 通用后端工程
pytest fixture 作用域、参数化、-k、--cov 会用 06.1 通用后端工程
mock unittest.mock、monkeypatch、边界 会用 06.1 通用后端工程
pre-commit 钩子配置、本地与 CI 一致 会用 06.1 通用后端工程

进度管理建议:把工具链跑通后,所有阶段 1、2 的代码都要补测试。《知识点全清单》「环境依赖」「质量工具链」段是全量清单。

五、分模块精讲

5.1 venv、uv 与锁文件

为什么需要它:venv 只隔离目录,不锁定版本;pip freeze 导出的 requirements.txt 不记录传递依赖版本,安装结果可能漂移。uv 用一个锁文件固定完整依赖树,干净环境 uv sync 结果可复现。

核心机制:

  • venv:复制/软链解释器,独立 site-packages;跨项目隔离。
  • uv:Astral 出品的 Rust 实现,兼容 pip 生态,解析速度比 pip 快 10–100 倍;用 uv.lock 锁文件记录每个包的精确版本与哈希。
  • uv init 创建工程骨架;uv add requests 加入依赖并写锁文件;uv sync 在干净环境按锁文件安装。
  • uv 与 pip 的差异:pip 每次解析依赖树,uv 有缓存与锁;pip 的 requirements.txt 是顶层声明,uv.lock 是完整闭包。

最小可运行示例:

# 安装 uv(一次性)
# macOS / Linux: curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 创建工程
uv init myproj
cd myproj

# 加生产依赖
uv add requests fastapi

# 加开发依赖(分组)
uv add --dev pytest ruff mypy

# 干净环境复现
rm -rf .venv
uv sync                 # 按 uv.lock 安装,结果与同事一致
uv sync --group dev     # 安装含 dev 组

# 锁定当前版本
uv lock

常见坑:

现象 原因 修法
同事 clone 后 uv sync 装出不同版本 没提交 uv.lock 把 uv.lock 提交进 Git
uv add 报错找不到 Python 本机没装对应版本 uv python install 3.11
全局 pip 仍被使用 没激活 uv 管理的环境 用 uv run python ... 或在 .venv 里执行

面试考法:常问「锁文件解决什么问题」。答「固定完整依赖树的精确版本与哈希,保证干净环境安装可复现;避免『我这能跑』」。追问「uv 比 pip 快在哪」,答 Rust 实现、并行解析、全局缓存。

5.2 pyproject.toml 与依赖分组

为什么需要它:每个工具都有自己的配置文件(setup.cfg、tox.ini、.flake8、mypy.ini),分散难维护。PEP 621 统一到 pyproject.toml,所有工具按 [tool.xxx] 分节配置。

核心机制:

  • [project]:名称、版本、依赖、Python 版本要求。
  • [project.optional-dependencies] 或 uv 的 [tool.uv] dev-dependencies:开发依赖分组。
  • [tool.ruff]、[tool.mypy]、[tool.pytest.ini_options]:各工具配置。
  • 依赖分组:生产只装运行时依赖,开发组含测试、lint、类型检查工具。

最小可运行示例:

# pyproject.toml
[project]
name = "myproj"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
    "fastapi>=0.110",
    "uvicorn>=0.29",
]

[dependency-groups]
dev = [
    "pytest>=8",
    "ruff>=0.5",
    "mypy>=1.10",
]

[tool.ruff]
line-length = 100
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "B", "UP"]

[tool.mypy]
python_version = "3.11"
strict = false
warn_unused_ignores = true

[tool.pytest.ini_options]
addopts = "-v"
testpaths = ["tests"]

常见坑:

现象 原因 修法
开发工具被装到生产镜像 依赖分组没分开 生产只 uv sync --no-dev,Docker 多阶段构建
配置改了工具不识别 toml 字段名写错 查对应工具文档核对字段名

面试考法:常问「pyproject.toml 解决了什么」。答「统一项目元数据与工具配置,告别 setup.cfg、tox.ini、.flake8 多个文件」。

5.3 ruff:lint 与 format

为什么需要它:flake8、isort、black 是三个工具,各自规则、各自速度。ruff 一个工具覆盖 lint 与 format,速度是 flake8 的几十倍,配置在 pyproject.toml 里。

核心机制:

  • ruff check .:lint,规则集按 select = ["E", "F", "I", "B", "UP"] 选择(E=pycodestyle、F=pyflakes、I=isort、B=bugbear、UP=pyupgrade)。
  • ruff check --fix .:自动修复可修复项。
  • ruff format .:格式化,风格接近 black。
  • 在 CI 里跑 ruff check . && ruff format --check .,任何一项失败即阻断。

最小可运行示例:

# 检查
ruff check .

# 自动修复
ruff check --fix .

# 格式化
ruff format .

# CI 中只检查不修改
ruff format --check .

常见坑:

现象 原因 修法
规则与团队风格冲突 选了太多规则 在 [tool.ruff.lint] ignore 里关掉
ruff format 与 black 输出不一致 二者风格略有差异 统一用 ruff,不用 black

面试考法:常问「ruff 和 flake8、black 的关系」。答「ruff 是 Rust 实现的替代,lint 替代 flake8+isort+pyupgrade,format 替代 black;速度快几十倍,配置统一」。

5.4 mypy:渐进式接入严格模式

为什么需要它:阶段 2 写了类型注解,但没人检查等于白写。mypy 是最主流的静态类型检查器;一上来 --strict 会报几百个错,正确做法是渐进式接入。

核心机制:

  • mypy . 默认配置:只检查有注解的函数,不强制所有参数。
  • mypy --strict:开启全部严格选项,包括 disallow_untyped_defs、warn_return_any 等。
  • 渐进式策略:先默认配置 → 0 error;再逐步开启 warn_redundant_casts、disallow_untyped_defs;最后 --strict。
  • 对动态特性(ORM、第三方库)用 # type: ignore[attr-defined] 或 mypy --strict 局部豁免。

最小可运行示例:

# 默认检查
mypy .

# 严格模式(新项目直接上)
mypy --strict .

# 只检查某个目录
mypy src/

# 生成基线(老项目)
mypy . --generate-baseline=mypy-baseline.txt
# 之后只报新增错误,存量错误逐步治理

常见坑:

现象 原因 修法
--strict 后几百条错误 一上来拉满 先用默认配置清零,再逐步开严格选项
ORM 模型属性报错 ORM 动态注入字段 用官方 mypy 插件(如 [tool.django-stubs])或 # type: ignore
# type: ignore 被滥用 报错就忽略 用 warn_unused_ignores = true 检查无效忽略

面试考法:常问「老项目怎么引入 mypy」。答「默认配置清零 → 开 warning 级选项 → 逐步 disallow_untyped_defs → 最后 --strict;用 baseline 隔离存量错误」。

5.5 pytest:fixture 作用域与参数化

为什么需要它:unittest 样板代码多、fixture 复用难。pytest 用 fixture 按作用域注入资源,用参数化驱动多组用例,测试代码简洁。

核心机制:

  • fixture:@pytest.fixture 装饰的函数,测试函数参数名匹配时自动注入。
  • 作用域:function(默认,每个测试新建)、class、module、package、session。
  • 参数化:@pytest.mark.parametrize("a, b, expected", [(1,2,3), (2,3,5)]) 一次写多组用例。
  • 常用命令:pytest -k "login" 按名字过滤;pytest --cov=src --cov-report=term-missing 覆盖率。

最小可运行示例:

# tests/test_calc.py
import pytest


@pytest.fixture
def user():
    return {"name": "Ann", "age": 30}


def test_user_name(user):
    assert user["name"] == "Ann"


@pytest.mark.parametrize("a, b, expected", [
    (1, 2, 3),
    (0, 0, 0),
    (-1, 1, 0),
])
def test_add(a, b, expected):
    assert a + b == expected
# 跑全部
pytest

# 按名字过滤
pytest -k "login"

# 覆盖率
pytest --cov=src --cov-report=term-missing --cov-fail-under=80

常见坑:

现象 原因 修法
fixture 每个测试都重建,慢 默认 function 作用域 复用开销大的 fixture 用 scope="module" 或 session
测试间状态串扰 用了模块级全局变量 用 fixture 隔离,每个测试独立
覆盖率 100% 但线上有 bug 为凑覆盖率写无效用例 关注分支覆盖与关键路径覆盖,不追求行覆盖数字

面试考法:常问「fixture 的作用域有哪些、怎么选」。答「function 默认隔离;module/session 用于连接池、数据库这类重资源」。追问「pytest 和 unittest 的区别」,答「fixture 注入、参数化、插件生态、断言更简洁」。

5.6 mock、monkeypatch 与覆盖率边界

为什么需要它:单元测试不能真的调用外部 API、数据库、时间——否则慢、不稳定、依赖外部环境。mock 把这些协作对象换成假对象,但 mock 过度会导致测试与真实行为脱节。

核心机制:

  • unittest.mock.Mock / MagicMock:模拟对象,记录调用。
  • monkeypatch fixture:临时替换模块属性、环境变量,测试结束自动还原。
  • mock 构造器:@patch("module.ClassName") 替换类,返回 Mock 实例。
  • 边界:mock 外部协作对象(API、DB、时间),不 mock 被测对象本身。

最小可运行示例:

# 被测代码:调用外部 API
import requests


def get_user_name(uid: int) -> str:
    resp = requests.get(f"https://api.example.com/users/{uid}", timeout=5)
    resp.raise_for_status()
    return resp.json()["name"]


# 测试:mock requests.get
from unittest.mock import patch, MagicMock


@patch("myapp.user.requests.get")
def test_get_user_name(mock_get):
    mock_resp = MagicMock()
    mock_resp.json.return_value = {"name": "Ann"}
    mock_resp.raise_for_status.return_value = None
    mock_get.return_value = mock_resp

    name = get_user_name(1)
    assert name == "Ann"
    mock_get.assert_called_once_with("https://api.example.com/users/1", timeout=5)

常见坑:

现象 原因 修法
mock 了被测对象本身 把要测的类也 mock 了 只 mock 外部协作对象
mock 设置太细,API 改了测试还绿 mock 与真实行为脱节 保留契约测试(对真实 sandbox 跑一次)
monkeypatch 后环境变量没还原 没用 fixture 用 pytest 的 monkeypatch fixture,自动还原

面试考法:常问「mock 适用于什么、边界在哪」。答「mock 外部依赖(网络、DB、时间),不 mock 被测对象;过度 mock 会让测试与真实行为脱节」。

5.7 pre-commit 与 CI 门禁

为什么需要它:本地跑过 lint 再提交,比 CI 报红再返工快。pre-commit 把 lint、format、类型检查挂到 git commit 钩子,不合规代码提交不了。

核心机制:

  • .pre-commit-config.yaml 声明钩子,每个钩子是一个 repo 与 id。
  • pre-commit install 把钩子装到 .git/hooks/。
  • 提交时自动跑钩子;失败则阻断 commit。
  • CI 里跑同样的命令,保证本地与 CI 一致。

最小可运行示例:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.5.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format
  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.10.0
    hooks:
      - id: mypy
pre-commit install
pre-commit run --all-files

常见坑:

现象 原因 修法
钩子报错后没法提交 代码不合规 按提示修复后重新 add/commit
CI 红但本地没跑 钩子没装 新 clone 后先 pre-commit install

面试考法:常问「pre-commit 解决什么」。答「把代码检查前移到本地,避免 CI 红返工;本地与 CI 规则保持一致」。

六、分层练习

6.1 复现型

练习 要求 验收标准 预计耗时
uv 创建工程 uv init 建工程,加 requests 与 pytest uv sync 在删 .venv 后复现 1 小时
ruff 检查与格式化 配 pyproject.toml,跑 ruff check --fix 0 错误 0.5 小时
mypy 默认检查 对阶段 2 的代码跑 mypy . 0 error 1 小时
pytest fixture 写一个带 fixture 的测试 测试隔离正确 1 小时
coverage 门禁 pytest --cov --cov-fail-under=80 覆盖率达阈值 1 小时

6.2 改造型

练习 要求 验收标准 预计耗时
引入 dev 依赖分组 把 pytest 从主依赖移到 dev 组 生产镜像不含 pytest 0.5 小时
mypy 渐进式 老项目用 baseline 隔离存量错误 新增代码 0 error 1.5 小时
mock 外部 API 给一个调用 requests 的函数写测试 mock 验证调用参数 1.5 小时
pre-commit 配 ruff + mypy 钩子 commit 时自动跑 1 小时

6.3 设计型

练习 要求 验收标准 预计耗时
工程模板 为后续项目沉淀一个带工具链的模板 新工程复制即可用 3 小时
测试覆盖核心逻辑 给阶段 1 的两个 CLI 工具补测试 关键路径覆盖,分支可达 4 小时
CI 配置草稿 写一个 GitHub Actions 或 GitLab CI 配置 跑 lint + mypy + pytest 2 小时

七、排障表

现象 可能原因 排查步骤 解决办法
uv sync 装出与锁文件不同版本 没提交 uv.lock 看 Git 状态 提交 uv.lock
ruff check 大量规则报错 规则集选太多 看报错规则名 在 [tool.ruff.lint] ignore 关掉
mypy 报 ORM 动态属性 ORM 动态注入字段 看报错文件 用官方插件或 # type: ignore
pytest 测试间状态串扰 模块级全局状态 看 fixture 作用域 用 fixture 隔离
coverage 100% 但线上有 bug 为覆盖率写无效用例 看测试是否真的断言行为 关注关键路径与分支
pre-commit 钩子没跑 没 pre-commit install 看 .git/hooks/ 重新安装
ModuleNotFoundError 在 pytest 时 工程根目录不在 sys.path 看运行目录 用 python -m pytest 或加 pyproject.toml 的 pythonpath
依赖装到生产镜像 dev 依赖没分组 看 Dockerfile 装包命令 生产 uv sync --no-dev

八、出口条件

全部勾选后再进入 08.5 阶段 4:Web 框架主线。

  • [ ] 能用 uv 创建工程、生成锁文件,在干净环境复现
  • [ ] 能写标准 pyproject.toml,区分生产/开发/测试依赖
  • [ ] ruff check . 与 ruff format --check . 0 错误
  • [ ] mypy . 0 error,理解渐进式接入策略
  • [ ] 能写 pytest fixture 按作用域复用,用参数化驱动多组用例
  • [ ] 能 mock 外部协作对象,知道 mock 的边界
  • [ ] coverage 门禁可配置,pre-commit 钩子可工作

自测题(先自己想,再看要点):

  1. 锁文件解决什么问题?
    • 要点:固定完整依赖树的精确版本与哈希,干净环境 uv sync 结果可复现。
  2. ruff 与 flake8、black 的关系?
    • 要点:ruff 一个工具覆盖 lint(替代 flake8+isort+pyupgrade)与 format(替代 black),Rust 实现速度快。
  3. mypy --strict 为什么不适合老项目一上来就开?
    • 要点:会报几百条错误打击信心;正确做法是默认配置清零 → 逐步开严格选项。
  4. fixture 的作用域有哪些?怎么选?
    • 要点:function/class/module/session;重资源(DB、连接池)用 module 或 session。
  5. mock 外部 API 时,边界在哪?
    • 要点:只 mock 外部协作对象,不 mock 被测对象本身;过度 mock 会与真实行为脱节。
  6. 为什么 uv.lock 必须提交进 Git?
    • 要点:否则同事 clone 后装出不同版本,依赖不可复现。
  7. pre-commit 与 CI 的关系?
    • 要点:本地跑钩子提前发现问题,CI 跑同一套命令保证一致;两者规则不能冲突。