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.jsapi/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 与 Mochanpm install sails # 或者如果全局安装了 Sails npm link sails npm install -g mocha3. 添加测试文件在钩子主目录下创建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中完成 liftafter中执行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 Specificationdefaults、configure、initialize、routes、registerActions等钩子特性的完整定义创建项目钩子与可安装钩子互补的api/hooks方案核心钩子清单命名冲突检查时参考钩子加载实现 与 userhooks 钩子实现loadUserHooks的源码级细节【免费下载链接】sailsRealtime MVC Framework for Node.js项目地址: https://gitcode.com/gh_mirrors/sa/sails创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考