/* MD / 富文本中的 .toc（含博客园搬家等嵌套结构）；.toc-box 在侧栏，不受影响 */
#content_views .toc,
/* 编辑器常在目录前后插入空 p（:empty 仍占 20px），一并去掉避免顶空隙 */
#content_views.markdown_views > p:empty:has(+ .toc),
#content_views.markdown_views > .toc + p:empty,
/* 富文本旧版目录标记 */
#content_views.htmledit_views #main-toc,
#content_views.htmledit_views #hr-toc,
#content_views.htmledit_views p[id*=\”-toc\”] {
display: none !important;
}
/* 目录去掉后，紧跟的首个标题不再多出一块上边距 */
#content_views.markdown_views > .toc + h1,
#content_views.markdown_views > .toc + h2,
#content_views.markdown_views > .toc + h3,
#content_views.markdown_views > .toc + h4,
#content_views.markdown_views > .toc + p:empty + h1,
#content_views.markdown_views > .toc + p:empty + h2,
#content_views.markdown_views > .toc + p:empty + h3,
#content_views.markdown_views > .toc + p:empty + h4 {
margin-top: 0 !important;
}
Python CLI 工程规范手册：代码结构、测试与发布最佳实践
在团队内部，很多工程师都写过用于数据处理、环境部署或辅助排障的 Python 脚本。
但绝大多数脚本都停留在“个人自制小脚本”的状态：代码只有一个平铺的 main.py、没有参数校验、缺少退出码规范、没有单元测试、依赖全靠在微信群里发一段 pip install 指令。当这个工具需要交给其他团队使用或集成进 CI/CD 自动化流水线时，就会爆发出各种兼容性问题与维护噩梦。
将一个随手的 Python 脚本，打造成一个结构规范、测试完备、可自动化打包分发的工业级 CLI 工具，需要遵循一套标准的工程化体系。
本文结合团队在开源与内部基础设施建设中的经验，提炼了一份现代 Python CLI 工程落地全景规范手册。
一、标准工程目录结构规范 (src-layout)
严禁在项目根目录下直接散落 Python 文件，必须采用经过社区充分验证的 src-layout 架构：
my-dev-cli/
├── .github/
│ └── workflows/
│ ├── test.yml # CI 自动化测试与 Lint
│ └── publish.yml # PyPI / Homebrew 自动化发布
├── src/
│ └── my_cli/
│ ├── __init__.py # 包导出与版本声明
│ ├── cli.py # 主命令入口 (Click/Typer 路由)
│ ├── core/ # 纯业务逻辑层 (零 CLI 依赖)
│ │ ├── __init__.py
│ │ └── engine.py
│ ├── commands/ # 子命令具体实现
│ │ ├── __init__.py
│ │ ├── deploy.py
│ │ └── status.py
│ └── utils/ # 工具库 (终端渲染/网络/配置)
│ ├── __init__.py
│ ├── config.py
│ └── printer.py
├── tests/ # 单元测试与集成测试
│ ├── conftest.py
│ ├── test_cli.py
│ └── test_engine.py
├── pyproject.toml # 现代统一元数据与依赖声明
└── README.md
二、声明式元数据配置 (pyproject.toml)
全面拥抱 PEP 621 标准，彻底告别旧时代的 setup.py 与 setup.cfg：
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
[project]
name = "my-dev-cli"
version = "1.0.0"
description = "企业级研发效能与运维治理命令行工具"
readme = "README.md"
requires-python = ">=3.10"
license = { text = "MIT" }
authors = [{ name = "Gu Shian", email = "gushian@example.com" }]
dependencies = [
"click>=8.1.7",
"rich>=13.7.0",
"pydantic-settings>=2.2.0",
"httpx>=0.27.0"
]
[project.scripts]
my-cli = "my_cli.cli:main"
[tool.hatch.build.targets.wheel]
packages = ["src/my_cli"]
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v –cov=src/my_cli –cov-report=term-missing –cov-fail-under=80"
三、命令分层设计与关注点分离
CLI 工程的核心架构原则是：命令交互层（Commands）与核心业务逻辑层（Core Engine）必须严格解耦。
# ❌ 反模式：在 CLI 命令函数内部直接写死业务逻辑与外部网络请求
@click.command()
def deploy():
# 在这里直接写了 200 行拼装请求、读写文件的代码 (无法进行纯单元测试)
pass
# ✅ 规范设计：命令层只负责入参校验与终端输出，核心逻辑交给纯 Python 引擎
from my_cli.core.engine import DeploymentEngine
@click.command()
@click.option("–env", type=click.Choice(["staging", "prod"]), required=True)
def deploy(env: str):
"""触发自动化部署"""
engine = DeploymentEngine()
try:
result = engine.execute_deployment(env)
print_success(f"部署成功: {result.deploy_id}")
except DomainError as e:
print_error(f"部署失败: {e.message}")
sys.exit(1)
这样设计的好处是，DeploymentEngine 是一个纯粹的 Python 类，可以在单测中被极速测试，也可以被其他 Python 脚本直接当成 SDK 库调用。
四、自动化测试准入红线
借助 click.testing.CliRunner，为每个命令编写完备的自动化测试：
from click.testing import CliRunner
from my_cli.cli import main
def test_deploy_missing_env_returns_code_2():
runner = CliRunner()
result = runner.invoke(main, ["deploy"])
assert result.exit_code == 2 # 参数缺失退出码必须为 2
assert "Missing option '–env'" in result.output
在 CI 流水线中强制执行两道门禁：
五、标准化分发机制
- 内部开发者使用：通过 pipx install my-dev-cli 进行环境隔离安装；
- macOS/Linux 用户：通过 GitHub Actions 自动打包发布至专属 Homebrew Tap；
- CI/CD 自动化容器：提供轻量级的单二进制产物或轻量 Docker 镜像。
从个人脚本走向工程化 CLI，不是繁文缛节，而是对软件交付确定性与团队协作效率的最高敬意。
