第一眼：错误是什么？
找异常类型、错误码和消息，例如 NullPointerException、ECONNREFUSED、context deadline exceeded。
BACKEND DEBUGGING FIELD GUIDE
看懂报错堆栈：
从“红字很多”到“第一处该改的代码”
适用于 Python / Go / Java / TypeScript。核心不是从头读到尾，而是回答四个问题：什么错、在哪炸、怎么走到这里、谁才是根因。
01统一心智模型：堆栈是一条“倒放的调用路线”
根因 / 异常业务代码基础设施框架 / 入口
第二眼：我的代码在哪？
跳过框架噪音，找包名/目录属于项目的第一帧；它通常是最值得打断点的位置。
第三眼：路径合理吗？
沿调用帧还原输入如何流动；确认错误是本地触发，还是下游包装后冒泡。
第四眼：证据够吗？
关联请求 ID、时间、参数摘要、部署版本和上下游日志，不要只凭最后一行猜。
02一张图解剖“异常、调用帧、因果链”
03四种语言怎么读：方向不同，目标相同
Python
Traceback (most recent call last):
File "api.py", line 21, in create_order
service.create(data)
File "service.py", line 48, in create
total = price * qty
TypeError: unsupported operand type(s)
- ① 先读最后一行：异常类型 + 消息。
- ② 再向上找最后一个属于项目的 frame。
- ③ 注意
During handling.../direct cause：有多段因果链。 - ④
raise ... from e能保留真正 cause。
Go
panic: runtime error: invalid memory address
goroutine 18 [running]:
shop/order.(*Service).Create(...)
/app/order/service.go:57 +0x1a4
shop/api.createOrder(...)
/app/api/handler.go:31 +0xb8
- ① 先看 panic 文本与
goroutine N [state]。 - ② 每帧是两行：完整函数名 + 文件:行号。
- ③ 找第一个非 runtime / net/http / 第三方的项目帧。
- ④ 普通
error默认没有栈；用%w包装并在边界记录。
Java
com.shop.OrderException: create failed
at com.shop.OrderService.create(OrderService.java:88)
at ... 24 common frames omitted
Caused by: java.sql.SQLIntegrityConstraintViolationException
at com.shop.OrderRepo.insert(OrderRepo.java:52)
... 18 common frames omitted
- ① 沿
Caused by一路读到最底。 - ②
... N common frames omitted是重复帧压缩，不是信息丢失。 - ③ 留意
Suppressed：资源关闭等次要异常。 - ④ 反射、代理、Spring AOP 帧多时，优先搜自己的包名前缀。
TypeScript / Node.js
TypeError: Cannot read properties of undefined
at OrderService.create (src/order.ts:63:21)
at processTicksAndRejections
(node:internal/process/task_queues:95:5)
at async OrderController.post (src/api.ts:28:7)
- ① 坐标是
文件:行:列；列号定位表达式很有用。 - ②
async栈可能跨 Promise；留意processTicks...边界。 - ③ 生产环境必须保留并正确发布 source map。
- ④
Error(..., { cause })保留因果，不要只拼接字符串。
共同口诀：类型定方向 → 消息给线索 → 根因链找源头 → 项目帧定位置 → 上下文证实假设。
04为什么堆栈会“断”：异步、线程、队列与跨服务
05实战排障：照着走，不靠猜
1冻结现场保存完整堆栈，不要只截最后一行；记录时间、环境、版本、请求/任务 ID。
2归类失败语法/类型、空值、I/O、超时、资源耗尽、并发、数据约束还是业务校验？
3追到根因Python 看最后异常链；Java 追最后 Caused by；TS 看 cause；Go 看 panic 或 error unwrap。
4圈定项目帧定位靠近根因的第一帧项目代码，再向上看 2–3 帧理解业务上下文。
5检查现场值核对输入、空值、边界、配置、SQL 参数、超时设置；敏感信息只记摘要。
6提出可证伪假设写成“若 X，则 Y 日志/测试应出现”；一次只验证一个假设。
7最小复现固定依赖和数据，把大请求缩成最短路径；并发问题保留时序与负载。
8修复并防复发加回归测试、结构化日志和必要监控；确认没有吞错、重复记录或泄露隐私。
06必知必会速查
必须保留原始因果
Python: raise DomainError(...) from e
Go: fmt.Errorf("save order: %w", err)
Java: new DomainException("...", cause)
TS: new Error("...", { cause: err })
日志异常只在责任边界记一次
底层返回并包装，API / Worker 边界统一记录完整异常。层层打印会制造重复告警，也可能泄露数据。
定位源码与构建产物要对应
部署版本、符号、source map、镜像标签必须可追溯；否则行号再精确也会指向错误源码。
警惕“最后一帧”不总是 bug
它可能只是失败被发现的位置。数据早已在上游污染，或下游服务返回了错误；必须看调用上下文。
区分错误、异常、崩溃
可预期业务失败应正常返回；异常表示非正常路径；panic / 未捕获异常会终止请求、线程甚至进程。
安全生产日志要脱敏
不要记录密码、Token、完整卡号、身份证或整段请求体。使用字段白名单、掩码和摘要。
5 分钟口诀： 保存全栈 → 读异常类型 → 沿 cause 到底 → 找最近的项目帧 → 对齐请求与版本 → 用最小实验验证 → 回归测试封口。
07配套实验：亲手制造一次错误，再亲手修好
Python · TypeError
缺少 price 导致 None * int。练习从最后一行反查 calculate_total。
Go · nil panic
解引用空 Customer。练习识别 panic、goroutine 和“两行一帧”的坐标格式。
Java · Caused by
业务异常包装重复订单错误。练习穿透外层异常，追到最后一个根因。
TypeScript · async
await 后访问 undefined。练习读取异步帧、行列号并理解 source map。
实验文件：
Makefile 是统一入口，labs/<language>/broken 负责制造错误，fixed 展示修复思路；详细步骤见 README.md。