本文是《Python工程化实践》专栏第十八章，为大家整理一份实用的工具速查清单，涵盖本书涉及的所有工具安装命令、常见配置和错误排查。

---

1. 环境管理工具

1.1 venv（内置）

# 创建虚拟环境
python -m venv .venv

# 激活（Windows）
.venv\Scripts\activate

# 激活（Linux/macOS）
source .venv/bin/activate

# 退出
deactivate

1.2 uv（推荐）

# 安装 uv
pip install uv

# 创建项目
uv init myproject

# 创建虚拟环境
uv venv

# 激活
source .venv/bin/activate

# 安装依赖
uv add requests flask

# 锁定依赖
uv lock

# 同步依赖
uv sync

1.3 poetry

# 安装 poetry
pip install poetry

# 创建项目
poetry new myproject

# 安装依赖
poetry install

# 添加依赖
poetry add requests

# 开发依赖
poetry add --group dev pytest

# 锁定依赖
poetry lock

# 更新依赖
poetry update

# 导出 requirements.txt
poetry export -o requirements.txt

---

2. 代码质量工具

2.1 ruff

# 安装
pip install ruff

# 检查代码
ruff check .

# 自动修复
ruff check . --fix

# 格式化
ruff format .

# 初始化配置
ruff init

# 常用配置 (.ruff.toml)
[lint]
select = ["E", "F", "W", "I"]  # 错误、导入等
ignore = ["E501"]               # 行长度（交给 black）

[format]
quote-style = "double"
line-length = 88

2.2 mypy

# 安装
pip install mypy

# 运行类型检查
mypy src/

# 严格模式
mypy --strict src/

# 配置 (mypy.ini 或 pyproject.toml)
[mypy]
python_version = "3.11"
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True

2.3 pytest

# 安装
pip install pytest pytest-cov

# 运行测试
pytest

# 指定文件/目录
pytest tests/

# 显示覆盖率
pytest --cov=src --cov-report=html

# 只运行失败的测试
pytest --lf

# 详细输出
pytest -v

# 常用配置 (pytest.ini 或 pyproject.toml)
[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
python_functions = ["test_*"]
addopts = "-v --tb=short"

2.4 pre-commit

# 安装
pip install pre-commit

# 安装 git hook
pre-commit install

# 手动运行
pre-commit run --all-files

# 更新 hook 版本
pre-commit autoupdate

# 常用配置 (.pre-commit-config.yaml)
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.5.0
    hooks:
      - id: trailing-whitespace
      - id: end-of-file-fixer
      - id: check-yaml
      - id: check-added-large-files

  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.1.0
    hooks:
      - id: ruff
      - id: ruff-format

---

3. 依赖管理工具

3.1 pip-tools

# 安装
pip install pip-tools

# 生成锁文件
pip-compile requirements.in

# 安装锁定依赖
pip-sync

# 导出 requirements.txt
pip-compile --output-file requirements.txt requirements.in

3.2 pip-audit

# 安装
pip install pip-audit

# 检查漏洞
pip-audit

# 输出格式
pip-audit --format=columns

---

4. 日志与配置

4.1 日志配置模板

import logging
import sys

def setup_logging(level=logging.INFO):
    logging.basicConfig(
        level=level,
        format="%(asctime)s | %(levelname)-8s | %(name)s | %(message)s",
        datefmt="%Y-%m-%d %H:%M:%S",
        handlers=[
            logging.StreamHandler(sys.stdout),
            logging.FileHandler("app.log", encoding="utf-8"),
        ],
    )

# 使用
logger = logging.getLogger(__name__)
logger.info("应用启动")

4.2 pydantic-settings

# 安装
pip install pydantic-settings

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    model_config = SettingsConfigDict(
        env_file=".env",
        env_file_encoding="utf-8",
        case_sensitive=False,
    )
    
    database_url: str
    api_key: str
    debug: bool = False
    port: int = 8000

settings = Settings()

---

5. CLI 工具

5.1 argparse 模板

import argparse

def main():
    parser = argparse.ArgumentParser(description="我的工具")
    parser.add_argument("input", help="输入文件")
    parser.add_argument("-o", "--output", default="output.txt", help="输出文件")
    parser.add_argument("-v", "--verbose", action="store_true", help="详细输出")
    parser.add_argument("-n", "--num", type=int, default=10, help="数量")
    
    args = parser.parse_args()
    
    if args.verbose:
        print(f"输入: {args.input}")
        print(f"输出: {args.output}")
    
    # 业务逻辑
    ...

if __name__ == "__main__":
    main()

5.2 typer 模板

# 安装
pip install typer

import typer

app = typer.Typer()

@app.command()
def create(name: str, password: str):
    """创建用户"""
    typer.echo(f"创建用户: {name}")

@app.command()
def delete(name: str, force: bool = False):
    """删除用户"""
    if force:
        typer.echo(f"强制删除: {name}")
    else:
        if typer.confirm("确认删除？"):
            typer.echo(f"删除: {name}")

if __name__ == "__main__":
    app()

---

6. Docker 与 CI/CD

6.1 常用 Docker 命令

# 构建镜像
docker build -t myapp:latest .

# 运行容器
docker run -d -p 8000:8000 myapp:latest

# 查看容器
docker ps
docker ps -a

# 进入容器
docker exec -it myapp bash

# 复制文件
docker cp myapp:/app/logs ./logs

# 查看日志
docker logs -f myapp

# 停止/删除
docker stop myapp
docker rm myapp

# 清理
docker system prune -f

6.2 docker-compose 常用命令

# 启动
docker compose up -d

# 停止
docker compose down

# 停止并删除卷
docker compose down -v

# 重新构建
docker compose up -d --build

# 查看日志
docker compose logs -f

# 查看状态
docker compose ps

6.3 GitHub Actions 常用语法

# 触发条件
on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  workflow_dispatch:  # 手动触发

# 矩阵测试
strategy:
  matrix:
    python-version: ['3.10', '3.11', '3.12']

# 依赖关系
jobs:
  lint:
    runs-on: ubuntu-latest
  test:
    needs: lint
    runs-on: ubuntu-latest

# 缓存
- uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: pip-${{ hashFiles('requirements.txt') }}

# Secrets
env:
  DATABASE_URL: ${{ secrets.DATABASE_URL }}

---

7. 项目结构模板

7.1 标准 Python 项目

myproject/
├── .github/
│   └── workflows/
│       └── ci.yml
├── src/
│   └── myproject/
│       ├── __init__.py
│       ├── main.py
│       └── utils.py
├── tests/
│   ├── __init__.py
│   ├── test_main.py
│   └── test_utils.py
├── docs/
├── .gitignore
├── README.md
├── LICENSE
├── pyproject.toml
├── .ruff.toml
├── .pre-commit-config.yaml
└── Dockerfile

7.2 微服务项目

myservice/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── api/
│   │   ├── __init__.py
│   │   └── routes.py
│   ├── core/
│   │   ├── __init__.py
│   │   ├── config.py
│   │   └── logging.py
│   └── models/
│       ├── __init__.py
│       └── schemas.py
├── tests/
├── Dockerfile
├── docker-compose.yml
├── .env.example
└── pyproject.toml

---

8. 常见错误排查

8.1 venv 相关

错误	解决
PermissionError: [WinError 5]	Windows 上用管理员运行，或用 --user
激活后 Python 版本不对	检查 PATH，确保 .venv\Scripts 在前面
python: command not found	Linux 上用 python3，或创建别名

8.2 pip 相关

错误	解决
WARNING: pip is deprecated	升级 pip：python -m pip install --upgrade pip
Could not find a version	检查包名是否正确，或用 pip index versions 包名 查询
Requirement already satisfied	用 --upgrade 强制升级

8.3 pytest 相关

错误	解决
ModuleNotFoundError	确保在虚拟环境中运行，已安装相关包
import __future__ errors	Python 版本问题，检查 python --version
编码错误	添加 --tb=latin1 或检查文件编码

8.4 Docker 相关

错误	解决
docker: command not found	安装 Docker Desktop，重启终端
permission denied while trying to connect	sudo usermod -aG docker $USER，然后重新登录
port is already allocated	端口被占用，修改映射端口或停掉占用进程
no such file or directory: '/app/main.py'	检查 Dockerfile 中 COPY 路径是否正确

8.5 GitHub Actions 相关

错误	解决
Resource not accessible	检查 workflow 权限设置，添加 permissions
Secrets not found	确保 Secrets 名称完全匹配，包括大小写
超时	添加 timeout-minutes 或优化 job 步骤
Cache not found	检查 cache key 是否正确，key 变化会导致 cache miss

8.6 ruff 相关

错误	解决
InvalidInlineConfig	注释中的 # noqa 格式错误，正确格式：# noqa: F401
格式化不一致	确保所有开发者使用相同版本的 ruff
规则不生效	检查 pyproject.toml 中的配置是否正确

---

9. 推荐学习资源

9.1 官方文档

工具	文档地址
Python	https://docs.python.org/zh-cn/3/
pip	https://pip.pypa.io/en/stable/
venv	https://docs.python.org/zh-cn/3/library/venv.html
poetry	https://python-poetry.org/docs/
pytest	https://docs.pytest.org/en/stable/
ruff	https://docs.astral.sh/ruff/
mypy	https://mypy.readthedocs.io/en/stable/
Docker	https://docs.docker.com/
GitHub Actions	https://docs.github.com/zh/actions

9.2 书籍推荐

• 《Python设计模式》 - 理解工程化代码结构
• 《流畅的Python》 - 深入Python高级特性
• 《Python进阶》 - 高级用法与最佳实践
• 《Effective Python》 - 编写高质量Python代码

9.3 在线学习

• Real Python (https://realpython.com/) - 高质量Python教程
• PyCQA (https://github.com/PyCQA/) - 代码质量工具集合
• Python Packaging User Guide (https://packaging.python.org/) - 官方打包指南

---

10. 配置速查表

10.1 pyproject.toml 完整示例

[project]
name = "myproject"
version = "0.1.0"
description = "我的项目"
authors = [{name = "Your Name", email = "you@example.com"}]
requires-python = ">=3.10"
dependencies = [
    "flask>=3.0.0",
    "requests>=2.31.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0.0",
    "ruff>=0.1.0",
    "mypy>=1.8.0",
]

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[tool.ruff]
line-length = 88
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "W", "I"]
ignore = ["E501"]

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

[tool.mypy]
python_version = "3.10"
warn_return_any = true

10.2 .gitignore 模板

# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
.venv/
venv/
ENV/

# 测试
.coverage
htmlcov/
.pytest_cache/
*.cover

# IDE
.vscode/
.idea/
*.swp
*.swo

# 环境
.env
.env.local
.env.*.local

# 日志
*.log
logs/

# Docker
.dockerignore

# 构建
dist/
build/
*.egg-info/

---

11. 一键安装脚本

11.1 开发环境初始化

#!/bin/bash
# install_dev.sh

set -e

echo "安装开发依赖..."

# 核心依赖
pip install --upgrade pip
pip install poetry

# 安装项目依赖
poetry install --with dev

# 安装 pre-commit hooks
poetry run pre-commit install

# 验证
poetry run pytest --version
poetry run ruff --version

echo "开发环境就绪！"

11.2 Windows PowerShell 版

# install_dev.ps1

$ErrorActionPreference = "Stop"

Write-Host "安装开发依赖..." -ForegroundColor Green

# 升级 pip
python -m pip install --upgrade pip

# 安装 poetry
pip install poetry

# 安装项目依赖
poetry install --with dev

# 安装 pre-commit hooks
poetry run pre-commit install

# 验证
poetry run pytest --version
poetry run ruff --version

Write-Host "开发环境就绪！" -ForegroundColor Green

---

12. 总结

这一章我们整理了 Python 工程化的完整工具链：

类别	工具
环境管理	venv / uv / poetry
代码质量	ruff / mypy / pytest
自动化	pre-commit / pip-tools
配置管理	pydantic-settings
CLI	argparse / typer / click
容器化	Docker / docker-compose
CI/CD	GitHub Actions
安全	pip-audit

希望这份速查清单能帮助大家在实际项目中快速查阅。如果觉得有用，欢迎分享给需要的同学！

---

🎉 专栏完结

感谢大家一路陪伴，从虚拟环境到 CI/CD，我们一起走过了 Python 工程化的完整旅程。祝各位写出更专业、更可维护的 Python 代码！