Sentry 官方 SDK ESLint 插件(@sentry/eslint-plugin-sdk)规则体系与源码深度解析
Sentry 官方 SDK ESLint 插件(@sentry/eslint-plugin-sdk)规则体系与源码深度解析
导读
@sentry/eslint-plugin-sdk 是 Sentry 官方维护的 ESLint 插件,承载着 Sentry JavaScript SDK 各包在代码质量、测试卫生、性能与安全层面的工程约束。本文以 packages/eslint-plugin-sdk/README.md 为主线,结合插件源码、测试用例与 @sentry/core 底层实现,逐一拆解 8 条自定义规则的触发逻辑、修复建议与设计动机,帮助读者理解这套规则如何在浏览器端包体积、随机数安全、追踪数据隐私等场景下守住质量底线。
插件定位:内部库而非公共 API
README 开篇即明确:这是 Sentry 内部使用的自定义 ESLint 规则集合,供 Sentry 自有 JavaScript SDK 包与仓库使用,不属于公共 API 契约的一部分,可能在任意版本中变更,直接依赖时不保证 SemVer 兼容。因此,外部项目若想使用,应以"参考其规则思路并自行取舍"的方式阅读,而非将其当作稳定的公共依赖。
从 packages/eslint-plugin-sdk/package.json 可以看到它的工程形态:
- 包名
@sentry/eslint-plugin-sdk,版本 11.2.0,MIT 许可; main指向src/index.js,即插件入口直接暴露源码而非编译产物;- 运行时要求 Node
>=20.19.0 <22.0.0 || >=22.12.0 <23.0.0 || >=23.2.0; - 测试使用 Vitest(
test: "vitest run"),并配有用 oxlint 的lint/lint:types脚本; - 发布时仅打包
/src目录。
插件入口 packages/eslint-plugin-sdk/src/index.js 采用 CommonJS 风格,将所有规则集中注册:
module.exports = {
rules: {
'no-eq-empty': require('./rules/no-eq-empty'),
'no-class-field-initializers': require('./rules/no-class-field-initializers'),
'no-regexp-constructor': require('./rules/no-regexp-constructor'),
'no-focused-tests': require('./rules/no-focused-tests'),
'no-skipped-tests': require('./rules/no-skipped-tests'),
'no-unsafe-random-apis': require('./rules/no-unsafe-random-apis'),
'no-unfiltered-url-attributes': require('./rules/no-unfiltered-url-attributes'),
'no-unguarded-span-apis': require('./rules/no-unguarded-span-apis'),
},
};
在仓库内启用时,通常在 ESLint 配置中通过 plugins 声明并逐条开启或关闭规则,规则名即上面导出的键名。全部规则实现位于 packages/eslint-plugin-sdk/src/rules,测试位于 packages/eslint-plugin-sdk/test/lib/rules。
规则总览
| 规则名 | 检查目标 | 核心动机 |
|---|---|---|
no-eq-empty |
对空数组/对象使用 ==/=== |
消除永远为 false 的误导性比较 |
no-class-field-initializers |
类字段初始化器 | 避免增大打包体积,改用构造函数赋值 |
no-regexp-constructor |
new RegExp(...) |
防止从用户输入构造非法或危险正则 |
no-focused-tests |
测试中的 .only |
防止误提交聚焦测试导致其他用例被跳过 |
no-skipped-tests |
测试中的 .skip |
防止误提交跳过测试 |
no-unsafe-random-apis |
Date.now/Math.random/performance.now/crypto API |
要求包在 withRandomSafeContext 中保证缓存场景安全 |
no-unfiltered-url-attributes |
URL 类 span 属性 | 要求经 filterCollectedUrl 过滤以遵守 dataCollection.urlQueryParams |
no-unguarded-span-apis |
浏览器端代码的 span 启动 API 导入 | 防止引入不安装 spanStreamingIntegration 的普通变体导致 span 被创建却永不发送 |
下面结合源码逐条展开。
no-eq-empty:禁止对空数组/空对象使用相等运算符
源码 packages/eslint-plugin-sdk/src/rules/no-eq-empty.js 检查 BinaryExpression:当 == 或 === 的一侧是字面量 [] / {},而另一侧不是同类表达式时即报错。
BinaryExpression(node) {
if (node.operator === '==' || node.operator === '===') {
if (node.left.type !== 'ArrayExpression' && node.right.type === 'ArrayExpression') {
context.report({
node,
messageId: 'equality',
data: { name: 'array', fix: ' Use .length or Array.isArray instead.' },
});
}
// ... 同理处理 ObjectExpression
}
}
其动机非常明确:arr === <a href="https://link.gitcode.com/i/865382a56e5f440ccc3525c71aa2acdc" target="_blank">] 在任何情况下都为 false(引用比较),但极易被误写为"判断数组为空"。测试 [packages/eslint-plugin-sdk/test/lib/rules/no-eq-empty.test.ts 中,'empty === []'、'empty == {}'、'const hey = function() {}() === []' 均判为非法,并分别给出"Use .length or Array.isArray instead."与空修复建议;而 '[] === []'、'{} == {}' 这类"两侧同为字面量"的代码反而合法——因为引用比较两侧都是新对象,结果恒为 false,属于典型的误导性写法,规则同样拦截。
no-class-field-initializers:为包体积而禁用类字段初始化器
源码 packages/eslint-plugin-sdk/src/rules/no-class-field-initializers.js 的 meta 描述直接点明动机:"disallow usage of class field initializers, because they produce larger bundle size"(禁用类字段初始化器,因为它们会产生更大的打包体积)。该规则参考了 eslint-plugin-react 的 state-in-constructor 思路。
实现上,它监听 ClassProperty, PropertyDefinition 节点,只要字段带有初始值即报错:
'ClassProperty, PropertyDefinition'(node) {
if (node.value !== null) {
context.report({
node,
message: `Avoid class field initializers. Property "${node.key.name}" should be initialized in the constructor.`,
});
}
},
对于以包体积为敏感指标的 SDK 类库(如 packages/core、packages/browser),把字段初始化统一收敛到构造函数中,可以减少类字段语法转换带来的额外代码。该规则标记为 recommended: true,type 为 problem。
no-regexp-constructor:禁止从用户输入构造正则
源码 packages/eslint-plugin-sdk/src/rules/no-regexp-constructor.js 的注释阐述了边界:使用 new RegExp 本身没有错,只有当正则由未检查、未转义的用户输入构造时才危险——可能产生非法正则表达式或引入 ReDoS 等漏洞。
NewExpression(node) {
if (node.callee.type === 'Identifier' && node.callee.name === 'RegExp') {
context.report({
node,
message: 'Avoid using the RegExp() constructor with unsafe user input.',
});
}
},
由于 ESLint 静态分析无法可靠判断参数来源,规则采取"一刀切"策略:凡 new RegExp(...) 一律告警,开发者若确认安全可用 eslint-disable 注释豁免。这与 no-unsafe-random-apis 的豁免思路一致——规则宁严勿松。
no-focused-tests 与 no-skipped-tests:测试卫生
这两条规则守护测试仓库的可靠性。源码 packages/eslint-plugin-sdk/src/rules/no-focused-tests.js 与 packages/eslint-plugin-sdk/src/rules/no-skipped-tests.js 结构完全相同,只是分别匹配 .only 与 .skip:
CallExpression(node) {
if (
node.callee.type === 'MemberExpression' &&
node.callee.object.type === 'Identifier' &&
['test', 'it', 'describe'].includes(node.callee.object.name) &&
node.callee.property.type === 'Identifier' &&
node.callee.property.name === 'only' // 或 'skip'
) {
context.report({ node, message: "Do not focus tests via `.only` ..." });
}
},
覆盖对象包括 test、it、describe 三种常见测试 API,同时适用于 Vitest 与 Jest。no-skipped-tests.js 的注释特别说明:跳过测试有时是合理的(例如 flaky 测试),此时可用 eslint-disable 显式豁免,把"临时跳过"变成"有意的、留下痕迹的例外"。
no-unsafe-random-apis:随机/时间 API 的缓存安全
这条规则是插件与 @sentry/core 运行时能力配合最紧密的一例。源码 packages/eslint-plugin-sdk/src/rules/no-unsafe-random-apis.js 检测以下成员调用:
Date.now()→ 建议替换为@sentry/core的safeDateNow()Math.random()→ 建议替换为safeMathRandom()performance.now()→ 建议包裹withRandomSafeContext(() => performance.now())crypto.randomUUID()/crypto.getRandomValues(...)→ 同样建议包裹
此外,无参的 new Date()(读取环境时钟)也被标记,提示改用 new Date(safeDateNow());而 new Date(<number>) 由于不读取当前时间,属于安全用法。
底层机制见 packages/core/src/utils/randomSafeContext.ts:withRandomSafeContext(cb) 会先在全局对象上查找 Symbol.for('__SENTRY_SAFE_RANDOM_ID_WRAPPER__') 对应的 runner(首次解析后缓存结果,避免重复查找),找到则用 runner 包裹回调执行,找不到则直接执行回调。safeMathRandom() 与 safeDateNow() 分别是 withRandomSafeContext(() => Math.random()) 与 withRandomSafeContext(() => Date.now()) 的封装:
export function safeMathRandom(): number {
return withRandomSafeContext(() => Math.random());
}
export function safeDateNow(): number {
return withRandomSafeContext(() => Date.now());
}
这套机制的典型应用场景是 React Server Components(Next.js)等带缓存的组件上下文:直接调用随机/时间 API 会破坏缓存稳定性(值随每次渲染变化),而通过 runner 在缓存上下文中生成安全的随机 ID 则能保证一致性。
规则实现的关键是判断调用是否已处于 withRandomSafeContext 的回调内:isInsidewithRandomSafeContext 沿 AST 父节点向上遍历,识别直接传入的箭头函数、普通函数表达式以及嵌套调用;同时豁免定义文件本身(文件名含 safeRandomGeneratorRunner 的文件),避免规则告警自己。测试 packages/eslint-plugin-sdk/test/lib/rules/no-unsafe-random-apis.test.ts 覆盖了包裹与未包裹、嵌套表达式、someOtherWrapper(() => Date.now())(非目标包裹器仍报错)以及 new Date(1234567890)(合法)等边界情形。
no-unfiltered-url-attributes:URL 属性必须过滤查询串
这条规则服务于隐私配置 dataCollection.urlQueryParams。源码 packages/eslint-plugin-sdk/src/rules/no-unfiltered-url-attributes.js 的注释说明了设计背景:URL 属性携带请求查询串,本应由 dataCollection.urlQueryParams 统一管控;过滤发生在写入点而非集中处理,因此用户自行附加的 URL 不受影响——这也意味着一旦某处忘记过滤,隐私数据就会静默泄漏,静态检查因此必不可少。
规则守护两类属性:
- 受保护属性(携带查询串):
URL_FULL、URL_QUERY、url.full、url.query;http.target未被列入,因为 SDK 已不再设置它,替代属性url.path是纯路径名,无需过滤; - 视为"已过滤"的辅助函数集合,包括
filterCollectedUrl、filterCollectedUrlQuery及内部变体_INTERNAL_filterCollectedUrl、_INTERNAL_filterCollectedUrlQuery、filterUrlQuery、filterQueryParams、normalizeAndFilterQueryString等; - 视为"彻底清洗"的函数集合:
stripUrlQueryAndFragment、getSanitizedUrlString、stripDataUrlContent、react-router 的getPathFromRequest等。
实现上,它检查对象属性写入({ [URL_FULL]: value }、{ 'url.full': value })与赋值表达式(attributes[URL_FULL] = value)。判断"值是否已过滤"是亮点:
isFiltered递归处理CallExpression、Identifier、ConditionalExpression、LogicalExpression(即a ?? filterCollectedUrl(b)、cond ? filterCollectedUrl(a) : b分支中的过滤调用也算)、TS 类型断言与await表达式;collectSafeLocals会把"由过滤函数初始化"的局部变量记入safeNames,使const q = filterCollectedUrlQuery(...)之后的{ url.query: q }不再误报;isTriviallySafe认为字符串/正则字面量、无插值模板字符串与undefined不可能携带查询串,直接放行——但注释提醒:若你的值确实不可能含查询串,应在本行 disable 该规则并说明理由,而不是依赖巧合。
对应过滤工具在浏览器侧的实际应用可参见 packages/browser/src/tracing/request.ts 与 packages/browser/src/integrations/httpcontext.ts 等文件,它们将采集到的 URL 交给过滤函数后再写入 span 属性。
no-unguarded-span-apis:浏览器端代码必须使用受保护的 span API
这条规则解决的是一个极其隐蔽的工程陷阱,源码 packages/eslint-plugin-sdk/src/rules/no-unguarded-span-apis.js 的注释给出了完整背景:
startSpan、startInactiveSpan、startSpanManual、startIdleSpan 这组 span 启动 API 在 @sentry/core 存在同名双变体:普通版(@sentry/core / @sentry/core/server)与受保护版(会在启动 span 前在 client 上安装 spanStreamingIntegration)。而浏览器 SDK 的 init() 刻意不引用该 integration——仅凭引用就会把整个 span streaming 依赖图带进所有 bundle(包括仅上报错误的包)。于是,若浏览器代码从根入口导入了普通版,编译照常通过,但创建的 span 永远不会被发送——静默失效。这条规则是唯一能拦截此问题的手段。
规则的核心是"哪些文件是浏览器面向的"判定表 BROWSER_FACING:
angular、browser、browser-utils、ember、feedback、gatsby、react、replay-canvas、replay-internal、solid、svelte、vue、wasm整包面向浏览器(true表示整个src以及 ember 的addon都算);astro、effect、nextjs、nuxt、react-router、remix、solidstart、sveltekit、tanstackstart-react仅src/client及其子路径面向浏览器——这些元框架包中的 server/edge/构建时代码必须继续使用普通版@sentry/coreAPI。
对通过判定的文件,规则检查 ImportDeclaration:从 @sentry/core 或 @sentry/core/server 导入上述四个 span API 名称即报错,提示改用 @sentry/core/browser(或 @sentry/browser)等受保护入口。同时细致地忽略 import type { startSpan } 这类纯类型导入——类型导入只用于签名,永远不会真正启动 span。
测试 packages/eslint-plugin-sdk/test/lib/rules/no-unguarded-span-apis.test.ts 完整验证了这些边界:
- 合法:浏览器文件从
@sentry/core/browser、@sentry/browser导入;@sentry/core的非 span 导入(如debug、spanToJSON);node、nextjs的 server 目录、effect的共享 tracer 文件(src/tracer.ts不属于src/client)继续使用普通版; - 非法:
packages/browser/src/...从@sentry/core导入startSpan、@sentry/core/server导入startIdleSpan、nextjs/src/client/routing.ts与effect/src/client/tracer.ts导入普通版、ember/addon/index.ts导入普通版,均产生unguardedSpanApi错误。
测试还特别说明:仓库当前缺少可用的 TypeScript ESLint parser(@typescript-eslint/parser@5 无法运行于 typescript@7),因此对 import type 的忽略逻辑通过直接驱动 visitor 的 ImportDeclaration 形状来验证——这也是测试工程里"以规则行为而非解析器为对象"的典型写法。
测试体系:RuleTester + Vitest
插件测试统一采用 ESLint 官方 RuleTester 驱动,再以 Vitest 组织用例,见 packages/eslint-plugin-sdk/test/lib/rules。每条规则测试都构造 valid(合法代码)与 invalid(非法代码 + 期望的 messageId/节点类型)两组用例,把规则行为固化为可回归的契约:
no-eq-empty.test.ts验证'[] === []'合法、'empty === []'非法并断言BinaryExpression节点类型;no-unsafe-random-apis.test.ts覆盖包裹形态、嵌套形态、非目标包裹器、多违规一次性上报以及new Date()构造器场景;no-unguarded-span-apis.test.ts通过伪造文件路径模拟不同包与目录的浏览器面向性,并对纯类型导入做定向单元验证。
仓库内运行测试的方式为 yarn test(对应 vitest run),详见 packages/eslint-plugin-sdk/package.json。
小结
@sentry/eslint-plugin-sdk 的 8 条规则并非通用代码风格建议,而是紧贴 Sentry SDK 工程现实的约束:从 no-class-field-initializers 对包体积的斤斤计较,到 no-unsafe-random-apis 对 React Server Components 缓存语义的适配,再到 no-unfiltered-url-attributes 与 no-unguarded-span-apis 对"静默失效"类问题的防守——它们共同构成了一条从构建产物、运行时安全到数据隐私的完整质量防线。阅读 packages/eslint-plugin-sdk/src/rules 下每条规则的源码与其测试,是理解 Sentry SDK 内部质量约束与工程取舍最直接的入口。