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 上能准确定位业务模块