Sails 可安装钩子（Installable Hooks）开发完全指南：创建、命名、测试与发布-平芜编程栈

Sails 可安装钩子（Installable Hooks）开发完全指南：创建、命名、测试与发布

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

导读

可安装钩子（Installable hooks）是 Sails 中一类以独立 npm 模块形式存在、通过安装到应用node_modules目录来扩展框架能力的插件机制。本篇指南以 installablehooks.md 为骨架，完整讲解钩子的创建步骤、package.json关键配置、内部命名覆盖（sails.hookName）、基于 Mocha 的测试脚手架以及npm publish发布流程，并对照 moduleloader 与 userhooks 的源码实现，带你理解 Sails 在启动时究竟如何扫描、校验和加载这些钩子。读完本文，你将能够独立开发、测试并发布一个可被任意 Sails 应用复用的官方风格钩子模块。

什么是可安装钩子

在 Sails 的钩子体系中，钩子分为三类（见 Hooks.md）：

核心钩子（Core hooks）：随 Sails 内置，提供请求处理、blueprint 路由、Waterline 数据库集成等基础能力，例如 default-hooks.js 中列出的moduleloader、logger、request、views、blueprints、responses、helpers、pubsub、policies、services、security、i18n、userconfig、session、http、userhooks。
应用级钩子（Project hooks）：存放在单个应用自身的api/hooks目录，适用于无需跨应用共享的代码。
可安装钩子（Installable hooks）：存放在应用的node_modules目录，通过npm install安装，是社区之间共享功能、向 Sails 生态发布插件的主要方式。

可安装钩子适合"想在多个 Sails 应用之间复用功能，或把钩子发布到 npm 与社区共享"的场景；如果只想在一个应用内使用，请参考创建项目钩子。

创建一个可安装钩子

创建可安装钩子只需四步：

1. 为钩子命名

钩子名称不得与任何核心钩子名称冲突，核心钩子清单见 default-hooks.js。推荐以sails-hook-作为前缀（例如sails-hook-your-hook-name），该前缀是可选的但强烈建议保留，因为 Sails 在加载钩子时会自动将其剥离。

2. 创建钩子目录

在本地创建名为sails-hook-<your hook name>的文件夹。命名空间与sails-hook-前缀的实际剥离逻辑，可以从 moduleloader/index.js 中loadUserHooks的实现得到印证：Sails 通过正则identity.replace(/^(@.+?[\/\\])?(sails-hook-)?/, '')计算出钩子在sails.hooks字典中的身份（identity），因此sails-hook-email最终会以email的身份被加载。

3. 创建 package.json

在文件夹中创建package.json。如果系统装有 npm，直接运行npm init并按提示填写即可；也可以手动创建，至少需要包含以下字段：

{ "name": "sails-hook-your-hook-name", "version": "0.0.0", "description": "a brief description of your hook", "main": "index.js", "sails": { "isHook": true } }

其中最关键的是sails键下的isHook: true——这是 Sails 识别一个 npm 模块是否为钩子的标志。如果使用npm init生成文件，务必在生成后手动补上这一项。对照源码可以看到，loadUserHooks在扫描node_modules时会读取每个包的package.json，并执行if (!packageJson.sails || !packageJson.sails.isHook) { return; }来过滤非钩子模块（见 moduleloader/index.js）。

4. 编写钩子代码

在index.js中按照钩子规范编写钩子。钩子的基本形态是一个接收sails实例并返回对象（含defaults、configure、initialize、routes、registerActions等可选特性）的模块：

module.exports = function myInstallableHook(sails) { return {}; }

即便这个最小实现什么也不做，Sails 也能成功加载它。

钩子目录中还可以包含其他任意文件，供钩子内部通过require加载；只有index.js会被 Sails 自动读取。钩子运行时需要的第三方依赖，请声明在package.json的dependencies键中（也可以用npm install <dependency> --save自动写入）。

指定 Sails 内部使用的钩子名（高级用法）

在某些情况下——尤其是使用scoped npm 包（形如@mycoolhooks/xxx）来覆盖某个核心钩子时——你可能希望改变 Sails 内部加载钩子时使用的名称。此时可以在package.json中使用sails.hookName配置项。该值将作为钩子加载进sails.hooks字典的键名，因此通常不要带sails-hook-前缀。

例如，假设你有一个模块@mycoolhooks/sails-hook-sockets，希望用它覆盖核心sails-hook-sockets模块，package.json可以这样写：

{ "name": "@mycoolhooks/sails-hook-sockets", "version": "0.0.0", "description": "my own sockets hook", "main": "index.js", "sails": { "isHook": true, "hookName": "sockets" } }

从源码看，钩子身份的解析遵循以下优先级（见 moduleloader/index.js）：

若package.json中配置了非空的sails.hookName，直接采用该值；
否则若sails.config.installedHooks中对该模块指定了name，采用之；
否则将模块名中的 npm 命名空间与sails-hook-前缀剥离后作为钩子名。

需要提醒的是，scoped 包能正常被发现的前提是模块位于node_modules下的命名空间目录中——源码在扫描时只会在node_modules直接子目录，以及形如node_modules/@something的命名空间目录内递归查找package.json（见 moduleloader/index.js）。

Sails 启动时如何发现并加载你的钩子

理解加载机制有助于排查"钩子没生效"之类的问题。整个过程由userhooks钩子与moduleloader钩子协作完成：

userhooks钩子的initialize方法调用sails.modules.loadUserHooks()收集所有用户钩子（见 userhooks/index.js）。注意它要求moduleloader钩子必须启用，否则直接报错'Cannot load user hooks withoutmoduleloaderhook enabled!'。
loadUserHooks同时扫描两个来源：应用api/hooks目录下的项目钩子，以及node_modules下所有声明sails.isHook: true的包（见 moduleloader/index.js）。
对于node_modules中发现的钩子，还会做如下校验与处理：
- 必须是应用声明的依赖：钩子必须出现在应用package.json的dependencies、devDependencies或optionalDependencies中，否则会被忽略并输出 debug 日志（moduleloader/index.js）；
- 核心钩子可被覆盖：当node_modules中的钩子与default-hooks.js中列为插件的核心钩子同名时会被放行，从而实现对核心钩子的安全覆盖（moduleloader/index.js）；
- api/hooks 优先级更高：若node_modules中的钩子与应用api/hooks中的项目钩子身份冲突，Sails 会发出E_INVALID_HOOK_NAME警告并选择api/hooks中的实现（moduleloader/index.js）；
- 可通过配置禁用：如果sails.config.hooks中将该钩子设为false，则跳过加载（moduleloader/index.js）。
收集完毕后，userhooks钩子还会依据sails.config.loadHooks（若设置）做二次过滤，最后将所有用户钩子并入sails.hooks（见 userhooks/index.js）。

此外，如果你需要在已有应用级钩子同名时调整钩子身份与配置键，Sails 还提供了sails.config.installedHooks.<hook-identity>配置（身份始终是钩子安装所在目录的文件夹名），详见 usinghooks.md。

测试你的新钩子

在分发钩子之前，务必为其编写测试，以确保与未来 Sails 版本的兼容性。虽然完整的测试编写指南超出本文范围，但以下步骤足够帮助你起步：

1. 将 Sails 声明为 devDependency

在钩子自己的package.json中加入：

"devDependencies": { "sails": "~0.11.0" }

说明：示例中的~0.11.0为撰写文档时的 Sails 版本；实际开发时请替换为你需要保证兼容的 Sails 版本。也可以在本仓库的 test/ 目录中参考官方集成测试的组织方式，例如 test/integration/hook.helpers.test.js 等钩子相关测试。

2. 安装 Sails 与 Mocha

npm install sails # 或者，如果全局安装了 Sails： npm link sails npm install -g mocha

3. 添加测试文件

在钩子主目录下创建test文件夹，并添加basic.js，内容如下：

var Sails = require('sails').Sails; describe('Basic tests ::', function() { // Var to hold a running sails app instance var sails; // Before running any tests, attempt to lift Sails before(function (done) { // Hook will timeout in 10 seconds this.timeout(11000); // Attempt to lift sails Sails().lift({ hooks: { // Load the hook "your-hook-name": require('../'), // Skip grunt (unless your hook uses it) "grunt": false }, log: {level: "error"} },function (err, _sails) { if (err) return done(err); sails = _sails; return done(); }); }); // After tests are complete, lower Sails after(function (done) { // Lower Sails (if it successfully lifted) if (sails) { return sails.lower(done); } // Otherwise just return return done(); }); // Test that Sails can lift with the hook in place it ('sails does not crash', function() { return true; }); });

这段测试的核心思路是：通过Sails().lift()显式启动一个最小化的 Sails 实例，在hooks配置中将钩子指定为require('../')（即钩子自身的入口），同时关闭grunt以避免不必要的构建流程；before中完成 lift，after中执行sails.lower(done)优雅关闭，从而验证"带着钩子时 Sails 可以正常启动"。

4. 运行测试

mocha -R spec

完整断言与异步测试的写法，可参考 Mocha 的官方文档。

发布你的钩子

假设钩子已经测试通过、表现良好，且该名称未被其他 npm 模块占用，运行以下命令即可与世界分享：

npm publish

发布后，任何 Sails 应用都可以通过npm install sails-hook-<your-hook-name> --save安装使用它（安装方式详见 usinghooks.md）。

与其他钩子文档的关联

Hooks 总览：三类钩子的整体介绍
在应用中使用钩子：安装、调用钩子方法、配置钩子与installedHooks配置
钩子规范（Hook Specification）：defaults、configure、initialize、routes、registerActions等钩子特性的完整定义
创建项目钩子：与可安装钩子互补的api/hooks方案
核心钩子清单：命名冲突检查时参考
钩子加载实现与 userhooks 钩子实现：loadUserHooks的源码级细节