在终端里反复敲 cd、find、tar,最烦的往往不是操作本身有多难,而是长路径写错一次就得重来。把这类重复动作收敛成一个短命令,是很自然的需求。下面这套实现来自一个叫 cua(Command Utility Assistant)的个人小工具,用 Python 写成,把打包、报告合并、服务体检固定成 pack、merge、check 三个子命令。这里按实际落地顺序拆解:argparse 的子命令分发、tarfile 的过滤打包、socket 端口探测、退出码设计,以及安装后命令找不到的排查思路。
一、先定形态:命令行、单文件、配置外置
做成命令行而不是 GUI,核心理由是可组合:命令行工具能被 shell 脚本、cron 定时任务、CI/CD 流程直接调用,比如在构建脚本里执行 cua check,靠返回码决定是否中止后续步骤,这种编程式调用能力 GUI 很难提供。另一方面,工具本身就跑在终端上下文里,不用为了一件小事切到别的窗口,分发也只是一个 Python 文件丢过去。
用 Python 而不是 Bash,关键不在功能而在参数处理。Shell 里靠 $1、$2 顺序取值或用 getopts,一旦出现“指定打包目录”“排除某类文件”“是否上传”这类组合参数,写法会迅速变得绕。标准库 argparse 处理子命令、可选参数和自动生成的 --help 帮助信息都更直接,用户敲 cua --help 就能看到每个子命令的用法。跨平台也是硬需求:macOS 自带 Bash 3.2,Linux 上常见 Bash 5.x,在关联数组和正则支持上存在差异,而 tarfile、subprocess、socket 在三个平台上行为基本一致。
整体结构参考 git、docker 的“一个主命令 + 若干子命令”形态,入口统一、子命令互相隔离。配置不写死在代码里,放在 ~/.cua/config.yaml,首次运行 cua init 生成默认内容,大致如下:
- projects:
- blog: ~/Documents/blog
- app: ~/Work/application
- pack:
- outputs: ~/Backups
- excludes:
- - node_modules
- - .git
- - dist
- check:
- ports: [3306, 6379, 9200]
- directory_max_mb: 2048
复制代码
路径别名、端口列表这类经常变化的信息留在配置里,改配置即可,不必动代码。项目目录按职责拆成主入口 cua.py、commands 包(pack_cmd.py、merge_cmd.py、check_cmd.py)、utils 包(config.py、output.py),依赖只有 PyYAML 一个第三方库,执行 pip install pyyaml 即可;如果是 Python 3.11 以上,也可以改用 tomllib 把配置格式换成 TOML,进一步减少依赖。
二、主入口:用 add_subparsers 做参数分发
- import argparse
- from commands import pack_cmd, merge_cmd, check_cmd
- def main():
- parser = argparse.ArgumentParser(prog="cua", description="Command Utility Assistant")
- subparsers = parser.add_subparsers(dest="command", required=True)
- pack_parser = subparsers.add_parser("pack", help="pack a project directory")
- pack_parser.add_argument("project", help="project alias defined in config")
- pack_parser.add_argument("--exclude", action="append", help="extra exclude patterns")
- pack_parser.add_argument("--no-upload", action="store_true", help="skip upload step")
- merge_parser = subparsers.add_parser("merge", help="merge report files")
- merge_parser.add_argument("directory", help="directory to scan")
- merge_parser.add_argument("--pattern", default="test-report*.md", help="glob pattern to match")
- check_parser = subparsers.add_parser("check", help="check ports and disk usage")
- check_parser.add_argument("--ports", action="append", type=int, help="additional ports to check")
- check_parser.add_argument("--directory", help="directory to check disk usage")
- args = parser.parse_args()
- if args.command == "pack":
- pack_cmd.run(args)
- elif args.command == "merge":
- merge_cmd.run(args)
- elif args.command == "check":
- check_cmd.run(args)
- if __name__ == "__main__":
- main()
复制代码
两个细节值得留意:一是 dest="command",解析后直接用 args.command 判断走哪个分支,分发逻辑很干净;二是 required=True,不加这个参数时,用户只输 cua 不带子命令会静默退出,对命令行工具来说是不良体验。
三、pack 子命令:别名映射、过滤打包、清单生成
pack 分三步。第一步把命令行传入的 project 名称通过配置里的别名映射换成真实路径,同时要处理别名不存在的情况,给出可读的错误提示而不是抛异常。第二步打包,用标准库 tarfile 配合 filter 参数做排除,比在 Shell 里拼 tar 命令更灵活:
- import os
- import tarfile
- from datetime import datetime
- def create_tarball(source_dir, output_dir, branch, excludes=None):
- excludes = excludes or []
- timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
- project_name = os.path.basename(source_dir.rstrip(os.sep))
- filename = f"{project_name}-{timestamp}-{branch}.tar.gz"
- output_path = os.path.join(output_dir, filename)
- def should_exclude(tarinfo):
- for pattern in excludes:
- if pattern in tarinfo.name:
- return None
- return tarinfo
- with tarfile.open(output_path, "w:gz") as tar:
- tar.add(source_dir, arcname=project_name, filter=should_exclude)
- size_mb = os.path.getsize(output_path) / 1024 / 1024
- return output_path, size_mb
复制代码
arcname=project_name 这层包装的作用是让解压后所有文件落在一个以项目名命名的目录里,而不是散在当前目录,看着不起眼,但实际解压时组织清晰很多。文件名带上时间戳和 git 分支,例如 frontend-20250615-143012-master.tar.gz,避免了 final_v2 这类无法追溯的命名。分支名通过 subprocess.check_output 执行 git branch --show-current 取得,这一步是后来补上的:一开始只有日期,等到需要回溯线上版本时,才发现缺分支信息的包根本无法快速定位代码。
第三步生成 manifest.txt 一并写入包内,记录源码目录的文件数量、总大小、Git 分支和打包时间,隔一段时间翻旧包时能快速知道内容是什么。
四、merge 子命令:排序靠文件名,拼接补标题
merge 的逻辑是扫描指定目录、按 glob 模式匹配文件、排序后依次拼接。测试报告通常按日期命名,如 test-report-20250601.md、test-report-20250602.md,字符串排序恰好等于时间顺序,因此直接用 sorted() 即可,不需要额外解析日期。拼接时在每个文件正文前插入一个二级标题,标题内容取去掉扩展名后的文件名,这样合并出来的 markdown 结构清晰,阅读者能一眼看出各段来源,文件头部再生成一份简单目录索引。
五、check 子命令:端口探测与退出码
check 覆盖两个维度:端口是否可连接、指定目录所在磁盘占用是否超过配置阈值。端口用 socket.connect_ex() 判断,比主动 connect 再捕获异常更干净,返回 0 表示可连、非 0 表示不可达:
- import socket
- def is_port_open(port, host="127.0.0.1", timeout=1):
- sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
- sock.settimeout(timeout)
- result = sock.connect_ex((host, port))
- sock.close()
- return result == 0
复制代码
磁盘部分用 shutil.disk_usage() 拿到总量、已用量和剩余量,与配置里的 directory_max_mb 比较即可。结果逐行输出 status: ok 或 status: fail。真正让 check 区别于其他子命令的是退出码:只要有一项不通过,主程序就 sys.exit(1);全部通过则为 0。终端里看不出太大差别,但一旦放进定时任务或 CI,外部脚本仅凭返回码就能判断要不要继续。
性能方面,瓶颈在磁盘 IO 和网络超时而非 Python 执行效率。一个约 5MB 的源码目录,tarfile 压缩不到 2 秒;检查 10 个端口、单端口超时 1 秒,最差也在 10 秒内结束。稳定性上做了两处防御:配置缺失时提示先执行 cua init,而不是抛 traceback;打包目标目录不可写时输出普通文本错误,而不是堆栈。
六、安装成全局命令
在 cua.py 头部加 shebang,赋予执行权限后软链到 /usr/local/bin:
- #!/usr/bin/env python3
- chmod +x cua.py
- sudo ln -s "$(pwd)/cua.py" /usr/local/bin/cua
复制代码
重新开终端执行 cua --help,能列出全部子命令说明就算装好了。这种方式简单稳定,适合个人使用;需要多用户共享或自动升级时,再考虑用 pip 的 entry_points 打包成正式分发包。
七、常见问题与排查
1. 提示 command not found。多数情况出在软链目标或 Python 解释器上。先确认软链是否建成功,再直接运行 /usr/local/bin/cua 看真实报错;如果提示找不到 python3,检查 shebang 用的是 python3 还是绝对路径,以及当前 shell 下 which python3 指向哪里。跨机器时解释器路径不一致,是这类问题最常见的根因。
2. argparse 的三个坑。其一,子命令参数若与主命令参数重名,解析结果可能被主命令拦截,子命令收不到值,取名时加前缀(如 --no-upload)可规避。其二,action="append" 的参数默认值是 None 而不是空列表,代码里直接 for 循环 args.ports 会抛 TypeError,解析后要先补 if args.ports is None: args.ports = []。其三,子命令的帮助信息默认不显示全局参数,希望所有子命令都识别的公共参数(例如 --verbose)应定义在主 parser 上。
3. 配置文件找不到导致项目路径无效。默认配置在 ~/.cua/config.yaml,但在 Windows 的 Git Bash 里 HOME 不一定指向 C:\Users\用户名,可能被改成 /tmp 之类的路径。处理办法是代码里不直接使用 ~,改用 Path.home() 获取主目录,并用 os.path.expanduser 统一展开配置中所有含 ~ 的路径,这样各平台解析结果一致。
4. 交互式选择要限定触发条件。pack 支持第二个参数传入目录路径时,若当前位于 git 仓库内,就列出最近几个 tag 让用户选择版本,用 input() 加循环校验实现简单菜单。但交互逻辑不能混进核心流程,否则工具无法用于无人值守场景,应封装成独立函数,仅在检测到标准输入是 TTY 时触发,脚本调用时直接走默认值。
八、与现有工作流整合
单点使用之外,价值主要来自整合。在 git 的 post-commit 钩子里可以接上打包逻辑;CI 配置里在测试步骤之后加一句 cua merge ./reports && cua check,借助退出码判断流程是否继续。整合时建议从一条高频主流程开始,比如先把打包做透,再加第二个场景,一次塞进五六个功能往往会每个都做得不深,最后整个工具被闲置。
小结:这类个人效率工具不需要一开始就追求大而全。找到重复频率最高、最容易出错的那个场景,封装到足够简单,哪怕只有一个子命令,只要天天在用就比一堆半成品有价值。输出格式值得花时间打磨,正常信息、警告和错误用不同颜色区分,扫一眼终端就能判断结果是否正常;文档也要顺手写,参数说明和配置说明不仅是换机器后恢复环境的依据,也是一个月后重新读代码时理解设计意图的线索。 |