Rome 工具链noDuplicateJsonKeys规则详解禁止 JSON 对象中的重复键【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址: https://gitcode.com/gh_mirrors/to/toolsnoDuplicateJsonKeys是 Rome 内置 JSON 检查器rome_json_analyze中的一条 lint 规则用于禁止同一个 JSON 对象内出现两个同名字符串键。本指南以该规则为核心完整讲解它的触发条件、诊断输出、配置方式并结合仓库源码剖析其基于语法树CST与HashMap的检测实现帮助你在rome check/rome lint流程中有效拦截由重复键导致的配置覆盖与数据歧义问题。规则概述Disallow two keys with the same name inside a JSON object. 禁止在 JSON 对象内使用两个同名键。这条规则在文档中的定位为nursery分组实验性规则版本标记为since vnext。从源码看它通过declare_rule!宏声明关键元数据如下见 no_duplicate_json_keys.rs规则名noDuplicateJsonKeys版本next推荐状态recommended: true已进入推荐规则集在 nursery 分组定义 中no_duplicate_json_keys是当前Nursery组唯一的 JSON 规则并在 规则配置定义 中被列入GROUP_RULES与RECOMMENDED_RULES两个常量数组——这意味着它既可以被显式配置也会随推荐规则集默认启用后续“配置方式”一节会说明如何调整。为什么需要这条规则重复键的“最后定义生效”陷阱JSON 规范本身允许对象中出现重复键且大多数解析器包括 JavaScript 的JSON.parse在遇到重复键时只保留最后一个定义。这会带来两类实际风险配置覆盖在rome.json、package.json、tsconfig.json等配置文件中重复键会静默覆盖前值排查成本极高数据歧义同一数据被不同模块读取时可能因为解析顺序或实现差异得到不同结果。该规则的诊断信息明确指出了这一语义见 源码第 103-107 行 与 快照If a key is defined multiple times, only the last definition takes effect. Previous definitions are ignored. 如果某个键被多次定义只有最后一个定义生效之前的定义会被忽略。触发与通过示例无效示例触发诊断{ title: New title, title: Second title }当对象中存在两个同名键title时规则会在首次声明处报错并为每个重复声明位置附加“再次声明”的定位信息。CLI 输出的诊断大致如下nursery/noDuplicateJsonKeys.js:2:3 lint/nursery/noDuplicateJsonKeys ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✖ The key title was already declared. 1 │ { 2 │ title: New title, │ ^^^^^^^ 3 │ title: Second title 4 │ } ℹ This where a duplicated key was declared again. 1 │ { 2 │ title: New title, 3 │ title: Second title │ ^^^^^^^ 4 │ } ℹ If a key is defined multiple times, only the last definition takes effect. Previous definitions are ignored.注意诊断的高亮范围是键名本身title而不是整个键值对便于在长值场景下快速定位冲突键。有效示例通过检查{ title: New title, secondTitle: Second title }只要键名不重复即使值相同或键风格不同camelCase等也不会触发。源码级原理基于 CST 与 HashMap 的检测实现规则实现位于 crates/rome_json_analyze/src/analyzers/nursery/no_duplicate_json_keys.rs整体采用 Rome 分析框架的Ruletrait 模式核心流程分为run收集与diagnostic报告两个阶段。1. 查询对象AstJsonObjectValue规则通过type Query AstJsonObjectValue声明自己只对JSON 对象值节点生效因此数组、标量与字符串内容不会被误报。这一机制由 Rome 的分析器架构提供——分析器会遍历语法树只把匹配该查询类型的节点交给规则处理。2. 收集重复键run阶段let mut names HashMap::String, VecTextRange::new(); let mut original_key None; for (index, member) in query.json_member_list().iter().flatten().enumerate() { let name member.name().ok()?; if index 0 { original_key Some(name.clone()); } let text name.inner_string_text().ok()?; if let Some(ranges) names.get_mut(text.text()) { ranges.push(name.range()); } else { names.insert(text.text().to_string(), vec![]); } }关键实现要点见 源码第 49-81 行遍历JsonObjectValue的成员列表json_member_list()对每个成员提取JsonMemberName通过inner_string_text()获取去引号后的键名字符串作为HashMapString, VecTextRange的键首次出现的键记录空列表再次出现的键把语法树文本范围TextRange追加进列表若存在非空范围列表则构造DuplicatedKeys状态其中original_key记录对象第一个成员的键作为“正确的那一个”duplicated_keys记录所有重复声明的位置。从这段代码可以推断规则的比较基准是去引号后的键名字符串因此title与title 带空格会被视为不同键而转义序列是否归一化取决于解析器对inner_string_text()的处理。3. 生成诊断diagnostic阶段let mut diagnostic RuleDiagnostic::new( rule_category!(), original_key.range(), markup! { The key Emphasis{{original_key.inner_string_text().ok()?.text()}}/Emphasis was already declared. }, ); for range in duplicated_keys { diagnostic diagnostic.detail( range, markup! { This where a duplicated key was declared again. }, ); }诊断以第一个声明位置为主定位消息The key ... was already declared.随后对每个重复声明依次附加detail定位This where a duplicated key was declared again.最后追加一条说明“最后定义生效”的note见 源码第 83-108 行。这种“一次报错、多处定位”的设计让开发者能一次性看清同一键的全部冲突位置。4. 测试佐证仓库为规则提供了独立的规格测试用例见 crates/rome_json_analyze/tests/specs/nursery/noDuplicateJsonKeys/invalid.json同一键foo连续声明 4 次invalid.json.snap 显示会生成 3 条重复定位 1 条语义说明valid.jsonfoo与bar各声明一次不产生诊断。这些测试由rome_json_analyze的spec_tests.rs驱动验证了规则在真实解析管线上的行为。配置方式开启、关闭与设为警告规则位于nursery分组。在rome.json中可针对该规则单独配置支持error/warn/off三档以及带选项的对象形式。配置解析逻辑见 crates/rome_service/src/configuration/parse/json/rules.rs#L1952-L1974它同时接受字符串JsonStringValue与对象JsonObjectValue两种写法其他类型如数字、布尔会抛出“object or string”类型错误。{ linter: { rules: { nursery: { noDuplicateJsonKeys: error } } } }可选的带选项形式规则当前无自定义选项Options ()对象写法主要用于统一规则的level字段{ linter: { rules: { nursery: { noDuplicateJsonKeys: { level: warn } } } } }由于规则声明为recommended: true见 linter/rules.rs 的 RECOMMENDED_RULES 数组在未显式配置时它会随推荐规则集默认启用如需整体关闭推荐集或单独豁免该规则可使用 linter 文档 中说明的全局/分组开关或按文件添加行内抑制注释。在 CLI 中的实际验证rome check与rome lint都会执行该规则。仓库的 CLI 集成测试 crates/rome_cli/tests/commands/check.rs#L2589-L2630 提供了一个端到端场景测试文件test.json内容为{ foo: true, foo: true }rome.json显式配置nursery: { noDuplicateJsonKeys: error }执行rome check test.json断言命令返回错误result.is_err()并生成 check_json_files 快照 记录完整诊断输出。这也印证了配置优先级即使规则属于推荐集也可以在配置文件中用显式error提升为硬性错误使 CI 在存在重复键时直接失败。使用建议配置文件优先开启对rome.json、package.json、tsconfig.json等项目级 JSON 文件建议保持error级别杜绝静默覆盖注意键名比较规则规则按去引号后的字符串比较title与title 不算重复若团队对键名空白敏感可结合 JSON 格式化流程统一风格定位信息阅读诊断的主定位是首次声明detail定位是后续重复声明note说明语义影响三者结合可快速修正nursery 分组状态规则当前位于nursery实验性分组随版本演进可能调整行为或变更分组升级工具后应复查相关快照与配置。相关链接禁用一条 lint 规则Disable a rule规则选项Rule options规则源码实现规则分组声明规则配置定义配置解析逻辑规则规格测试CLI 端到端测试【免费下载链接】toolsUnified developer tools for JavaScript, TypeScript, and the web项目地址: https://gitcode.com/gh_mirrors/to/tools创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考