Sails.js 稳定度指数（Stability Index）详解：如何解读 Hook 与核心文档中的四级稳定性标签

Sails.js 稳定度指数（Stability Index）详解：如何解读 Hook 与核心文档中的四级稳定性标签

【免费下载链接】sailsRealtime MVC Framework for Node.js项目地址: https://gitcode.com/gh_mirrors/sa/sails

在 Sails.js 仓库的文档与各类 README 中，你可以频繁看到形如 “Stability: 2 - Stable” 的标注。稳定度指数（Stability Index）是 Sails 用来向开发者声明「某个方法、事件、配置项或核心子模块」当前可信程度的一套分级体系，它基于 稳定度指数文档 中的四级定义（0 Deprecated、1 Experimental、2 Stable、3 Locked），帮助使用者在依赖框架 API、编写插件（Hook）或贡献代码之前，准确判断哪些接口可以放心长期依赖、哪些可能在未来的大版本中被修改甚至移除。本文完整梳理该指数的定义、适用范围与「显式公开」边界规则，并结合仓库中真实标注的核心 Hook 与文档，演示如何在实际开发中读懂和使用它。

一、为什么需要稳定度指数

Sails 框架仍在持续演进：随着框架不断成熟，不同部分的可靠性程度并不一致。有些能力（如核心的应用对象 API）经过长期验证、被广泛依赖，几乎不会改变；有些则是全新的实验性功能，或者已知存在问题、正在重构过程中。

因此，Sails 在文档和仓库内各模块的 README 中使用稳定度指数来标明每个章节、方法、事件、配置项以及核心子模块（如 core hooks）的稳定性。官方文档对这一机制的定位可以归纳为两点（见 docs/contributing/stability-index.md）：

• 对 API 而言：稳定度指数用于描述单独的方法（method）、事件（event）、配置项（configuration setting），告诉你该 API 在后续版本中可依赖的程度；
• 对子模块而言：指数同样适用于 Sails 核心中的子模块，例如各个核心 Hook。官方文档特别指出，对 Hook 打稳定度标签是一件「软科学」（a soft science）——核心团队给 Hook 标注稳定度，是为了让开发 Sails 插件以及向 Sails 核心贡献代码的开发者拥有更好的体验，是一种约定性的指引，而非严格的契约。

二、四级稳定度定义（完整继承原文档）

以下是 稳定度指数文档 给出的完整定义，按等级从低到高排列：

需要特别注意 0 级与 1 级的区别：0 级意味着「已知有问题 + 计划修改 + 不应期望向后兼容」，而 1 级只是「未来大版本中可能变化或移除」，尚属可用但需谨慎的状态。

三、适用范围与「显式公开」边界规则

稳定度指数的适用对象包括：

1. 单个方法（如某模型上的查询方法）；
2. 事件（如核心事件系统里的sails.on(*)生命周期事件）；
3. 配置项（如sails.config下的具体设置）;
4. Sails 核心的子模块，最典型的就是核心 Hook。

当稳定度指数指向一个模块（如某个核心 Hook）时，有一条容易被忽略但非常关键的边界规则（原文档明确强调）：

该指数只针对该 Hook明确公开（explicitly public）的功能负责。

原文档给出的例子是：如果某个 Hook 的文档提到它在sails应用对象上「暴露（exposes）」了一个名为foo的属性，那么你只有在文档的其他地方也明确将该属性标记为 “public” 时，才能依赖这个属性遵守该 Hook 声明的稳定度等级。换言之：

• Hook 的整体等级高（比如 2-Stable），并不代表它内部的所有属性、方法都可被外部依赖；
• 只有被文档显式标注为 public 的接口，才受该稳定度等级的保护；
• 如果不确定某个属性是否属于公开 API，官方文档建议的做法是：向该 Hook 的 README 文件提交一个 Pull Request，在其 FAQ 部分加上你的疑问（甚至可以先没有答案）。

这一规则与仓库中各 Hook README 的组织方式是吻合的——例如 lib/hooks/logger/README.md 中专门用「Exposesails.logfunction」「Addsails.log.ship()method」等小节列出该 Hook 对外暴露的能力，并单独列出「Events」小节描述其发射的事件（如hook:logger:loaded），这些正是判断「公开 API 边界」的依据。

四、仓库中的实际应用：核心模块如何标注稳定度

稳定度指数并非停留在概念层面，在 Sails 仓库源码树中，核心模块的 README 和代码注释里都能看到真实标注。以下列举若干有代表性的实例（标注原文均取自对应文件）：

4.1 核心事件系统（lib/EVENTS.md）

lib/EVENTS.md 在文件开头标注：

> ##### Stability: 2 - Unstable > > The API is in the process of settling, but has not yet had sufficient real-world testing > to be considered stable. Backwards-compatibility will be maintained if reasonable.

从该文件内容看，核心事件（sails实例是 Node EventEmitter）被定位为「面向核心贡献者与 Hook 开发者」的接口，并明确警告「请勿在应用代码中直接使用这些事件」。其文档还详细列出了生命周期事件（lifted、ready、lower、router:before/after/done/reset）、启动期事件（router:bind、router:unbind）与运行时事件（router:request、router:request:500、router:request:404、router:route），以及sails.on()/sails.once()/sails.after()三种监听用法——这些都是阅读核心事件稳定度标注时应该对照的具体 API 面。值得注意的是：从仓库现状看，该文件的标签写法（“2 - Unstable”）与 稳定度指数文档 对 2 级的命名（“Stable”）并不完全一致，属于早期文档标注的遗留差异；解读时建议以四级定义本身的语义为准，并结合文件内附带的说明文字（“正在定型中、尚未有足够实战测试”）综合判断。

4.2 Hooks 插件系统本体（Stability 2）

lib/hooks/README.md 将 Hooks 子系统整体标注为Stability: 2 - Stable。该文件说明 Hooks 是 Sails 为「让框架更模块化、更可测试」而引入的重大重构产物：如今 Sails 的大部分非核心（non-essential）功能都已拆成 Hook，可以被覆盖、禁用，也可以向项目中混入新的 Hook，从而演变成一套正式的插件系统。理解这一点有助于理解为什么稳定度指数要专门覆盖 Hook 这类「子模块」：插件生态（社区 Hook）需要知道 Hook 加载机制本身的可依赖程度。

4.3 各核心 Hook 的分级示例

仓库lib/hooks/目录下各 Hook 的 README 均在 “Status” 小节给出稳定度标注，可归纳为三个梯度：

这组示例恰好覆盖了 0、1、2 三个等级，展示了三种不同的标注位置：

• README 的 Status 小节：大多数 Hook（http、policies、responses、security、logger）采用；
• 代码文件头部的 JSDoc 注释：blueprints Hook 在 lib/hooks/blueprints/index.js 中直接标注；
• README 中的补充说明：logger Hook 在 0 级标签下额外解释了自己「几乎必然会被合并进 core（见 FAQ）」，其 FAQ 部分（lib/hooks/logger/README.md）解释了原因——核心配置流程本就在做这个 Hook 所做的事，因此它「不如直接并入 core」。这正是 0 级（Deprecated）标注的典型用途：明确告知用户「不要在新代码里依赖它的 Hook 形态」，并给出后续演进方向。

此外，核心应用对象本身在 lib/app/README.md 被标注为最高等级（Stability: 3），与sails.load/sails.lift等应用入口 API 长期稳定的事实相符（参见 lib/README.md 中「Sails.js 核心在应用以sails.load或sails.lift启动时运行」的说明）。

4.4 适配器规范文档中的细粒度标注

稳定度指数同样用于适配器接口规范。docs/contributing/adapter-specification.md 对规范的不同部分采用了不同等级：概述与接口契约部分标注为Stability: 3（对应原文第 9、53 行），而部分具体方法（如某些可选接口）标注为Stability: 1 - Experimental（对应原文第 91、124、136、168、182、202 行）。这说明稳定度标注可以做到「一份文档内部不同章节不同等级」的粒度，与文档中「指数用于描述 individual methods, events, and configuration settings」的定位一致。配套阅读 docs/contributing/intro-to-custom-adapters.md 可以看到适配器（adapter）作为 Waterline 标准化扩展点的背景——标注为 Experimental 的接口正是第三方适配器开发者需要重点关注的兼容风险区。

4.5 与 Node.js 稳定度指数的渊源

原文档在 Notes 部分明确指出：Sails 的稳定度指数以及该文档的大部分措辞，源自 Node.js 核心所采用的稳定度指数（Node.js API Documentation 中的 “Documentation Stability Index”）。仓库核心说明 lib/README.md 也重申了这一点，并给出了两个动机：

We use a slight variation of the stability index used by Node.js core; partially out of allegiance, but mostly for consistency.

即：一部分出于对 Node.js 的致敬（allegiance），但主要是为了一致性（consistency）——让熟悉 Node.js 官方文档分级体系的开发者，能用同样的心智模型阅读 Sails 文档。因此，如果你已经习惯 Node.js 文档中 “Stability: 0 (Deprecated) / 1 (Experimental) / 2 (Stable) / 3 (Locked)” 的读法，那么阅读 Sails 的 Hook 文档时几乎没有迁移成本。

五、实战用法：开发者与贡献者如何用好稳定度指数

结合原文档与仓库实践，可以总结出以下检查清单：

1. 阅读任何 Hook/API 文档时，先看 Status 小节的稳定度标签。它决定你对该接口的依赖策略：
   • 0（Deprecated）：升级前清理存量代码，新项目禁用；
   • 1（Experimental）：可用，但升级大版本时预留适配成本；
   • 2（Stable）：生产可用，大版本内默认不破坏兼容；
   • 3（Locked）：API 冻结，除非安全/性能关键修复，否则不会变化，也不应再向它提设计类变更提案。
2. 对 Hook 等级，务必核实「显式公开」边界。只有文档明确标为 public 的暴露面（暴露的属性、方法、发射的事件）才受该等级保护。以 lib/hooks/logger/README.md 为例，其公开面被明确列为：实例化 CaptainsLog 日志器、暴露sails.log()、增加sails.log.ship()方法、发射hook:logger:loaded事件、设置隐式默认配置sails.config.log.level（默认'info'）——这些是你可以对照其稳定度等级去依赖的部分。
3. 遇到模糊地带，走 FAQ 提问流程。原文档建议：如有疑问，向相应 Hook 的 README 提交 PR 并在其 FAQ 部分添加问题（「even if you don't have the answer」）。仓库中各 Hook README 都保留了这一 FAQ 模板（如 lib/hooks/README.md 的收尾提示），社区通过这种方式逐步把「公开边界」的疑问沉淀为文档事实。
4. 注意标注位置的三种形态：README Status 小节、实现文件 JSDoc 注释（blueprints）、规范文档的分章节标注（adapter-specification）。检索时不要只看 README，代码文件头注释同样是标注载体。
5. 以四级定义为解读基准。从仓库现状看，个别早期文档的标签文案（如 lib/EVENTS.md 写作 “2 - Unstable”）与 docs/contributing/stability-index.md 的标准命名存在出入；可以推断这是框架早期文档演进的遗留。使用时以四级定义（第二节表格）的语义为准，并结合标注文件内附带的说明文字做交叉印证。

六、小结

Sails 的稳定度指数是一份成本极低但信息量很高的「依赖风险说明书」：四级定义（0 Deprecated / 1 Experimental / 2 Stable / 3 Locked）覆盖了从「禁止新依赖」到「API 完全锁定」的完整光谱；其适用范围横跨方法、事件、配置项与核心子模块（尤其是 Hook），并对 Hook 引入了「只保护显式公开功能」的边界规则。在仓库中，你可以从 lib/EVENTS.md、lib/hooks/ 下各 Hook 的 README、lib/app/README.md 以及 docs/contributing/adapter-specification.md 中反复看到这套指数的真实应用。掌握它之后，你在评估「这个sails.*API 能不能进生产」「这个 Hook 升级后会不会挂」时，就有了仓库文档内可验证的明确依据。

【免费下载链接】sailsRealtime MVC Framework for Node.js项目地址: https://gitcode.com/gh_mirrors/sa/sails