欢迎光临
我们一直在努力

错误处理与日志最佳实践:独立开发者构建可维护系统的实战指南

错误处理与日志最佳实践:独立开发者构建可维护系统的实战指南

错误处理的三个核心原则

错误处理是独立开发者最容易"知道重要但一直拖延"的工程环节。早期产品用户少,错误影响范围小,你总觉得"先把功能做出来,错误处理后面再加"。

但等到用户量到几千、每天API请求到几万次时,你会发现没有系统化的错误处理和日志,排查一个问题需要几小时——你需要在服务器日志文件里手动搜索错误信息,需要猜测"这个错误是哪个用户触发的",需要复现"这个错误在什么条件下发生"。

我在2023年到2026年,逐步建立了产品的错误处理和日志体系。以下是最佳实践的完整记录。

原则一:区分"预期错误"与"非预期错误"

很多开发者把所有错误都用同样的方式处理——返回500 Internal Server Error。这是错误的。预期错误(Expected Errors)和非预期错误(Unexpected Errors)需要完全不同的处理策略。

预期错误:这是"正常业务流程的一部分"的错误。如:

  • 用户登录时密码错误
  • 用户请求的资源不存在(404)
  • 用户输入的表单数据验证失败(400)
  • 用户权限不足(403)

这些错误的特征是:你知道它们会发生,且需要在产品层面给用户友好的反馈。

处理策略:

  • 返回合适的HTTP状态码(4xx系列)
  • 返回人类可读的错误信息(如"密码错误,请重试")
  • 不要记录为"错误日志"——这是正常业务流,不需要告警
  • 非预期错误:这是"不应该发生"的错误。如:

    • 数据库查询失败(连接断了、SQL语法错误)
    • 外部API调用失败(网络超时、API返回500)
    • 代码里的逻辑错误(如试图读取undefined的属性)

    这些错误的特征是:它们不应该在正常业务流程中发生,发生了说明有bug或系统故障。

    处理策略:

  • 返回500 Internal Server Error(或502/503,如果是外部服务不可用)
  • 返回给用户一个通用的"抱歉,出了点问题"提示(不要把技术错误信息暴露给用户)
  • 必须记录详细的错误日志,包含堆栈追踪、用户上下文、请求参数
  • 可选发送告警通知(根据错误频率决定是否立即告警)
  • 原则二:结构化日志,而不是"console.log到处打"

    早期产品的日志通常是这样的:

    console.log('用户登录成功', userId);
    console.error('数据库查询失败', error);
    console.log('API请求开始', req.body);

    这种日志的问题:

  • 不可查询。出了问题时,你需要在服务器上用grep或tail -f手动搜索日志。如果日志量很大,这几乎不可能。
  • 缺少上下文。日志只记录了"发生了什么",没有记录"发生在谁身上""请求ID是什么""调用链路是什么"。
  • 格式不一致。有的日志是字符串,有的是JSON,有的是错误对象。后期要做日志分析几乎不可能。
  • 解决方案:结构化日志(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会自动:

  • 聚合相同错误:把堆栈追踪相同的错误归类为一个Issue
  • 统计发生频率和影响用户数:"这个错误在过去24小时发生了50次,影响了30个用户"
  • 提供上下文:每次错误发生时的用户信息、请求信息、面包屑(用户在做这个错误之前做了什么操作)
  • 告警:当某个错误的发生频率超过阈值时,发送邮件或Slack通知
  • 接入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)、以及"给用户友好错误提示"的用户体验意识。

    赞(0)
    未经允许不得转载:171主机测评 » 错误处理与日志最佳实践:独立开发者构建可维护系统的实战指南
    分享到: 更多 (0)

    评论 抢沙发

    • 昵称 (必填)
    • 邮箱 (必填)
    • 网址