编程语言编译器语言运行时标准库开发工具【免费下载链接】sdkThe Dart SDK, including the VM, JS and Wasm compilers, analysis, core libraries, and more.项目地址https://gitcode.com/gh_mirrors/sdk1/sdk点击查看免费下载lint 生命周期lint lifecycle是 Dart SDK 中pkg/linter包用来管理每一条 lint 规则成熟度与可见性的核心机制每一条规则都有且仅有一个当前状态同时它的全部状态变迁历史都会被记录在pkg/linter/messages.yaml中。本文以 lint-lifecycle.md 为骨架结合pkg/analyzer中的RuleState实现、pkg/linter的规则源码与生成工具系统讲解 lint 从提案、实验、稳定、废弃到移除的完整生命周期帮助 SDK 贡献者理解状态语义也帮助使用 lint 的开发者判断某条规则的可靠性等级。生命周期总览状态即契约每一条在pkg/linter中实现的 lint 规则都有一个状态state它同时描述两件事成熟度maturity规则的语义、实现与测试完备到什么程度是否公开可见publicly visible规则是否面向所有 Dart/Flutter 用户暴露、是否会出现在 IDE 的补全建议与官方文档中。一个 lint 的当前状态写在其实现文件里通过LintRule/AnalysisRule的super构造调用指定而它的完整状态历史则记录在 pkg/linter/messages.yaml 中——这保证了后人可以追溯这条规则是什么时候变的 stable、什么时候被 deprecated。需要注意的是lint 在被实现之前还要走一段提案proposal流程而提案阶段并不以状态形式记录也就是说提案 → 接受这一过程发生在代码之外只有进入实现后的状态才落在messages.yaml与源码里。实现之前Proposed 与 AcceptedProposed提案中一条 lint 的生命始于一份提案proposal。提案的状态是pending即等待 Dart developer experience 团队devexp 团队的裁决。这一阶段不写入任何状态字段对应仓库中也看不到对应的规则文件。Accepted已接受经过团队讨论并取得充分共识后提案被接受accepted规则随即进入待实现状态。从这一步开始规则才会以源码、测试与messages.yaml条目的形式进入仓库。一个重要的工程约定任何落地一条新的、公开可用lint 的变更change都应当附带对应的CHANGELOG条目——这一点在 pkg/linter/CHANGELOG.md 中持续累积也是 reviewer 检查新规则提交的硬性关注点。公开状态Public statesExperimental / Stable / Deprecated / Removed处在这四种状态的 lint 都是公开可用且有文档的。它们之间的区别在于稳定程度、变更风险与维护承诺。Experimental实验性实验性 lint 允许公开使用但随时可能被移除或变更且不会提前通知。文档 lint-lifecycle.md 明确列举了规则处于 experimental 的典型原因试探性地引入tentatively introduced价值尚不确定unknown value语义不完整incomplete semantics存在已知但可修复的误报outstanding but fixable false positives已知只是临时存在known to be temporary。实验性状态不是终点规则应当以成为 stable 为目标。一条 experimental lint 在满足以下条件时可以视为 stable 的候选语义完整complete semantics实现完整且没有已知误报no known false positives已被证明有长期价值——例如某个核心 lint 集core lint set正在考虑将其纳入。从源码可以看到当前仍处于 experimental 的规则例如 annotate_redeclares.dart 与 implicit_reopen.dart 都以const RuleState.experimental()声明状态。Stable稳定稳定 lint 公开可用通常测试与文档都比较完善并且未经通知就移除或变更的可能性大大降低。稳定状态意味着规则的语义与实现被视为完整complete误报属于 bug除非是已知且被文档记录的局限known and documented limitations修复误报应被优先处理漏报false negatives可能是 bug 也可能是增强具体取决于该 lint 的语义定义。稳定 lint 有可能被纳入核心规则集core rule sets例如官方package:lints推荐集。同时一条稳定 lint在移除前通常应先经历 deprecated 阶段——除非它在任何受支持的语言版本下都不再相关或不再有效。仓库中通过RuleState.stable(since: Version(...))指定稳定状态及其起始 SDK 版本例如 omit_obvious_local_variable_types.dart 与 specify_nonobvious_local_variable_types.dart 都以Version(3, 11, 0)为稳定起始版本。Deprecated已废弃Deprecated 意味着规则已计划在 SDK 的某个未来版本中被移除。文档列出的废弃原因包括语义与当前语言语义不再契合例如null safety 之后变得没有意义的规则建议已过时stale advice性能不佳poor performance开发者体验差例如误报过多生态中使用不足或价值不足insufficient usage or value。文档特别提醒废弃一条常见 lint 集如package:lints中的规则影响面很大必须谨慎行事。废弃后的 lint仍然公开可见、仍然有文档——这正是为了让用户能够了解为什么废弃、改用哪个替代规则。废弃变更同样要求CHANGELOG条目。仓库中的典型示例是 prefer_final_parameters.dart它以RuleState.deprecated(since: Version(3, 11, 0))声明从 3.11.0 起废弃同批的 avoid_null_checks_in_equality_operators.dart 也是如此。Removed已移除Removed 意味着规则不再被实现、也不再受支持。这个状态专门用于曾经公开可用的规则而那些从未公开、仅用于内部或测试的规则不需要经历 removed 状态详见下文私有状态。一般情况下移除之前会先经历一段废弃期deprecation。移除一条公开可用 lint 的变更同样需要CHANGELOG条目。在代码层面removed 状态由RuleState.removed(since: Version(...))表示。需要注意的是源码 rule_state.dart 中该构造函数已被标记为Deprecated(Use RemovedAnalysisRule instead)——从代码结构可以看出新的实现方式是通过RemovedAnalysisRule来声明已移除规则但状态历史仍完整保留在messages.yaml中。writing-lints.md中给出了一个典型的状态历史示例writing-lints.mdpackage_api_docs: # ... state: stable: 2.0 deprecated: 3.6 removed: 3.7这正体现了实现文件只写当前状态、messages.yaml记录完整历史的约定从 2.0 稳定3.6 废弃3.7 移除一目了然。私有状态Private statesInternal / Testing处于这两种状态的 lint不应出现在面向用户的工具补全建议中也不应被公开文档化。它们服务于 SDK 自身或测试流程普通用户不会也不应依赖它们。Internal内部Internal lint仅供 Dart SDK 内部使用。它们被移除时不需要迁移到 removed 状态——代码与配套文档直接删除即可因为它们从未对公众承诺过任何稳定性。仓库中的实例包括 analyzer_public_api.dart、analyzer_element_model_tracking.dart 以及 erase_dart_type_extension_types.dart均以const RuleState.internal()声明。在messages.yaml中它们则记录为internal: 3.10之类的历史版本信息。Testing测试Testing lint 是仅供内部测试使用的临时规则。它的使用范围不限于 Dart SDK其他测试环境也可以引用但没有任何稳定性保证也不面向公开使用。文档给出了两条硬性约定lint不应无限期停留在 testing 状态测试完成后规则必须被移除或升格到其他状态graduated。同样地testing 规则被移除时不需要经过 removed 状态代码与文档可直接删除。在RuleState的实现中rule_state.darttesting 状态被描述为 experimental, temporary, and have no stability guarantees与文档语义完全吻合。状态在代码中的落地三处记录、一份生成产物理解生命周期后可以沿着仓库源码看清状态机制的真实实现。规则状态在pkg/linter中一共有三个落点1. 类型定义RuleStaterule_state.dartRuleState是pkg/analyzer中定义的final class提供了与六种状态一一对应的命名构造函数构造函数语义额外字段RuleState.deprecated已废弃since起始版本、replacedBy替代规则名RuleState.experimental实验性sinceRuleState.internal仅 SDK 内部sinceRuleState.removed已移除已弃用改用RemovedAnalysisRulesince、replacedByRuleState.stable稳定sinceRuleState.testing内部测试since每个构造函数还对应一个只读判断属性isDeprecated、isExperimental、isInternal、isRemoved、isStable、isTesting以及用于文档展示的label。注意since是可选的Version类型——它记录的是该状态起始的 Dart 版本这正是当前状态 历史版本信息模型的基础。2. 实现文件当前状态pkg/linter/lib/src/rules每条规则的实现文件中super构造调用只指定最新的状态。例如PackageApiDocs() : super( name: LintNames.package_api_docs, description: _desc, state: State.removed(since: Version(3, 7, 0)), );3. 元数据文件完整历史pkg/linter/messages.yamlmessages.yaml中的state字段按从旧到新的顺序列出全部历史状态并附带每个状态的起始版本号。该文件头部注释也给出了编辑后的必做步骤messages.yamldart run pkg/linter/tool/generate_lints.dart dart run pkg/analyzer/tool/messages/generate.dart其中generate_lints.dart负责重新生成LintNames与LinterLintCode静态访问器machine.dartdart run pkg/linter/tool/machine.dart -w负责更新旧的rules.json机器可读清单位于 pkg/linter/tool/machine/rules.json。writing-lints.md中还有专门的 Generating docs 章节强调修改messages.yaml或 super 构造信息后必须重新生成相关文件保证产物与元数据一致。状态迁移的实战建议与测试保障综合文档与源码可以总结出几条可供 SDK 贡献者直接遵循的迁移路径提案先行先提交提案等 devexp 团队接受后再动手实现避免把未接受的想法直接写成代码。新规则从 experimental 起步语义未定、可能误报时保持 experimental补齐语义与实现、确认无已知误报、看到长期价值如被核心 lint 集考虑后再提升为 stable。废弃要有充分理由语义过时如 null safety 之后、建议过时、性能差、误报过多、生态价值不足——这些都是文档认可的废弃依据废弃常见 lint 集中的规则要格外谨慎因为影响面大。移除前先废弃一般流程是 stable → deprecated → removed只有规则在所有受支持语言版本下都不再相关时才可跳过废弃直接移除。private 状态可以原地删除internal 与 testing 规则不需要走 removed 状态删除代码与文档即可但要遵守testing 不得长期滞留的约定。每次状态变更都要写 CHANGELOG新增、废弃、移除公开 lint 的变更都必须附带 pkg/linter/CHANGELOG.md 条目。仓库为这些状态语义还提供了配套的校验测试例如 test/rules/analyzer_public_api_test.dart 等针对 internal 规则的测试、以及 verify_generated_files_test.dart 这类验证生成产物与元数据一致性的测试。运行 linter 全部测试的方式在 writing-lints.md 中有说明dart run pkg/linter/test/all.dart由于 linter 与pkg/analyzer、pkg/analysis_server紧密耦合涉及这两处的改动还应运行dart run pkg/analyzer/test/test_all.dart dart run pkg/analysis_server/test/test_all.dart小结lint 生命周期本质上是 Dart 团队对一条规则从想法到退休的全过程治理提案Proposed→ 接受Accepted→ 实验Experimental→ 稳定Stable→ 废弃Deprecated→ 移除Removed构成公开规则的主干演进路径而Internal与Testing则划定了 SDK 内部与测试用规则的私有边界。对贡献者而言理解这套状态机意味着知道何时该把规则定为 experimental、何时可以升 stable、废弃与移除各有什么前提、CHANGELOG 何时必须更新对使用者而言官方文档与messages.yaml中的状态历史就是判断一条 lint 可靠性最直接的依据——stable可以放心纳入核心规则集experimental则要接受可能随时变更或移除的风险。赞分享编程语言编译器语言运行时标准库开发工具【免费下载链接】sdkThe Dart SDK, including the VM, JS and Wasm compilers, analysis, core libraries, and more.项目地址https://gitcode.com/gh_mirrors/sdk1/sdk点击查看免费下载相关推荐OpenSandbox OSEP 提案流程完全指南从 init-osep.sh 到状态生命周期OpenSandbox OSEP 提案流程完全指南从 init osep.sh 到状态生命周期 OpenSandbox 采用 OSEPOpenSandbox人工智能AI 应用Agent 沙箱云原生后端代码智能体编写 Dart Linter 规则Writing LintsDart SDK 内置 Linter 规则开发的完整指南编写 Dart Linter 规则Writing LintsDart SDK 内置 Linter 规则开发的完整指南 引言 pkg/linter/doc/编程语言编译器语言运行时标准库开发工具JupyterLab 版本生命周期Version Lifecycle完全指南维护期规则、支持状态与升级规划JupyterLab 版本生命周期Version Lifecycle完全指南维护期规则、支持状态与升级规划 JupyterLab 以主版本major v前端后端数据科学开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考