【服务出错问题排查记录】从一个“点击失败”开始：为什么“系统异常”其实是最差的错误设计
一、问题起点：一次“无信息”的失败
那天我在页面上点击一个功能按钮，预期是触发一次 URL 分析任务。但页面只返回了一句：❗“系统异常，请稍后重试”。
没有错误详情，没有接口信息，也没有任何可追踪线索。
作为算法工程师，我的第一反应是：
- 是模型推理失败？
- 是输入数据异常？
- 还是后端服务挂了？
但很快我意识到一个更本质的问题：❗这个错误对“定位问题”没有任何帮助。在这种提示下，系统其实等于告诉我一句话：“出错了，但你自己想办法。”但工程上真正的问题是：❗我甚至不知道这个按钮调用的是哪个接口
二、从黑盒到请求层：错误开始变得“可见”
在页面只给出一句“系统异常”的情况下，所有业务逻辑都被隐藏在前端之后。这时候能做的第一件事，不是猜后端，而是把前端请求“扒出来”。
2.1 查看真实请求信息
我打开了浏览器开发者工具（F12），切换到 Network 面板，开始重新触发按钮操作。
关键动作
- 切换到Network
- 过滤XHR / Fetch
- 再次点击页面按钮，触发请求
这个动作本身很简单，但本质上是在做一件事：❗把“黑盒交互”变成“可观测请求流”。因为在没有日志、没有报错详情的情况下，Network 面板就是唯一能看到系统真实行为的窗口。
2.2 定位接口
很快，一个请求出现了：
/xxx/po_monitoring/inference 在此之前，这个系统对我来说是“完全黑盒”的：
不知道前端调用了什么接口
不清楚后端服务结构
没有任何请求链路信息
而此刻，我第一次看到了真实的后端入口。
三、接口暴露与问题定位：从现象到结构
我点击该请求，重点确认三部分信息：
- Request URL
https://xxx/algoapi/po_monitoring/inference- Request Payload
{"text":"www.paypal.com"}- Response
{"code":500,"message":"Internal Server Error"}
这一刻问题发生第一次转向，从页面为什么报错，变成这个接口为什么返回 500。
同时我也重新理解了这个接口的结构：
/xxx/po_monitoring/inference
| 层级 | 含义 |
|---|---|
| xxx | 后端服务 |
| po_monitoring | 业务模块 |
| inference | 功能入口 |
可以看出这不是“模型接口”，而是后端业务系统中的一个函数入口。
四、验证与隔离：排除前端干扰
为了确认问题不在前端，我直接用 curl 复现请求：
curl-XPOST"https://xxx/po_monitoring/inference"\-H"Content-Type: application/json"\-d'{"text":"www.paypal.com"}'-k 返回结果完全一致：
{"code":500,"message":"Internal Server Error"} 此时可以确定：
前端不是问题来源
请求已经成功到达后端
后端执行过程中发生异常
但问题也开始变得更棘手：❗错误存在，但不可见（没有 traceback）
五、真正的问题：错误信息不可观测
到这里，问题已经不再是接口本身，而是错误设计本身：
当前系统只能提供：
{"code": 500, "message": "Internal Server Error"}但对于排障来说，这几乎等于没有信息。缺失的关键内容包括：
- 具体接口路径的错误归属
- 异常类型（模型错误 / 参数错误 / 代码异常）
- 后端模块信息
- trace_id（无法追踪日志）
- 具体异常堆栈
六、一个更合理的错误设计应该是什么样？
如果系统稍微“工程化”一点，返回的应该是这样的信息：
{"code":500,"api":"/xxx/po_monitoring/inference","error_type":"ModelInferenceError","message":"input parsing failed","trace_id":"xxxxxx"} 这样至少可以做到：
出错知道在哪个接口
可以关联日志 trace_id
可以区分错误类型
可以快速定位后端模块
六、结语
这次排障到这里暂时结束。问题已经从前端页面，推进到了后端接口层，但也卡在了更深一层的系统内部：
错误是存在的
请求是通的
但具体异常点不可见
这次经历最大的变化不是找到问题，而是第一次清晰看到：排障不是从“现象”开始，而是从“请求链路”开始。