优先选argparse（标准库、轻量）或click（子命令/补全/类型安全更优）；参数校验放解析后回调中；配置按命令行>环境变量>配置文件>默认值加载；输出应契约化，核心逻辑不print。
命令行入口怎么选：argparse 还是 click？
绝大多数 Python 命令行工具，入口层只该做一件事：把用户输入的 --help、-v、--output path.json 这类东西，干净地转成 Python 字典或命名空间。别在入口里写业务逻辑，也别在这里做数据校验或 I/O。
用 argparse 是最轻量的选择，标准库自带，适合简单工具（比如单命令、少于 5 个参数）。但一旦要支持子命令（mytool build / mytool deploy）、自动补全、类型转换或帮助文本格式化，click 就更稳——它把参数绑定和函数调用解耦得更彻底，错误提示也更友好。
常见错误现象：argparse 中把 type=int 和 default="1" 混用，导致解析失败时抛出 TypeError 而不是清晰的 usage 提示；click 里误用 @click.option 的 is_flag=True 却又给 default 设为字符串，结果 flag 变成布尔值但默认值被忽略。
-
argparse：优先用nargs='?'处理可选值，别依赖default做类型兜底 -
click：所有@click.option都显式写type=...，哪怕只是str，避免隐式转换歧义 - 子命令场景下，
click的@click.group()+@cli.command()结构比argparse.add_subparsers()更易维护
参数校验该放在哪一层？
参数合法性检查不能塞进入口定义里，也不该拖到业务函数开头再 if not path.exists(): raise ValueError(...)。正确位置是「解析后、调用前」——也就是 argparse 的 action 类或 click 的 callback 函数中。
立即学习“Python免费学习笔记（深入）”；
这样做的好处是：错误能统一拦截、提示语能对齐 CLI 习惯（比如 “Error: Invalid path: /foo/bar”），且不污染业务函数签名。否则，同一个路径校验逻辑可能在 3 个命令函数里重复出现，改起来容易漏。
使用场景举例：需要确保 --config 指向的 YAML 文件存在且可读；--port 必须是 1024–65535 范围内的整数；--mode 只接受 "dev" 或 "prod"。
-
argparse：自定义action子类，在__call__里做校验并抛parser.error(...) -
click：写独立函数作为callback，用ctx.abort()终止，不要用raise ValueError - 避免在 callback 里做耗时操作（如网络请求、大文件读取），CLI 入口层应保持轻量
配置加载顺序怎么定才不混乱？
用户期望命令行参数 > 环境变量 > 配置文件 > 默认值，这个优先级必须硬编码进加载逻辑，不能靠文档“建议”。否则会出现：用户明明写了 --timeout 30，程序却读了配置文件里的 timeout: 10，还默默执行了。
性能影响很小，但兼容性很关键。比如某些 CI 环境禁用文件系统访问，此时若配置文件加载失败就直接退出，会阻断整个流程；而环境变量和命令行参数始终可用。
常见错误现象：用 os.getenv() 读环境变量时没设默认值，结果返回 None，后续传给 int() 报 TypeError；或把配置文件路径写死为 ./config.yaml，导致无法通过 --config 覆盖。
- 配置键名统一小写加下划线（如
log_level），对应环境变量用大写加下划线（LOG_LEVEL），命令行参数用短横线（--log-level） - 配置文件加载失败时，仅记录 warning，不中断；除非明确要求（如
--config required.yaml）才报错退出 - 所有配置项最终合并进一个扁平字典，避免嵌套结构，方便业务函数直接取值
为什么 print() 不该出现在核心逻辑里？
命令行工具的输出本质是接口契约：用户靠 stdout 判断成功，靠 stderr 判断错误，靠退出码判断状态。如果业务函数里混着 print("Processing...")，就会污染机器可读输出（比如管道或 JSON 输出），也导致日志级别失控。
真正该做的，是把输出行为抽离成「渲染器」或「格式化器」，由入口层根据 --verbose、--json、--quiet 等开关决定调用哪个。核心逻辑只负责返回数据结构（如 {"status": "ok", "items": [...]}），不碰 sys.stdout。
容易踩的坑：用 logging.info() 打印进度，却忘了配置 handler 输出到 stderr；或在异常处理里用 print(e) 而非 print(str(e), file=sys.stderr)，导致错误信息混进正常输出流。
- 所有面向用户的输出，统一走
print(..., file=sys.stdout)或print(..., file=sys.stderr)，不依赖 logging 配置 - JSON 输出模式下，禁止任何额外文本（包括空行、"Done." 这类提示），只输出合法 JSON
- 进度条、spinner 等动态输出，必须检测
sys.stdout.isatty()，非终端环境下退化为静态日志
