argparse 是命令行接口契约工具，非装饰器；nargs 值需慎用，如 '*' 必须置末尾；子命令应独立定义并设 dest；type 应为校验+转换函数；help 是 API 文档核心，需全覆盖且格式清晰。
argparse 不是“优雅”的装饰，而是命令行接口的契约工具——用错地方或乱设参数，反而让脚本更难维护、更难调试。
为什么 add_argument 的 nargs 值总让人踩坑
最常见的误用是把 nargs='*' 当成“可选多个参数”的万能解，结果发现它会吞掉后续所有参数（包括本该是其他选项的），甚至让 --help 显示混乱。
-
nargs='*'：匹配 0 个或多个，但必须放在参数列表末尾，且不能和nargs='+'或位置参数混用 -
nargs='+'：至少 1 个，适合强制要求输入文件列表，比如python script.py --files a.txt b.txt c.txt -
nargs=2：明确要两个值，如--range 10 20，解析后是[10, 20]，不是元组也不是字符串拼接 - 如果参数带
default且nargs不为'?'，记得显式设const（尤其配合action='store_const'时）
子命令（subparsers）不是炫技，而是避免写一堆 if arg.cmd == 'xxx'
当脚本承担多个职责（如 deploy、rollback、status），硬编码分支逻辑会让 --help 失效、参数校验松散、错误提示模糊。
- 每个子命令应有自己的
add_parser()，并独立调用add_argument()，不要复用主 parser 的参数 - 务必给子命令设置
dest（如subparsers.add_parser('deploy', dest='cmd')），否则无法在args.cmd中拿到命令名 - 子命令不支持全局
add_argument(..., action='store_true')自动透传，需显式在每个子 parser 中添加或通过set_defaults()统一注入 - 别忘了调用
parser.set_defaults(func=...)绑定执行函数，而不是靠if args.cmd == 'x'手动分发
type 参数不是类型转换器，而是验证+预处理入口
type=int 看似简单，但它会在解析阶段抛出 ArgumentTypeError，而这个异常默认被 argparse 吞掉、只打印 usage。你真正需要的是可控的校验逻辑。
立即学习“Python免费学习笔记（深入）”；
- 用自定义函数替代内置类型：例如
type=valid_port，函数内 raiseargparse.ArgumentTypeError('port must be 1024–65535') -
type函数接收原始字符串，返回转换后值（如Path对象、datetime实例），不要在其中做 IO 或网络请求 - 避免用
type=lambda x: x.strip()，它无法提供有意义的错误信息；改用显式函数 +help描述 - 如果需同时做类型转换和范围检查，优先封装进
type函数，而非依赖action或后续代码校验
help 文本不是可有可无的注释，而是用户第一眼看到的 API 文档
很多脚本的 --help 输出全是 optional arguments: 和空行，因为开发者把 help 当成“补充说明”，而不是接口契约的一部分。
- 每个
add_argument()都应有help，哪怕只有一句话；缺失时 argparse 会显示None或空白 - 用
metavar控制 help 中的占位符名（如metavar='FILE'→--config FILE），别让它默认显示大写的参数名 - 长帮助文本中换行会被压缩成空格，如需保留格式，用
formatter_class=argparse.RawDescriptionHelpFormatter -
epilog和description支持%(prog)s占位符，比硬编码脚本名更健壮
最常被忽略的其实是 allow_abbrev=False —— 默认开启缩写（--ver 匹配 --version），但在多命令、多选项场景下极易引发歧义，上线前务必关掉。
