调试这件事很多人一开始会迷信断点后来又会迷信日志框架但我在实际项目里摸爬滚打这么多年最后发现最快解决问题的往往是那个最简单、最“返祖”的手段print。Python 生态里有个很有意思的库名字就叫caveman中文直译就是“穴居人”。这个命名本身就透露了它的态度抛弃花哨复杂的调试工具链回到最原始的打印输出用最粗暴直接的方式把代码内部状态“看”明白。它不是什么大而全的可观测平台就是一个让你在代码里随手插桩、快速看到现场的小工具特别适合写脚本、搞数据清洗、调接口时那种“不对劲但说不清哪里不对劲”的时刻。这篇文章我把caveman的玩法从头到尾捋一遍包括它的核心函数、输出格式、环境变量开关、真实调试案例以及我实际使用中踩过的坑。不管你是刚接触 Python 的初学者还是被复杂调用链折磨得头大的老手看完应该都能直接把这套思路搬到自己的项目里。1. caveman 到底是个什么“穴居人”1.1 一个为 print 调试而生的 Python 小工具caveman是一个纯 Python 库安装很简单pip install caveman装完之后不需要配置任何东西只要在代码里导入并调用即可from caveman import caveman def calc_total(prices, discount): total sum(prices) caveman(total after sum, total) total total * (1 - discount) caveman(total after discount, total) return total运行这段代码你会在控制台看到类似这样的输出/path/to/your_script.py:6 in calc_total: total after sum 100 /path/to/your_script.py:8 in calc_total: total after discount 85.0注意它不只是打印你传进去的消息和值还会自动带上文件名、行号、函数名。这一点在调试时非常关键因为项目一大你的print(total is, total)可能散落十几个看到屏幕上飘过的数字你根本不知道是哪里打印的。caveman用这种“自带位置信息”的打印帮你省掉了最烦人的溯源过程。它适合的场景也很清楚你正在写一个脚本或者正处于开发阶段想快速验证逻辑你遇到一个偶发 Bug想在不打断思路的前提下边跑边看你维护的代码是别人写的里面塞满了调试逻辑你想快速搞清楚每条路径走到了哪里。这些场景下caveman的体验比打开 pdb 断点一步一步按要顺滑得多因为你不需要提前知道“问题大概在哪一行”只需要在几个关键位置插上标记跑一遍就能看到数据在全链路上的变化。1.2 为什么“原始”反而更好用我见过不少同事一遇到 Bug 就立刻打开 IDE 断点然后人肉单步调试。这个做法本身没有错但它有几个隐性成本第一断点调试会打断程序的自然运行节奏尤其当你处理的是多线程、异步任务、或者定时脚本时断点一停上下文可能就变了复现问题变得很困难。第二断点调试通常需要你能“定位到大概位置”如果一个问题发生在深层调用链里你要么一层层打断点要么按“继续执行”按到手酸。第三断点调试对运行环境有要求远程服务器、容器里、命令行工具下往往很难方便地操作 IDE 的调试器。日志框架是一个更高阶的方案但同样有学习成本而且问题在于“重”你得先设计 logger 名字、设置 handler、规划 level等你把这一套东西搭完那种“随手看看变量”的轻量感已经没了。更关键的是日志通常记录的是“业务事件”不会自动带上某个局部变量的值你想看变量还得手动在日志消息里拼接。caveman就很聪明地把“print 的随意 ”和“日志的规范”结合了一下。它不需要初始化不需要配置一行代码就能打印出带文件行号函数名的信息比裸 print 好用太多又比日志框架轻太多。像生活里那些“返祖”的解决方案一样——比如复杂电路板出问题时老工程师直接拿万用表两两点一下就能定位故障——最原始的手段往往直击要害因为你跳过了所有中间层的噪音。2. 核心机制拆解caveman 是怎么工作的2.1 关键函数与输出格式caveman对外暴露的核心 API 其实非常少主要以caveman()函数为主。它的签名大致是caveman(*args, **kwargs)你可以像用print一样传多个值进去caveman(user_id, user.id, status, status)输出的时候它会把args里每对“key, value”都展示出来。这个设计比单纯打印(user.id, status)语义清晰得多一眼就能看出哪个值对应哪个变量。此外它还支持一些额外参数来控制行为常用的有参数作用示例sink指定输出目标默认是sys.stderr可以改成输出到文件caveman(msg, variable, sinkopen(/tmp/debug.log, a))timer打印自某个参考点以来的耗时常用于性能排查caveman(batch done, batch_size, timerTrue)color是否使用 ANSI 颜色输出默认会自动检测终端caveman(warn, value, colorFalse)输出格式上caveman默认的每一行都包含这样几部分信息文件路径:行号 in 函数名: 你传入的消息和变量这个自动获取文件名、行号、函数名的能力是它和print最大的区别。实现原理也不复杂Python 本身提供了inspect模块可以拿到当前的调用栈信息。caveman内部会往上查一层调用栈找到谁调用了它然后把那个位置的filename、lineno、function拿过来格式化输出。这也是为什么它在任何普通 Python 环境里都能工作不需要依赖 IDE 或专门的运行时因为这只是标准库能力的一个巧妙封装。2.2 环境变量与开关控制开发时插桩一时爽测试完了如果忘了删这些调试打印就会污染正式输出。这个问题我在真实项目里碰到过很多回一个脚本跑完屏幕上全是调试信息日志文件里也混入了大量临时输出运维同事一脸问号。caveman提供了一个比较优雅的方案——通过环境变量做总开关。你在代码里保留所有的caveman调用点但要控制它们是否生效时设置export CAVEMAN_LOG_LEVELERROR如果不希望看到任何输出可以把级别设为一个不匹配的值或直接在调用处搭配条件判断。更常见的做法是把调试行为绑定到环境变量上import os from caveman import caveman DEBUG os.environ.get(DEBUG_MODE) 1 def process_item(item): if DEBUG: caveman(processing, item.id, item.value) # 正常业务逻辑这种写法特别适合那种“运行在服务器上的脚本”或“定时任务”你平时让它安静地跑一旦要排查问题就在执行命令前加一个DEBUG_MODE1立刻就能看到关键节点的内部状态排查完再恢复正常执行。也就是说caveman并不是一个“污染代码”的累赘反而可以变成一套轻量级的可插拔观测开关。2.3 基于调用栈的定位原理前面说到caveman能自动显示行号和函数名这里稍微展开讲一下原理。Python 的sys._getframe和inspect.currentframe可以拿到当前栈帧栈帧对象的f_back指向调用者。caveman的实现就是把自己这个函数从栈里摘出去看上一帧是谁然后从那个帧对象里读取f_code.co_filename、f_lineno、f_code.co_name等信息。这个思路其实可以扩展。你自己写代码时如果想实现一个类似的小工具也可以照搬这套逻辑import sys def debug_print(msg): frame sys._getframe(1) info f{frame.f_code.co_filename}:{frame.f_lineno} in {frame.f_code.co_name}: {msg} print(info, filesys.stderr)不过caveman显然比这做得更完整它把变量格式化、颜色、sink、定时器等常见需求都封装好了。理解这层原理的好处是当你在一个不满足“常规调用”的场景里使用它时比如被装饰器包装过、在生成器里、在异步回调里你会更容易预测输出是否符合预期。有一点要提醒不要对打印出的行号 100% 死磕在装饰器或嵌套函数里行号可能指向调用点的位置而不是逻辑核心行的位置但这对于定位问题完全足够了。3. 实操走一遍用 caveman 排查一个真实 Bug3.1 场景构建一个分页参数异常的数据脚本为了演示caveman的实际用法我构造一个非常常见的业务场景从一个文件中读取订单数据按用户分组给每个用户计算分页后的订单摘要。import json from collections import defaultdict # 模拟原始订单数据 raw_data [ {user_id: u1, order_id: o1, amount: 100}, {user_id: u1, order_id: o2, amount: 250}, {user_id: u2, order_id: o3, amount: 60}, {user_id: u3, order_id: o4, amount: 520}, ] def load_orders(source): # 这里简化成直接返回静态数据 return raw_data def group_by_user(orders): groups defaultdict(list) for order in orders: groups[order[user_id]].append(order) return groups def build_page_summary(groups, page_size2): summaries [] for user_id, orders in groups.items(): total sum(order[amount] for order in orders) page_count (len(orders) page_size - 1) // page_size summaries.append({ user_id: user_id, total_amount: total, page_count: page_count, order_count: len(orders), }) return summaries def run(): orders load_orders(orders.json) groups group_by_user(orders) result build_page_summary(groups, page_size2) print(json.dumps(result, indent2, ensure_asciiFalse)) if __name__ __main__: run()假设现在运行结果是[ { user_id: u1, total_amount: 350, page_count: 2, order_count: 2 }, { user_id: u2, total_amount: 60, page_count: 2, order_count: 2 }, { user_id: u3, total_amount: 520, page_count: 1, order_count: 1 } ]发现问题了吗u3只有 1 条订单但order_count显示是 1page_count算出来是 1这看起来没错。问题出在u2它只有 1 条订单但是输出里order_count却是 2。此时如果不看代码单从输出猜原因可能会一头雾水明明原始数据里u2只有一条记录为什么分组后变成两条这就是caveman该上场的时候了。3.2 从症状到定位插桩看数据流向我从load_orders开始在关键节点插入cavemanfrom caveman import caveman def load_orders(source): orders raw_data caveman(load_orders returned, orders) return orders def group_by_user(orders): caveman(group_by_user input, orders) groups defaultdict(list) for order in orders: groups[order[user_id]].append(order) caveman(group_by_user groups, dict(groups)) return groups重新运行后输出会是这样/path/to/debug_demo.py:15 in load_orders: load_orders returned [{user_id: u1, order_id: o1, amount: 100}, {user_id: u1, order_id: o2, amount: 250}, {user_id: u2, order_id: o3, amount: 60}, {user_id: u3, order_id: o4, amount: 520}] /path/to/debug_demo.py:20 in group_by_user: group_by_user input [{user_id: u1, order_id: o1, amount: 100}, {user_id: u1, order_id: o2, amount: 250}, {user_id: u2, order_id: o3, amount: 60}, {user_id: u3, order_id: o4, amount: 520}] /path/to/debug_demo.py:25 in group_by_user: group_by_user groups {u1: [{user_id: u1, order_id: o1, amount: 100}, {user_id: u1, order_id: o2, amount: 250}], u2: [{user_id: u2, order_id: o3, amount: 60}], u3: [{user_id: u3, order_id: o4, amount: 520}]}到这一步原始数据和分组结果都符合预期u2只有一条订单。问题一定出在build_page_summary里。继续插桩def build_page_summary(groups, page_size2): summaries [] for user_id, orders in groups.items(): caveman(processing user, user_id, orders, orders) total sum(order[amount] for order in orders) page_count (len(orders) page_size - 1) // page_size caveman(computed, user_id, order_count, len(orders), page_count, page_count) summaries.append({...}) return summaries输出会显示每组处理时orders的长度其实是 1、1、1那为什么最终 JSON 里u2的order_count是 2此时你可能怀疑是summaries.append或后续打印环节的问题。再在返回前插一个caveman看summariescaveman(summaries before return, summaries)很容易就会发现summaries本身三个用户的order_count都是 111。问题不在计算逻辑而在于run()函数里打印结果时可能拿错了变量或者我为了演示构造了一个 局部变量覆盖 的坑。真实的 Bug 可能多种多样但核心套路是一样的通过caveman在输入端、处理中、输出端各放一个观察点数据在哪个环节发生了“变异”一眼就能看出来。这是caveman最大的使用心得不要只在出错的地方打印要在数据进入一个函数时、离开一个函数时、循环体内的关键分支处都打印一遍然后把整个过程跑一遍你会得到一张“数据流动轨迹图”。这比守着某一个点反复猜要高效得多。3.3 在 Web 服务和自动化任务里怎么用除了普通脚本caveman在 Web 服务和自动化任务里也非常好用。举一个实际案例我曾经维护过一个 Flask 接口用户反馈某个订单状态总是算错。代码是别人写的调用链横跨三个模块路由函数 - 订单服务 - 状态机转换。当时我也没有把握问题在哪一层于是直接在路由入口、服务入口、状态机转换三个位置各加了一行cavemanapi.route(/orders/order_id/status) def get_order_status(order_id): caveman(route entry, order_id) result order_service.get_status(order_id) caveman(route exit, order_id, result) return result因为 Flask 的请求线程每次处理一个请求只要同时只有一个请求在跑caveman输出和请求的对应关系是清晰的。跑一次测试请求控制台就清清楚楚地列出整个调用链上每个环节的状态变化。问题最后定位在状态机里一个参数传递错误而没有caveman的话我可能还得写一堆临时日志、重启服务、重放请求才能看到内部状态。在 Celery 任务里用法也类似。定时任务出现数据异常时把caveman加在任务函数开头把任务参数、数据库查询结果、中间计算结果都打印出来然后手动执行一次任务观察输出。由于任务通常是一次性运行的caveman的输出不会像 Web 高并发下那样交错混乱反而非常直观。生产环境里当然不建议保留大量caveman输出那怎么办我一般把调试代码用环境变量包一层或者全部集中在某个函数里排查问题时打开一个开关就能复现观测问题解决后再关闭。这个过程可以做得很快比写正式日志再发布一次要省太多时间。4. 常见问题与避坑指南4.1 忘记移除调试语句怎么办很多人担心调试时插了上百个caveman最后清理不干净。我的建议是不要靠“记住”来清理而是靠机制来控制。一种做法是全局开关用一个自定义包装器# debug_helper.py import os from caveman import caveman as _caveman DEBUG os.environ.get(APP_DEBUG) 1 def dbg(*args, **kwargs): if DEBUG: _caveman(*args, **kwargs)然后代码里统一从debug_helper导入dbg而不是直接使用caveman。这样只要生产环境不设置APP_DEBUG1代码里残留再多的dbg调用也是空操作不会影响性能也不会污染输出。检查代码时你只需要搜一下dbg(就能清理干净。4.2 生产环境误开输出的风险caveman默认输出到sys.stderr如果你在一个高并发的 Web 服务里开了大量调试输出轻则把日志文件撑爆重则因为频繁 I/O 拖慢响应速度。我在某个项目里就遇到过同事在循环里插了个调试打印循环一万次每次输出几百字节结果接口响应时间从 50ms 变成 800ms排查了半天才发现是调试输出导致的。所以在生产环境务必遵循几个原则调试开关默认关闭只有需要排查时临时打开不要在高频循环内调用caveman如果要调用加一个采样条件打开调试开关时把sink指到一个独立文件避免和业务日志混在一起排查完成后立刻关闭开关并清理临时文件4.3 caveman 与断点、logging 怎么配合caveman不能完全替代断点调试和正式日志它与二者应该是配合关系。我的工作流一般是先用caveman快速锁定问题的大致范围再在有疑问的那个小区域里用 IDE 断点单步执行最后修复完用正式的logging为关键业务过程留下可追踪的记录。有一个场景特别适合caveman配合断点当你不知道某个变量在某个分支是否被赋值时直接打断点可能十次有八次没走到而用caveman搭一个临时探针跑一遍全流程看哪些探针亮过、哪些没亮你立刻就知道分支覆盖情况。这体验很像用一个简单的示波器先看信号大致长什么样再决定要不要拿逻辑分析仪去深究细节。提示caveman输出默认带颜色在终端里看很醒目但如果你的日志转到文本文件最好设置colorFalse否则文件里会残留一堆 ANSI 转义序列比如\x1b[31m读起来很痛苦。4.4 遇到不输出或格式化错乱时的排查有人会遇到“caveman没生效”的情况仔细看通常是下面几个原因环境变量控制没生效代码里包了if DEBUG而 DEBUG 被计算为 False在多线程下输出交错但caveman本身没问题只是多个线程在同一个终端里同时打印显得乱在 Jupyter Notebook 或某些 IDE 内置控制台里ANSI 颜色转义被原样输出看起来像乱码用colorFalse解决还有一个我自己踩过的坑把caveman用在functools.wraps装饰过的函数内部时行号会指向装饰器内部而不是业务函数内部。这是因为caveman获取调用栈时拿到了装饰器那一帧导致打印的 “函数名” 是装饰器的包装函数名。如果遇到输出里的函数名和预期不符不用慌直接看行号对应的代码文件位置即可本质不影响定位。5. 一些个人经验用caveman这几年我最大的感受是调试工具最重要的不是功能多强大而是“在你想用的那一刻能不能立刻用上”。断点调试要开 IDE、日志系统要配置、链路追踪更是要搭一整套基础设施这些在大型系统里都是必需的但在日常开发、快速验证、临时排查这些场景里它们都太重了。caveman就像一个随身带的放大镜虽然比不了显微镜和 CT 机但当你只是要看清楚指甲盖上的纹路时它是最顺手的选择。再分享一个小技巧我习惯在项目里定义一个debug_hook.py把caveman的开关、输出目标、格式统一封装同时给它起一个更短的名字see代码里写起来很顺手。# debug_hook.py import os from caveman import caveman as _see ENABLED os.environ.get(DEBUG_CAVEMAN, 0) 1 def see(*args, **kwargs): if not ENABLED: return kwargs.setdefault(color, False) _see(*args, **kwargs)有了这个薄封装调试完只需要检查代码里有多少个see(再决定是清理还是保留。保留也无所谓因为默认不输出对生产环境完全无副作用。如果你也想试试这种“返祖但高效”的调试方式我建议别一次插太多探针先插两三个关键节点跑一遍观察输出再根据结果决定下一个探针放哪像盲人摸象一样一步一步摸完整个流程最后你会对整个系统的数据流有特别清晰的理解。
调试这件事很多人一开始会迷信断点后来又会迷信日志框架但我在实际项目里摸爬滚打这么多年最后发现最快解决问题的往往是那个最简单、最“返祖”的手段print。Python 生态里有个很有意思的库名字就叫caveman中文直译就是“穴居人”。这个命名本身就透露了它的态度抛弃花哨复杂的调试工具链回到最原始的打印输出用最粗暴直接的方式把代码内部状态“看”明白。它不是什么大而全的可观测平台就是一个让你在代码里随手插桩、快速看到现场的小工具特别适合写脚本、搞数据清洗、调接口时那种“不对劲但说不清哪里不对劲”的时刻。这篇文章我把caveman的玩法从头到尾捋一遍包括它的核心函数、输出格式、环境变量开关、真实调试案例以及我实际使用中踩过的坑。不管你是刚接触 Python 的初学者还是被复杂调用链折磨得头大的老手看完应该都能直接把这套思路搬到自己的项目里。1. caveman 到底是个什么“穴居人”1.1 一个为 print 调试而生的 Python 小工具caveman是一个纯 Python 库安装很简单pip install caveman装完之后不需要配置任何东西只要在代码里导入并调用即可from caveman import caveman def calc_total(prices, discount): total sum(prices) caveman(total after sum, total) total total * (1 - discount) caveman(total after discount, total) return total运行这段代码你会在控制台看到类似这样的输出/path/to/your_script.py:6 in calc_total: total after sum 100 /path/to/your_script.py:8 in calc_total: total after discount 85.0注意它不只是打印你传进去的消息和值还会自动带上文件名、行号、函数名。这一点在调试时非常关键因为项目一大你的print(total is, total)可能散落十几个看到屏幕上飘过的数字你根本不知道是哪里打印的。caveman用这种“自带位置信息”的打印帮你省掉了最烦人的溯源过程。它适合的场景也很清楚你正在写一个脚本或者正处于开发阶段想快速验证逻辑你遇到一个偶发 Bug想在不打断思路的前提下边跑边看你维护的代码是别人写的里面塞满了调试逻辑你想快速搞清楚每条路径走到了哪里。这些场景下caveman的体验比打开 pdb 断点一步一步按要顺滑得多因为你不需要提前知道“问题大概在哪一行”只需要在几个关键位置插上标记跑一遍就能看到数据在全链路上的变化。1.2 为什么“原始”反而更好用我见过不少同事一遇到 Bug 就立刻打开 IDE 断点然后人肉单步调试。这个做法本身没有错但它有几个隐性成本第一断点调试会打断程序的自然运行节奏尤其当你处理的是多线程、异步任务、或者定时脚本时断点一停上下文可能就变了复现问题变得很困难。第二断点调试通常需要你能“定位到大概位置”如果一个问题发生在深层调用链里你要么一层层打断点要么按“继续执行”按到手酸。第三断点调试对运行环境有要求远程服务器、容器里、命令行工具下往往很难方便地操作 IDE 的调试器。日志框架是一个更高阶的方案但同样有学习成本而且问题在于“重”你得先设计 logger 名字、设置 handler、规划 level等你把这一套东西搭完那种“随手看看变量”的轻量感已经没了。更关键的是日志通常记录的是“业务事件”不会自动带上某个局部变量的值你想看变量还得手动在日志消息里拼接。caveman就很聪明地把“print 的随意 ”和“日志的规范”结合了一下。它不需要初始化不需要配置一行代码就能打印出带文件行号函数名的信息比裸 print 好用太多又比日志框架轻太多。像生活里那些“返祖”的解决方案一样——比如复杂电路板出问题时老工程师直接拿万用表两两点一下就能定位故障——最原始的手段往往直击要害因为你跳过了所有中间层的噪音。2. 核心机制拆解caveman 是怎么工作的2.1 关键函数与输出格式caveman对外暴露的核心 API 其实非常少主要以caveman()函数为主。它的签名大致是caveman(*args, **kwargs)你可以像用print一样传多个值进去caveman(user_id, user.id, status, status)输出的时候它会把args里每对“key, value”都展示出来。这个设计比单纯打印(user.id, status)语义清晰得多一眼就能看出哪个值对应哪个变量。此外它还支持一些额外参数来控制行为常用的有参数作用示例sink指定输出目标默认是sys.stderr可以改成输出到文件caveman(msg, variable, sinkopen(/tmp/debug.log, a))timer打印自某个参考点以来的耗时常用于性能排查caveman(batch done, batch_size, timerTrue)color是否使用 ANSI 颜色输出默认会自动检测终端caveman(warn, value, colorFalse)输出格式上caveman默认的每一行都包含这样几部分信息文件路径:行号 in 函数名: 你传入的消息和变量这个自动获取文件名、行号、函数名的能力是它和print最大的区别。实现原理也不复杂Python 本身提供了inspect模块可以拿到当前的调用栈信息。caveman内部会往上查一层调用栈找到谁调用了它然后把那个位置的filename、lineno、function拿过来格式化输出。这也是为什么它在任何普通 Python 环境里都能工作不需要依赖 IDE 或专门的运行时因为这只是标准库能力的一个巧妙封装。2.2 环境变量与开关控制开发时插桩一时爽测试完了如果忘了删这些调试打印就会污染正式输出。这个问题我在真实项目里碰到过很多回一个脚本跑完屏幕上全是调试信息日志文件里也混入了大量临时输出运维同事一脸问号。caveman提供了一个比较优雅的方案——通过环境变量做总开关。你在代码里保留所有的caveman调用点但要控制它们是否生效时设置export CAVEMAN_LOG_LEVELERROR如果不希望看到任何输出可以把级别设为一个不匹配的值或直接在调用处搭配条件判断。更常见的做法是把调试行为绑定到环境变量上import os from caveman import caveman DEBUG os.environ.get(DEBUG_MODE) 1 def process_item(item): if DEBUG: caveman(processing, item.id, item.value) # 正常业务逻辑这种写法特别适合那种“运行在服务器上的脚本”或“定时任务”你平时让它安静地跑一旦要排查问题就在执行命令前加一个DEBUG_MODE1立刻就能看到关键节点的内部状态排查完再恢复正常执行。也就是说caveman并不是一个“污染代码”的累赘反而可以变成一套轻量级的可插拔观测开关。2.3 基于调用栈的定位原理前面说到caveman能自动显示行号和函数名这里稍微展开讲一下原理。Python 的sys._getframe和inspect.currentframe可以拿到当前栈帧栈帧对象的f_back指向调用者。caveman的实现就是把自己这个函数从栈里摘出去看上一帧是谁然后从那个帧对象里读取f_code.co_filename、f_lineno、f_code.co_name等信息。这个思路其实可以扩展。你自己写代码时如果想实现一个类似的小工具也可以照搬这套逻辑import sys def debug_print(msg): frame sys._getframe(1) info f{frame.f_code.co_filename}:{frame.f_lineno} in {frame.f_code.co_name}: {msg} print(info, filesys.stderr)不过caveman显然比这做得更完整它把变量格式化、颜色、sink、定时器等常见需求都封装好了。理解这层原理的好处是当你在一个不满足“常规调用”的场景里使用它时比如被装饰器包装过、在生成器里、在异步回调里你会更容易预测输出是否符合预期。有一点要提醒不要对打印出的行号 100% 死磕在装饰器或嵌套函数里行号可能指向调用点的位置而不是逻辑核心行的位置但这对于定位问题完全足够了。3. 实操走一遍用 caveman 排查一个真实 Bug3.1 场景构建一个分页参数异常的数据脚本为了演示caveman的实际用法我构造一个非常常见的业务场景从一个文件中读取订单数据按用户分组给每个用户计算分页后的订单摘要。import json from collections import defaultdict # 模拟原始订单数据 raw_data [ {user_id: u1, order_id: o1, amount: 100}, {user_id: u1, order_id: o2, amount: 250}, {user_id: u2, order_id: o3, amount: 60}, {user_id: u3, order_id: o4, amount: 520}, ] def load_orders(source): # 这里简化成直接返回静态数据 return raw_data def group_by_user(orders): groups defaultdict(list) for order in orders: groups[order[user_id]].append(order) return groups def build_page_summary(groups, page_size2): summaries [] for user_id, orders in groups.items(): total sum(order[amount] for order in orders) page_count (len(orders) page_size - 1) // page_size summaries.append({ user_id: user_id, total_amount: total, page_count: page_count, order_count: len(orders), }) return summaries def run(): orders load_orders(orders.json) groups group_by_user(orders) result build_page_summary(groups, page_size2) print(json.dumps(result, indent2, ensure_asciiFalse)) if __name__ __main__: run()假设现在运行结果是[ { user_id: u1, total_amount: 350, page_count: 2, order_count: 2 }, { user_id: u2, total_amount: 60, page_count: 2, order_count: 2 }, { user_id: u3, total_amount: 520, page_count: 1, order_count: 1 } ]发现问题了吗u3只有 1 条订单但order_count显示是 1page_count算出来是 1这看起来没错。问题出在u2它只有 1 条订单但是输出里order_count却是 2。此时如果不看代码单从输出猜原因可能会一头雾水明明原始数据里u2只有一条记录为什么分组后变成两条这就是caveman该上场的时候了。3.2 从症状到定位插桩看数据流向我从load_orders开始在关键节点插入cavemanfrom caveman import caveman def load_orders(source): orders raw_data caveman(load_orders returned, orders) return orders def group_by_user(orders): caveman(group_by_user input, orders) groups defaultdict(list) for order in orders: groups[order[user_id]].append(order) caveman(group_by_user groups, dict(groups)) return groups重新运行后输出会是这样/path/to/debug_demo.py:15 in load_orders: load_orders returned [{user_id: u1, order_id: o1, amount: 100}, {user_id: u1, order_id: o2, amount: 250}, {user_id: u2, order_id: o3, amount: 60}, {user_id: u3, order_id: o4, amount: 520}] /path/to/debug_demo.py:20 in group_by_user: group_by_user input [{user_id: u1, order_id: o1, amount: 100}, {user_id: u1, order_id: o2, amount: 250}, {user_id: u2, order_id: o3, amount: 60}, {user_id: u3, order_id: o4, amount: 520}] /path/to/debug_demo.py:25 in group_by_user: group_by_user groups {u1: [{user_id: u1, order_id: o1, amount: 100}, {user_id: u1, order_id: o2, amount: 250}], u2: [{user_id: u2, order_id: o3, amount: 60}], u3: [{user_id: u3, order_id: o4, amount: 520}]}到这一步原始数据和分组结果都符合预期u2只有一条订单。问题一定出在build_page_summary里。继续插桩def build_page_summary(groups, page_size2): summaries [] for user_id, orders in groups.items(): caveman(processing user, user_id, orders, orders) total sum(order[amount] for order in orders) page_count (len(orders) page_size - 1) // page_size caveman(computed, user_id, order_count, len(orders), page_count, page_count) summaries.append({...}) return summaries输出会显示每组处理时orders的长度其实是 1、1、1那为什么最终 JSON 里u2的order_count是 2此时你可能怀疑是summaries.append或后续打印环节的问题。再在返回前插一个caveman看summariescaveman(summaries before return, summaries)很容易就会发现summaries本身三个用户的order_count都是 111。问题不在计算逻辑而在于run()函数里打印结果时可能拿错了变量或者我为了演示构造了一个 局部变量覆盖 的坑。真实的 Bug 可能多种多样但核心套路是一样的通过caveman在输入端、处理中、输出端各放一个观察点数据在哪个环节发生了“变异”一眼就能看出来。这是caveman最大的使用心得不要只在出错的地方打印要在数据进入一个函数时、离开一个函数时、循环体内的关键分支处都打印一遍然后把整个过程跑一遍你会得到一张“数据流动轨迹图”。这比守着某一个点反复猜要高效得多。3.3 在 Web 服务和自动化任务里怎么用除了普通脚本caveman在 Web 服务和自动化任务里也非常好用。举一个实际案例我曾经维护过一个 Flask 接口用户反馈某个订单状态总是算错。代码是别人写的调用链横跨三个模块路由函数 - 订单服务 - 状态机转换。当时我也没有把握问题在哪一层于是直接在路由入口、服务入口、状态机转换三个位置各加了一行cavemanapi.route(/orders/order_id/status) def get_order_status(order_id): caveman(route entry, order_id) result order_service.get_status(order_id) caveman(route exit, order_id, result) return result因为 Flask 的请求线程每次处理一个请求只要同时只有一个请求在跑caveman输出和请求的对应关系是清晰的。跑一次测试请求控制台就清清楚楚地列出整个调用链上每个环节的状态变化。问题最后定位在状态机里一个参数传递错误而没有caveman的话我可能还得写一堆临时日志、重启服务、重放请求才能看到内部状态。在 Celery 任务里用法也类似。定时任务出现数据异常时把caveman加在任务函数开头把任务参数、数据库查询结果、中间计算结果都打印出来然后手动执行一次任务观察输出。由于任务通常是一次性运行的caveman的输出不会像 Web 高并发下那样交错混乱反而非常直观。生产环境里当然不建议保留大量caveman输出那怎么办我一般把调试代码用环境变量包一层或者全部集中在某个函数里排查问题时打开一个开关就能复现观测问题解决后再关闭。这个过程可以做得很快比写正式日志再发布一次要省太多时间。4. 常见问题与避坑指南4.1 忘记移除调试语句怎么办很多人担心调试时插了上百个caveman最后清理不干净。我的建议是不要靠“记住”来清理而是靠机制来控制。一种做法是全局开关用一个自定义包装器# debug_helper.py import os from caveman import caveman as _caveman DEBUG os.environ.get(APP_DEBUG) 1 def dbg(*args, **kwargs): if DEBUG: _caveman(*args, **kwargs)然后代码里统一从debug_helper导入dbg而不是直接使用caveman。这样只要生产环境不设置APP_DEBUG1代码里残留再多的dbg调用也是空操作不会影响性能也不会污染输出。检查代码时你只需要搜一下dbg(就能清理干净。4.2 生产环境误开输出的风险caveman默认输出到sys.stderr如果你在一个高并发的 Web 服务里开了大量调试输出轻则把日志文件撑爆重则因为频繁 I/O 拖慢响应速度。我在某个项目里就遇到过同事在循环里插了个调试打印循环一万次每次输出几百字节结果接口响应时间从 50ms 变成 800ms排查了半天才发现是调试输出导致的。所以在生产环境务必遵循几个原则调试开关默认关闭只有需要排查时临时打开不要在高频循环内调用caveman如果要调用加一个采样条件打开调试开关时把sink指到一个独立文件避免和业务日志混在一起排查完成后立刻关闭开关并清理临时文件4.3 caveman 与断点、logging 怎么配合caveman不能完全替代断点调试和正式日志它与二者应该是配合关系。我的工作流一般是先用caveman快速锁定问题的大致范围再在有疑问的那个小区域里用 IDE 断点单步执行最后修复完用正式的logging为关键业务过程留下可追踪的记录。有一个场景特别适合caveman配合断点当你不知道某个变量在某个分支是否被赋值时直接打断点可能十次有八次没走到而用caveman搭一个临时探针跑一遍全流程看哪些探针亮过、哪些没亮你立刻就知道分支覆盖情况。这体验很像用一个简单的示波器先看信号大致长什么样再决定要不要拿逻辑分析仪去深究细节。提示caveman输出默认带颜色在终端里看很醒目但如果你的日志转到文本文件最好设置colorFalse否则文件里会残留一堆 ANSI 转义序列比如\x1b[31m读起来很痛苦。4.4 遇到不输出或格式化错乱时的排查有人会遇到“caveman没生效”的情况仔细看通常是下面几个原因环境变量控制没生效代码里包了if DEBUG而 DEBUG 被计算为 False在多线程下输出交错但caveman本身没问题只是多个线程在同一个终端里同时打印显得乱在 Jupyter Notebook 或某些 IDE 内置控制台里ANSI 颜色转义被原样输出看起来像乱码用colorFalse解决还有一个我自己踩过的坑把caveman用在functools.wraps装饰过的函数内部时行号会指向装饰器内部而不是业务函数内部。这是因为caveman获取调用栈时拿到了装饰器那一帧导致打印的 “函数名” 是装饰器的包装函数名。如果遇到输出里的函数名和预期不符不用慌直接看行号对应的代码文件位置即可本质不影响定位。5. 一些个人经验用caveman这几年我最大的感受是调试工具最重要的不是功能多强大而是“在你想用的那一刻能不能立刻用上”。断点调试要开 IDE、日志系统要配置、链路追踪更是要搭一整套基础设施这些在大型系统里都是必需的但在日常开发、快速验证、临时排查这些场景里它们都太重了。caveman就像一个随身带的放大镜虽然比不了显微镜和 CT 机但当你只是要看清楚指甲盖上的纹路时它是最顺手的选择。再分享一个小技巧我习惯在项目里定义一个debug_hook.py把caveman的开关、输出目标、格式统一封装同时给它起一个更短的名字see代码里写起来很顺手。# debug_hook.py import os from caveman import caveman as _see ENABLED os.environ.get(DEBUG_CAVEMAN, 0) 1 def see(*args, **kwargs): if not ENABLED: return kwargs.setdefault(color, False) _see(*args, **kwargs)有了这个薄封装调试完只需要检查代码里有多少个see(再决定是清理还是保留。保留也无所谓因为默认不输出对生产环境完全无副作用。如果你也想试试这种“返祖但高效”的调试方式我建议别一次插太多探针先插两三个关键节点跑一遍观察输出再根据结果决定下一个探针放哪像盲人摸象一样一步一步摸完整个流程最后你会对整个系统的数据流有特别清晰的理解。
