用Python写一个可复用的命令行小工具：从argparse到日志与异常处理

很多开发者都写过一次性脚本：复制一段代码，改几个参数，跑完就扔掉。下一次遇到类似需求，又要从头翻找。把常用操作沉淀成一个可复用的命令行小工具，成本并不高，收益却很实在。本文用 Python 标准库做一个例子，目标是参数清晰、日志可查、出错不崩、别人拿到就能用。

先定好工具的边界。一个好的小工具只做一件事，比如批量重命名文件、汇总日志中的错误行、把 CSV 转成简单的统计表。功能越聚焦，参数越少，维护成本越低。开始写代码之前，先写一句话说明：这个工具的输入是什么，输出是什么，失败时应该发生什么。这句话后来可以直接变成帮助信息。

参数解析优先使用 argparse。它能自动生成帮助信息，自动校验必填项，还能把类型转换和默认值集中管理。建议把参数分成三类：必需的位置参数或选项、常用选项、调试选项。文件路径用 Path 处理，不要自己拼字符串；数值参数用 type=int 或 type=float，让解析器先拦截非法输入；布尔开关用 store_true，避免用户还要传 true 或 false。

日志比 print 更适合工具。print 只能输出到屏幕，日志可以同时写文件、分级别、加时间戳。建议默认输出 INFO，调试时用 --verbose 切换到 DEBUG，错误只输出 ERROR。日志格式里至少包含时间和级别，写文件时再加上模块名。不要在正常流程里用 print 输出结果数据，结果应该走标准输出或写文件，日志走标准错误，这样两者不会混在一起，也方便后续用管道处理。

异常处理要分层。用户输入错误，比如文件不存在、格式不对，应该给出明确的提示并以非零退出码结束，不要抛出长长的堆栈。程序内部错误则可以记录堆栈，便于排查。常见做法是：在主函数里捕获预期的异常，打印一句人能看懂的话，返回对应的退出码；未预期的异常交给日志记录完整信息。退出码也有讲究：0 表示成功，2 表示参数错误，1 表示运行失败，这样脚本和自动化流程才能判断结果。

结构上建议把逻辑拆成三个函数：parse_args 负责参数，run 负责核心逻辑，main 负责组装和异常处理。核心逻辑不要直接读全局变量，也不要在函数里偷偷打印结果，而是返回数据或写入目标文件。这样以后想把命令行工具改成库、改成定时任务，改动都很小。入口处用 if name == ‘main’: 调用 main，并用 sys.exit 传递退出码。

最后别忘了写一个简单的使用示例，放在帮助信息或文档开头。比如先准备一小份测试数据，跑一次正常流程，再跑一次错误输入，确认提示和退出码都符合预期。把这个示例保存成脚本或文档，团队成员就不需要再猜用法。一个小工具不在于代码量，而在于边界清楚、提示友好、行为可预测。把这三点做好，你的脚本就能从一次性代码，变成真正可以复用的工具。