错误处理与日志最佳实践:独立开发者构建可维护系统的实战指南
错误处理的三个核心原则
错误处理是独立开发者最容易"知道重要但一直拖延"的工程环节。早期产品用户少,错误影响范围小,你总觉得"先把功能做出来,错误处理后面再加"。
但等到用户量到几千、每天API请求到几万次时,你会发现没有系统化的错误处理和日志,排查一个问题需要几小时——你需要在服务器日志文件里手动搜索错误信息,需要猜测"这个错误是哪个用户触发的",需要复现"这个错误在什么条件下发生"。
我在2023年到2026年,逐步建立了产品的错误处理和日志体系。以下是最佳实践的完整记录。
原则一:区分"预期错误"与"非预期错误"
很多开发者把所有错误都用同样的方式处理——返回500 Internal Server Error。这是错误的。预期错误(Expected Errors)和非预期错误(Unexpected Errors)需要完全不同的处理策略。
预期错误:这是"正常业务流程的一部分"的错误。如:
- 用户登录时密码错误
- 用户请求的资源不存在(404)
- 用户输入的表单数据验证失败(400)
- 用户权限不足(403)
这些错误的特征是:你知道它们会发生,且需要在产品层面给用户友好的反馈。
处理策略:
非预期错误:这是"不应该发生"的错误。如:
- 数据库查询失败(连接断了、SQL语法错误)
- 外部API调用失败(网络超时、API返回500)
- 代码里的逻辑错误(如试图读取undefined的属性)
这些错误的特征是:它们不应该在正常业务流程中发生,发生了说明有bug或系统故障。
处理策略:
原则二:结构化日志,而不是"console.log到处打"
早期产品的日志通常是这样的:
console.log('用户登录成功', userId);
console.error('数据库查询失败', error);
console.log('API请求开始', req.body);
这种日志的问题:
解决方案:结构化日志(Structured Logging)
所有日志用统一的JSON格式,包含以下字段:
{
"timestamp": "2026-07-01T14:30:00.123Z",
"level": "error",
"message": "数据库查询失败",
"error": {
"message": "Connection terminated",
"stack": "Error: Connection terminated\\n at …"
},
"context": {
"requestId": "req_abc123",
"userId": "user_456",
"path": "/api/generations",
"method": "POST"
}
}
在Node.js里,可以用winston或pino这类日志库来实现结构化日志:
import winston from 'winston';
const logger = winston.createLogger({
format: winston.format.combine(
winston.format.timestamp(),
winston.format.json()
),
transports: [
new winston.transports.File({ filename: 'error.log', level: 'error' }),
new winston.transports.File({ filename: 'combined.log' })
]
});
// 使用
logger.info('用户登录成功', { userId, sessionId });
logger.error('数据库查询失败', { error, userId, query });
关键实践:给每个请求分配一个唯一的Request ID
这样,当一个请求触发了多个日志条目(如"API请求开始"→"数据库查询"→"AI API调用"→"返回响应"),你可以用Request ID把这些日志条目关联起来。
实现方式:用Express中间件给每个请求生成一个UUID:
app.use((req, res, next) => {
req.requestId = crypto.randomUUID();
logger.info('API请求开始', {
requestId: req.requestId,
method: req.method,
path: req.path,
userId: req.user?.id
});
next();
});
然后,在所有后续的日志调用里,都带上requestId。这样排查问题时,你只需要搜索requestId,就能看到这个请求的全链路日志。
原则三:用Sentry或类似工具做错误追踪与聚合
结构化日志解决了"记录错误"的问题。但它没有解决"错误聚合与趋势分析"的问题。
如果你有1000个用户,其中50个用户触发了同一个错误(如"AI API调用超时"),在日志文件里,这会表现为50条独立的错误日志。你需要手动统计"这个错误发生了多少次、影响了多少用户"。
错误追踪工具(如Sentry)的价值,就是自动做这个聚合。
Sentry会自动:
接入Sentry的核心实践:
在后端和前端都接入Sentry后端Sentry捕获API层面的未处理异常;前端Sentry捕获浏览器里的JavaScript错误和用户操作层面的问题。
设置合理的告警规则不是每一个错误都需要立即告警。我的告警规则是:
- P0:过去1小时内同一个错误发生了>10次 → 立即Slack通知
- P1:过去24小时内某个错误影响了>5个用户 → 每日汇总邮件
- P2:其他错误 → 不告警,定期在Sentry后台审查
用Sentry的"发布版本"功能追踪错误和代码版本的关系每次部署新版本时,在Sentry里标记一个新的Release。这样,当某个错误出现在Sentry里时,你能看到"这个错误是在哪个版本引入的"。
用户输入验证与错误反馈的用户体验
最后谈一个经常被忽视的话题:错误处理的用户体验。
技术层面的错误处理(记录日志、发送告警)是重要的。但用户看到错误提示时的体验同样重要。
最佳实践:
给用户的信息应该是"可行动的"❌ 错误:"Internal Server Error"✅ 正确:"服务器处理你的请求时出了点问题。请稍后重试,如果问题持续,请联系支持(support@product.com)。"
区分"用户能修复的错误"和"用户不能修复的错误"
- 用户能修复的(如表单验证失败):明确告诉用户"哪一栏填错了、怎么改"
- 用户不能修复的(如服务器错误):告诉用户"这不是你的问题,我们已经知道了,正在修复"
用Toast或Inline错误提示,不要用Alert弹窗在2026年,用户体验的最佳实践是:表单验证错误用Inline提示(在输入框旁边显示红色文字),操作失败用Toast通知(页面右上角滑入的提示),不要用浏览器原生的alert()弹窗。
实战案例:一次生产错误的完整排查过程
2024年8月15日,我收到了Sentry的告警:"AI API调用超时"在过去1小时内发生了23次,影响了18个用户。
排查过程:
在Sentry里查看错误详情看到了错误的堆栈追踪、每个错误发生时的Request ID、受影响的用户ID列表。
用Request ID查询完整日志在Grafana(我的日志查询界面)里搜索其中一个Request ID,看到了这个请求的全链路日志:
- 14:30:01 – API请求开始
- 14:30:01 – 数据库查询用户订阅状态(成功)
- 14:30:02 – 调用Claude API(超时,30秒后放弃)
- 14:30:32 – 返回500错误给用户
识别根因所有23次错误都集中在14:30-14:45这个时间段。我查了Claude API的状态页(status.anthropic.com),发现Claude API在14:25-14:50有一次部分服务中断。
修复这次错误是外部服务的问题,不是我的代码bug。但我在代码中加入了"外部API调用超时后的重试逻辑"(用axios-retry库),这样下次Claude API短暂超时时,系统会自动重试,不需要把错误暴露给用户。
后续优化我加入了"多个AI模型Fall-back"机制——如果Claude API超时,自动切换到GPT-4 API。这个优化让同样的外部服务中断不再影响我的用户。
结论:好的错误处理系统,不是"没有错误",而是"当错误发生时,你能快速定位、快速修复、且用户受到的影响最小"。独立开发者不需要搭建像大公司那样复杂的错误管理平台,但至少需要:结构化日志、错误追踪工具(如Sentry)、以及"给用户友好错误提示"的用户体验意识。



