2. 命令行参数解析：用argparse优雅地处理用户输入

说实话，我见过太多人写自动化脚本时，直接把参数硬编码在代码里。改个路径要翻源码，换个环境要改变量。嗯，这种做法在你自己用的时候还行，一旦交给别人用，或者放到CI/CD流水线里，就彻底崩了。

我个人习惯是：任何可能变化的配置，都通过命令行参数传入。今天我们就聊聊Python标准库里的argparse，它是我最常用的参数解析工具。

2.1 为什么需要argparse？

你想想看，一个构建脚本通常需要知道：

• 构建哪个环境？开发、测试还是生产？
• 输出目录在哪？
• 要不要清理缓存？
• 日志级别怎么设？

用sys.argv手动解析？太原始了。自己写正则匹配？容易出bug。argparse帮你把参数定义、类型校验、帮助信息、错误提示全包了。

2.2 基础用法：三步走

说白了就三步：创建解析器、添加参数、解析参数。看个最简单的例子：

import argparse

# 第一步：创建解析器
parser = argparse.ArgumentParser(description='自动化构建工具')

# 第二步：添加参数
parser.add_argument('--env', type=str, default='dev',
                    help='构建环境：dev/test/prod')
parser.add_argument('--output', type=str, default='./dist',
                    help='输出目录')
parser.add_argument('--clean', action='store_true',
                    help='构建前清理缓存')

# 第三步：解析参数
args = parser.parse_args()

print(f'环境：{args.env}')
print(f'输出目录：{args.output}')
print(f'是否清理：{args.clean}')

运行效果：

$ python build.py --env prod --output ./release --clean
环境：prod
输出目录：./release
是否清理：True

$ python build.py --help
usage: build.py [-h] [--env ENV] [--output OUTPUT] [--clean]

自动化构建工具

options:
  -h, --help       show this help message and exit
  --env ENV        构建环境：dev/test/prod
  --output OUTPUT  输出目录
  --clean          构建前清理缓存

2.3 参数类型：不只是字符串

我在项目中遇到过一个问题：有人传了--threads abc，结果程序在运行时才报错。用argparse的type参数，可以在解析阶段就做类型校验。

参数类型	示例	说明
字符串	type=str	默认类型，不需要显式指定
整数	type=int	自动校验是否为合法整数
浮点数	type=float	用于版本号、超时时间等
布尔值	action='store_true'	开关型参数
文件路径	type=Path	Python 3.4+，自动处理路径

parser.add_argument('--port', type=int, default=8080,
                    help='服务端口号')
parser.add_argument('--timeout', type=float, default=30.0,
                    help='超时时间（秒）')
parser.add_argument('--config', type=Path,
                    help='配置文件路径')

2.4 必选参数与可选参数

argparse默认把--开头的参数视为可选参数。那必选参数怎么办？两种方式：

• 位置参数：不带--前缀，按顺序解析
• required=True：让可选参数变成必选

# 位置参数示例
parser.add_argument('project_name', type=str,
                    help='项目名称（必填）')
parser.add_argument('--env', required=True,
                    help='构建环境（必填）')

args = parser.parse_args()
print(f'项目：{args.project_name}')
print(f'环境：{args.env}')

运行效果：

$ python build.py myapp --env prod
项目：myapp
环境：prod

$ python build.py --env prod
usage: build.py [-h] --env ENV project_name
build.py: error: the following arguments are required: project_name

我个人更推荐用required=True，因为位置参数在帮助信息里不够直观，用户容易搞错顺序。

2.5 参数默认值与choices限制

你想想看，如果用户传了--env staging，但你的脚本只支持dev/test/prod，那肯定要报错。用choices可以限制参数取值范围：

parser.add_argument('--env', type=str, default='dev',
                    choices=['dev', 'test', 'prod'],
                    help='构建环境')
parser.add_argument('--log-level', type=str, default='INFO',
                    choices=['DEBUG', 'INFO', 'WARNING', 'ERROR'],
                    help='日志级别')

这样用户传错值时，argparse会直接提示可选值：

$ python build.py --env staging
usage: build.py [-h] [--env {dev,test,prod}] [--log-level {DEBUG,INFO,WARNING,ERROR}]
build.py: error: argument --env: invalid choice: 'staging' (choose from 'dev', 'test', 'prod')

2.6 实战：一个完整的构建脚本参数设计

好了，我们把上面的知识点串起来，写一个真正能用的构建脚本参数解析：

import argparse
from pathlib import Path

def create_build_parser():
    parser = argparse.ArgumentParser(
        description='自动化构建工具 v2.0',
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog='示例: python build.py --env prod --clean --threads 4'
    )

    # 必选参数
    parser.add_argument('project', type=str,
                        help='项目名称')

    # 构建相关
    parser.add_argument('--env', type=str, default='dev',
                        choices=['dev', 'test', 'prod'],
                        help='构建环境 (默认: dev)')
    parser.add_argument('--output', type=Path, default=Path('./dist'),
                        help='输出目录 (默认: ./dist)')
    parser.add_argument('--clean', action='store_true',
                        help='构建前清理输出目录')

    # 性能相关
    parser.add_argument('--threads', type=int, default=4,
                        help='并行构建线程数 (默认: 4)')
    parser.add_argument('--no-cache', action='store_true',
                        help='禁用构建缓存')

    # 调试相关
    parser.add_argument('--verbose', action='store_true',
                        help='输出详细日志')
    parser.add_argument('--dry-run', action='store_true',
                        help='只打印要执行的命令，不实际执行')

    return parser

if __name__ == '__main__':
    parser = create_build_parser()
    args = parser.parse_args()

    print(f'项目: {args.project}')
    print(f'环境: {args.env}')
    print(f'输出目录: {args.output}')
    print(f'清理缓存: {args.clean}')
    print(f'线程数: {args.threads}')
    print(f'禁用缓存: {args.no_cache}')
    print(f'详细日志: {args.verbose}')
    print(f'模拟运行: {args.dry_run}')

这个设计覆盖了日常构建的常见场景。你想想看，是不是比在代码里写死配置要灵活得多？

2.7 避坑指南

最后分享几个我踩过的坑：

• 短参数冲突：-c被多个参数使用会报错。我建议只在常用参数上用短参数，比如-e给--env，-o给--output。
• 布尔参数的陷阱：--no-cache和--cache不要同时存在，用action='store_true'配合--no-cache就够了。
• 路径处理：用Path类型而不是字符串，可以避免跨平台路径分隔符的问题。
• 帮助信息格式化：如果帮助文本很长，用RawDescriptionHelpFormatter可以保留换行格式。

嗯，argparse的内容就这些。下一章我们会聊怎么用这些参数去驱动实际的构建流程，包括调用外部命令、处理错误、记录日志等。到时候你会发现，今天学的参数解析是整套自动化体系的基石。