深入解析：HOW - 前端团队手动上报规范（Sentry）

文章目录

我们的目标是：不仅仅接入 Sentry 自动化上报，而是要在团队内部制定一套「前端手动上报规范」，指导大家如何在需要时显式调用 Sentry 的 API 来记录错误、业务事件、用户上下文等。

1. 设计原则

  1. 最小必要原则：只在「关键节点」或「自动捕获不足」的情况下手动上报，避免噪音。
  2. 结构化信息：所有手动上报必须携带上下文（用户信息 / 模块标签 / 环境变量 / 业务参数），方便后续查询和归因。
  3. 统一封装：不要在业务代码里直接裸用 Sentry.captureException，而是通过团队封装的 reportError、reportMessage 等函数，保证统一格式和清洗逻辑。
  4. 隐私合规：禁止上报明文 PII（如手机号、邮箱、token），需要时应脱敏处理。
  5. 可控性：通过配置项决定哪些场景上报到生产，哪些仅在 staging 记录。

2. 上报场景分类

A. 异常类

  • 接口失败：业务强依赖接口失败，需额外关注（例如支付下单失败）。
  • 逻辑异常：catch 到的异常，不会被全局捕获到，但对业务有影响。
  • 第三方库报错：重要的第三方调用失败，如支付 SDK、地图 SDK。

B. 业务事件类

  • 关键业务失败：如“提交订单失败”、“用户资料保存失败”。
  • 兜底容错触发：比如本地缓存异常恢复机制启动时。
  • 异常 UI 状态：用户界面进入“不应该发生”的状态。

C. 性能与交互类（可选）

  • 耗时异常：某些核心操作耗时超过阈值。
  • 手动事务 / span：标记关键链路（如支付流程、上报链路）。

3. 常用 API 与用法规范

这里以 Sentry version 9 为例。
Sentry 版本(注意版本差异)：
“@sentry/react”: “^9.12.0”,
“@sentry/vite-plugin”: “^3.3.1”,

3.1 异常上报

import * as Sentry from "@sentry/react"
export function reportError(
error: unknown,
context?: Record<string, any>,
  level: Sentry.SeverityLevel = "error"
  ) {
  Sentry.withScope((scope) => {
  if (context) {
  Object.entries(context).forEach(([key, value]) => {
  scope.setExtra(key, value)
  })
  }
  scope.setLevel(level)
  Sentry.captureException(error)
  })
  }

使用规范：

try {
await api.submitOrder(payload);
} catch (err) {
reportError(err, { module: "Order", action: "submitOrder", payloadId: payload.id });
}

3.2 信息类（非异常）

import * as Sentry from "@sentry/react"
export function reportMessage(
message: string,
context?: Record<string, any>,
  level: Sentry.SeverityLevel = "info"
  ) {
  Sentry.withScope((scope) => {
  if (context) {
  Object.entries(context).forEach(([key, value]) => {
  scope.setExtra(key, value)
  })
  }
  scope.setLevel(level)
  Sentry.captureMessage(message)
  })
  }

使用规范：

reportMessage("User clicked retry", { module: "Upload", fileName: "report.pdf" }, "info");

3.3 性能链路（手动 span）

具体阅读 HOW - 团队性能监控上报规范（Sentry）

3.4 用户上下文

function setUserContext(user: { id: string; role?: string }) {
Sentry.setUser({ id: user.id, role: user.role });
}
function clearUserContext() {
Sentry.setUser(null);
}

4. 封装层推荐

在项目里新增 utils/sentry.ts，统一导出：

  • reportError
  • reportMessage
  • reportWithSpan
  • setUserContext / clearUserContext

业务代码只调用封装层，避免滥用 SDK 原始 API。

5. 规范文档（写进团队 Wiki/README）

  1. 什么时候要上报？

    • 影响用户核心流程的错误（接口失败 / 业务失败）
    • 需要跟踪的业务容错场景
    • 性能关键链路（可选）

  2. 怎么上报？

    • 严禁 Sentry.captureException 直写
    • 必须调用 utils/sentry.ts 封装函数
    • 必须传入 context，至少包含 module、action、paramsId

  3. 不允许上报内容

    • 用户隐私（手机号、邮箱、身份证）
    • 密码、token、cookie

  4. 代码审查要求

    • PR 中出现裸用 Sentry.* → 拒绝
    • 确认上报点符合规范场景
    • 确认有 context 信息，且已脱敏

6. Code Review 清单

  • 是否使用了封装函数而非裸用 SDK？
  • 是否附带了完整上下文（module, action, paramsId 等）？
  • 是否存在敏感信息上报？
  • 是否控制了上报频率（避免循环上报）？

最终效果

  • 团队上报点统一、可读、可检索
  • 日志里所有手动上报都能按「module/action」维度过滤
  • 避免数据泄漏 & 避免噪音
  • 在告警和 Sentry Dashboard 上能准确定位业务模块
posted @ 2025-10-11 15:50  wzzkaifa  阅读(15)  评论(0)    收藏  举报