Sentry 官方 SDK ESLint 插件(@sentry/eslint-plugin-sdk)规则体系与源码深度解析

原创2026-10-10 20:15:131,435 阅读
文章标签:可观测性

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/core API。

对通过判定的文件,规则检查 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 内部质量约束与工程取舍最直接的入口。

登录后查看全文
sentry-javascript