企业官网建设流程全解析

• 后端

Sails 从 v1.0 起内置了对helpers（辅助方法）的原生支持——这是一种把重复 Node.js 代码抽离为独立文件、并在多个位置复用的标准方案。本文以 Sails 官方文档中关于 Helpers 的核心概念为主线，结合本仓库的 helpers 钩子源码（lib/hooks/helpers/index.js、lib/hooks/helpers/private/load-helpers.js）与集成测试（test/integration/hook.helpers.test.js）深入讲解其定义规范、调用方式、异常处理与组织策略。读完本文，你将能够编写自校验、自文档化的可复用 helper，并在 action、自定义响应、命令行脚本、单元测试乃至其他 helper 中安全高效地调用它们。

为什么需要 Helpers

在开发基于 Sails 的应用时，你常常会在多个 action 中编写几乎相同的代码——例如重复的数据库查询、重复的字符串处理、重复的鉴权逻辑。这种复制粘贴既容易引入 bug，也让维护变得痛苦：某处逻辑需要调整时，你不得不同步修改多处。

Helpers 正是为解决这一问题而生的推荐方案：把重复代码抽取到单独的文件中，然后在各处复用。官方文档明确列出了 helpers 的典型使用场景：

• Actions 与 Controllers
• 自定义响应
• 命令行脚本（Sails 通过 Whelk 提供sails run脚本能力，参见 Shell 脚本）
• 单元测试
• 其他 helpers

一个最直观的例子：在 action 中把重复代码替换为对自定义 helper 的一次调用：

const greeting = await sails.helpers.formatWelcomeMessage('Bubba'); sails.log(greeting); // => "Hello, Bubba!"

只要代码所在位置能够访问到sails应用实例，helper 就可以被调用——这意味着应用启动之后的大部分代码路径都满足条件。

如何定义一个 Helper

Sails 中的每个 helper 就是一个位于api/helpers/目录下的 CommonJS 模块。以下是一个简单但规范完整的 helper 定义：

// api/helpers/format-welcome-message.js module.exports = { friendlyName: 'Format welcome message', description: 'Return a personalized greeting based on the provided name.', inputs: { name: { type: 'string', example: 'Ami', description: 'The name of the person to greet.', required: true } }, fn: async function (inputs, exits) { const result = `Hello, ${inputs.name}!`; return exits.success(result); } };

这个文件虽然简单，却体现了一个优秀 helper 的几大特征：

• 友好的名称与描述（friendlyName、description）：让代码读者一眼就能明白这个工具是干什么的；
• 声明式 inputs：清楚描述该工具接收哪些参数，便于理解如何调用；
• 单一职责：以最简单的方式完成一个离散的任务。

这种"机器规范"（machine specification）你并不陌生——Sails 的 Shell 脚本 与 actions2 风格的 action 遵循的是同一套规范，因此它们之间的知识可以互相迁移。

fn函数：helper 的核心

fn是 helper 真正执行逻辑的地方，它接收两个参数：

• inputs：输入值的字典（即"实参/argins"），helper 用它来获得调用者传入的数据；
• exits：回调函数字典，helper 用它把控制权交还给调用方。

需要特别注意的是：与普通 JavaScript 函数用return返回结果不同，helper 是通过把结果值传入exits.success(...)来"返回"的。

fn: async function (inputs, exits) { const result = `Hello, ${inputs.name}!`; return exits.success(result); }

Inputs：自校验的"函数参数"

helper 声明的inputs类似于普通 JavaScript 函数的参数——它们定义了代码要处理的数据。但关键区别在于：inputs 会被自动校验。如果调用时传入的实参类型与声明不匹配，或缺少某个required: true的输入，helper 会直接触发错误。因此，helpers 是**自校验（self-validating）**的。

每个 input 定义至少包含一个type属性，Sails 支持以下输入类型（与模型属性定义中的类型语义一致）：

在此基础上，你还可以为输入配置：

• defaultsTo：默认值；
• required: true：必填；
• allowNull：允许null；
• 以及几乎所有更高级的校验规则，例如isEmail。

调用 helper 时传入的实参按声明顺序对应 inputs 的键顺序；如果你更愿意按名称传参，可以链式使用.with()：

const greeting = await sails.helpers.formatWelcomeMessage.with({ name: 'Bubba' });

Exits：声明所有可能的结局

Exits 描述了 helper 所有可能的结果——无论好坏。每个 helper自动支持error和success两个出口：

• 当fn触发success时，helper 正常返回；
• 当fn触发success以外的其他出口时，helper 会抛出一个 Error（除非调用方使用了.tolerate()）。

你还可以暴露额外的自定义出口（称为"异常/exceptions"），让调用方代码能够针对性地处理特定例外场景。这保证了代码的透明度和可维护性——声明和协商错误变得轻松简单。

自定义出口定义在exits字典中。好的实践是：为每个自定义异常提供显式的description属性，这样 Sails 在必要时可以用它自动构造合适的 JavaScript Error 实例（针对非success出口）。

假设有一个名为inviteNewUser的 helper，暴露了一个emailAddressInUse自定义出口。当传入的邮箱已存在时，fn触发该出口，从而让调用方无需污染结果值、也无需手写大量try/catch就能处理这一具体场景。

例如，在自带badRequest出口的 action 中调用该 helper：

const newUserId = sails.helpers.inviteNewUser('bubba@hawtmail.com') .intercept('emailAddressInUse', 'badRequest');

上面这行漂亮的简写，等价于：

.intercept('emailAddressInUse', (err)=>{ return 'badRequest'; });

而.intercept()本身也只是另一个快捷方式，让你不必每次手动编写try/catch来协商这些错误。

在 helper 内部，fn负责触发其中一个出口——既可以通过抛出特殊的exit signal，也可以通过调用出口回调（例如exits.success('foo')）。如果 helper 通过 success 出口返回了结果（例如'foo'），该值就会成为 helper 的返回值。

同步 Helper（sync）

默认情况下，所有 helper 都被视为异步的。这是一个安全的默认假设，但并不总是事实。当你确定某个 helper 是同步的时，可以通过设置sync: true来告诉 Sails，从而允许调用方不使用await直接调用，以优化性能：

// api/helpers/foo-bar.js module.exports = { sync: true, fn: function (inputs, exits) { // 注意：不再是 async function！ return exits.success('...'); } };

重要提醒：不带await调用一个异步 helper 是不会生效的。如果你把sync设为true，务必把fn: async function改成fn: function！

在 Helper 中访问req

如果你要设计一个专门从 action 中解析请求头的 helper，可以利用请求对象（req）上现成的方法和属性。让 action 中的代码把req传给 helper 的最简单方式，就是定义一个type: 'ref'的输入：

inputs: { req: { type: 'ref', description: 'The current incoming request (req).', required: true } }

然后在 action 中这样使用：

const headers = await sails.helpers.parseMyHeaders(req);

生成一个 Helper

Sails 提供了内置生成器，可以自动创建新的 helper：

sails generate helper foo-bar

该命令会创建文件api/helpers/foo-bar.js，在代码中可通过sails.helpers.fooBar访问。初始生成的 helper 是一个没有任何 inputs、只有默认出口（success和error）的通用模板，执行时立即触发success出口。

如何调用一个 Helper

每当 Sails 应用加载时，它会找到api/helpers/目录下的所有文件，将其编译为可调用函数，并以**文件名的驼峰命名（camelCase）**作为键存入sails.helpers字典。之后，任何 helper 都可以通过在代码中带上await并传入实参来调用：

const result = await sails.helpers.formatWelcomeMessage('Dolly'); sails.log('Ok it worked! The result is:', result);

这种用法与你熟悉的模型方法（如.create()）大致相同。

.timeout(ms)：调用超时

.timeout()方法为 helper 的执行设置最大等待毫秒数。如果执行超过指定时间，会抛出TimeoutError：

// 如果 helper 耗时超过 5 秒则抛出 TimeoutError var result = await sails.helpers.someLongRunningTask() .timeout(5000);

传入0可以禁用 helper 实现中可能已设置的所有超时。

.retry(negotiationRule, retryDelaySeries)：指数退避重试

.retry()方法为 helper 调用附加一个指数退避重试策略：当 helper 失败时，会在延迟后自动重试。

// 使用默认延迟（250ms、500ms、1000ms）最多重试 3 次 var result = await sails.helpers.riskyOperation() .retry(); // 仅在 TimeoutError 时重试 var result = await sails.helpers.externalApiCall() .retry('TimeoutError'); // 自定义指数退避（4 次重试：1s、2s、4s、8s） var result = await sails.helpers.flakyService() .retry('TimeoutError', [1000, 2000, 4000, 8000]);

链式组合.timeout()与.retry()

这两个方法可以相互链式组合，也可以与.intercept()、.tolerate()等其他 helper 修饰符一起链式使用：

var data = await sails.helpers.externalApiCall(apiPayload) .timeout(10000) .retry('TimeoutError', [1000, 2000, 5000]) .intercept('serviceUnavailable', 'backboneError') .intercept((err) => { sails.log.error('API call failed:', err); return err; });

注意：当.timeout()与.retry()组合使用时，超时作用于每一次单独的尝试，而不是所有重试的总耗时。

同步调用

如果 helper 声明了sync属性，你也可以不用await直接调用：

const greeting = sails.helpers.formatWelcomeMessage('Timothy');

但在移除await之前，请确认该 helper 确实是同步的——没有await的异步 helper 永远不会执行！

组织 Helper：子目录分组

当应用的 helper 很多时，把相关 helper 分到子目录会更有条理。例如，假设有一批userhelper 和若干itemhelper，目录结构如下：

api/ helpers/ user/ find-by-username.js toggle-admin-role.js validate-username.js item/ set-price.js apply-coupon.js

调用时，每个子文件夹名（如user、item）会成为sails.helpers对象中额外的一层属性。于是你可以用sails.helpers.user.findByUsername()调用find-by-username.js，用sails.helpers.item.setPrice()调用set-price.js。

从源码看，这套机制的实现位于 lib/hooks/helpers/index.js 的furnishPack与furnishHelper方法：helper 定义会先经过 kebab-case 归一化，再按点分路径逐层构建"pack"（中间层容器）与最终的 callable。值得注意的是，源码中针对嵌套超过一层的 helper 会打印 verbose 提示——尽量保持目录扁平，用更明确的长文件名代替过深的目录层级，往往更利于维护和调用。

异常处理与"自动出口转发"

你可能习惯用设置错误码再检查错误的方式做精细化错误处理。这种方案可行，但费时且难以追踪。在 Sails helpers 中有几种更便捷的错误处理方式，详见：

• .tolerate()
• .intercept()
• 特殊 exit signals（参见 ActionsAndControllers）

自动出口转发（automatic exit forwarding）是另一个关键特性：调用方代码可以按需、逐例选择接入尽可能少或尽可能多的自定义出口。换句话说，调用 helper 时完全忽略它的自定义notUnique出口也没关系——你的代码因此保持简洁直观；而将来需求变化时，你随时可以回来补充对该自定义出口的处理。

源码视角：Helpers 钩子如何工作

深入本仓库源码，可以更好地理解 helpers 的加载与构建机制。

加载过程

应用启动时，lib/hooks/helpers/index.js 中定义的 helpers 钩子会在initialize阶段调用 lib/hooks/helpers/private/load-helpers.js：

1. 通过includeAll.optional()扫描sails.config.paths.helpers指向的目录（默认api/helpers/），正则过滤掉.md/.txt等非定义文件；
2. 若配置了sails.config.helpers.moduleDefinitions（实验特性，用于以编程方式注入 helper 字典），会浅合并到磁盘加载结果之上；
3. 对每个定义，将文件路径的各段做 camelCase 处理得到 key path（例如user-helpers/foo/my-helper→userHelpers.foo.myHelper），并把文件名作为强制identity；
4. 调用furnishHelper把定义构建为"wet machine"（可调用对象），挂载到sails.helpers上；任何构建失败都会以E_FAILED_TO_BUILD_CALLABLE错误码终止应用加载。

另外，源码还会检查 helper 定义中是否混入了 action 专属的属性（如files、responseType、viewTemplatePath、statusCode），一旦发现便打印警告——这些能力只能用于 action，helper 不可使用。

配置项：sails.config.helpers.usageOpts

钩子的defaults暴露了 helpers 的调用风格配置（lib/hooks/helpers/index.js）：

defaults: { helpers: { usageOpts: { arginStyle: 'serial', // 'serial' 按顺序传参 | 'named' 以字典传参 execStyle: 'natural' // 'natural'/'immediate' 立即执行 | 'deferred' 延迟执行（需 .now() 触发） }, moduleDefinitions: undefined } }

• arginStyle: 'serial'对应sails.helpers.foo('a', 'b')这种按声明顺序传参的写法；'named'则对应sails.helpers.foo({...})。
• execStyle: 'natural'表示同步 helper 调用后立即执行；'deferred'则返回一个"待执行"的 deferred 对象，需要调用.now()（或.execSync()）才会真正运行。

钩子在configure阶段会做一次向后兼容检测：如果应用package.json中的sails依赖指向1.0.0-44之前的预发布版本，会自动把usageOpts切换为{arginStyle: 'named', execStyle: 'deferred'}以保持旧行为，并在存在 helper 时打印升级提示。自 v1.0.0-44 起，默认风格变为 serial + natural，但.with({...})随时可以把调用切换为按名称传参。

测试验证

集成测试 test/integration/hook.helpers.test.js 验证了上述机制：

• 从磁盘加载api/helpers/greet.js，并与通过helpers.moduleDefinitions编程式注入的ucasehelper 合并（断言sailsApp.helpers中共有 2 个 helper）；
• 每个 helper 都是可调用函数，且都带有.with方法；
• 开箱即用地支持serial+natural风格与.with()命名传参，且两种方式结果一致；
• 支持.customize({arginStyle, execStyle})在调用层面临时切换风格。

实战示例：封装数据库查询的getRecentUsers

官方文档（docs/concepts/Helpers/ExampleHelper.md）给出了一个极具代表性的实践案例——把重复的数据库查询封装成 helper。假设应用的User模型有lastActiveAt字段记录最近登录时间，我们需要反复查询"最近在线的用户列表"，可以写成：

// api/helpers/get-recent-users.js module.exports = { friendlyName: 'Get recent users', description: 'Retrieve a list of users who were online most recently.', extendedDescription: 'Use `activeSince` to only retrieve users who logged in since a certain date/time.', inputs: { numUsers: { friendlyName: 'Number of users', description: 'The maximum number of users to retrieve.', type: 'number', defaultsTo: 5 }, activeSince: { description: 'Cut-off time to look for logins after, expressed as a JS timestamp.', extendedDescription: 'Remember: A _JS timestamp_ is the number of **milliseconds** since [that fateful night in 1970](https://en.wikipedia.org/wiki/Unix_time).', type: 'number', defaultsTo: 0 } }, exits: { success: { outputFriendlyName: 'Recent users', outputDescription: 'An array of users who recently logged in.', }, noUsersFound: { description: 'Could not find any users who logged in during the specified time frame.' } }, fn: async function (inputs, exits) { // 执行查询 var users = await User.find({ active: true, lastLogin: { '>': inputs.activeSince } }) .sort('lastLogin DESC') .limit(inputs.numUsers); // 如果没有找到用户，触发 noUsersFound 出口 if (users.length === 0) { throw 'noUsersFound'; } // 否则通过 success 出口返回记录 return exits.success(users); } };

调用方式

在 action 等应用代码中，使用默认选项调用：

var users = await sails.helpers.getRecentUsers();

传入参数以修改查询条件：

var users = await sails.helpers.getRecentUsers(50);

或者获取自 2017 年圣帕特里克节以来登录的最近 10 位用户：

await sails.helpers.getRecentUsers(10, (new Date('2017-03-17')).getTime());

这些在运行时传入 helper 的值有时被称为argins（或 options），它们与 helper 声明的 input 定义的键顺序（如numUsers、activeSince）一一对应。

同样，可以链式调用.with()使用命名参数：

await sails.helpers.getRecentUsers.with({ numUsers: 10, activeSince: (new Date('2017-03-17')).getTime() });

处理noUsersFound异常

要显式处理noUsersFound出口，而不是简单地把它当成一般错误，可以使用.tolerate()或.intercept()：

var users = await sails.helpers.getRecentUsers(10) .tolerate('noUsersFound', ()=>{ // ... 处理未找到用户的情况。例如： sails.log.verbose( 'Worth noting: Just handled a request for active users during a time frame '+ 'where no users were found. Anyway, I didn\'t think this was possible, because '+ 'our app is so cool and popular. But there you have it.' ); });

var users = await sails.helpers.getRecentUsers(10) .intercept('noUsersFound', ()=>{ return new Error('Inconceivably, no active users were found for that timeframe.'); });

这个例子的启示

使用 helpers 的最大优势在于：只需修改一处代码，就能更新应用许多地方的功能。例如，把numUsers的默认值从5改成15，所有使用该 helper 的位置返回的默认列表大小就都更新了。同时，得益于numUsers、activeSince这样定义良好的 inputs，一旦不小心传入了非法（非数值）值，你会立刻得到有帮助的错误提示。

几点补充说明：

• description、friendlyName等字段并非严格必需，但它们在保持代码可维护性上价值巨大——尤其是当 helper 要在多个应用间共享时；
• noUsersFound出口是否必要，取决于你的应用：如果你在无用户时总要执行特定动作（例如重定向到其他页面），这个出口就很有价值；反之，如果你只是根据是否有用户来微调视图中的文案，那么让success出口返回数组、在 action 或视图代码里检查length可能更合适。

进阶主题与下一步

• 与 actions2、shell scripts 的统一规范：helper 遵循与 Shell 脚本、actions2 相同的机器规范，同一套inputs/exits/fn心智模型可以复用。
• 与其他模块协同：helper 可以调用模型方法，也可以调用其他 helper；在自定义响应与单元测试中同样可以使用。
• sails-hook-organics：在"Web App"模板中捆绑的sails-hook-organics提供了大量免费、开源、MIT 许可的常用 helper，可直接借鉴其定义风格。
• 源码研读路径：若想进一步深入，可以从 lib/hooks/helpers/index.js（钩子入口与usageOpts配置）、lib/hooks/helpers/private/load-helpers.js（磁盘加载与构建）以及 test/integration/hook.helpers.test.js（行为验证）入手；machine与parley依赖（见 package.json）则提供了底层的 callable 构建与 Promise 化能力。

总结：Helpers 是 Sails v1.0 应用保持可维护性的核心工具。通过"声明式输入 + 自动校验 + 命名出口 + 声明式错误协商"这一套机制，你既能消灭重复代码，又能获得自文档化、自校验的高质量代码单元。从简单的formatWelcomeMessage到封装数据库查询的getRecentUsers，掌握这套模式后，你就能在自己的 Sails 应用中流畅地设计、生成、组织和调用 helpers 了。

• 后端