Sails 框架 CHANGELOG 全解读:从 0.10 到 1.2 的关键演进、破坏性变更与源码级验证

原创2026-09-19 13:54:111,760 阅读
文章标签:后端

Sails 框架 CHANGELOG 全解读:从 0.10 到 1.2 的关键演进、破坏性变更与源码级验证

导读

Sails 是基于 Express 与 Socket.io 的实时 MVC 框架,本仓库(package.json)当前版本为 1.5.18。本文以仓库根目录下的 CHANGELOG.md(共 853 行)为骨架,完整梳理 Sails 从 0.10 到 1.2 各版本的功能增强(ENHANCEMENT)、破坏性变更(REMOVAL)、缺陷修复(BUGFIX)与内部重构(INTERNAL),并结合 lib/ 下的真实源码与 test/ 测试用例进行验证。读完本文,你将理解 Sails 核心机制(Actions 2、Helpers、蓝图 Blueprints、钩子 Hooks、虚拟请求解释器)的演进脉络,掌握 sails migrate、sails.getActions()、Model.updateOne() 等关键能力的正确用法,并能在升级项目时准确评估每个版本的兼容性影响。

版本总览:一条从 0.10 通往 1.x 的演进主线

CHANGELOG 覆盖了 Sails 的主要历史版本,其演进主线可以概括为三个阶段:

版本 定位 核心主题
0.10.x 早期稳定版 Waterline 0.10、CSRF routesDisabled 选项
0.11.x 架构拆分期 sockets 钩子独立成仓、Socket.IO 0.9→1.2.1、可安装式钩子
0.12.x 1.0 前夜 大量内部重构、基准测试引入、CORS/CSRF 细节打磨
1.0.0 里程碑大版本 Actions 2、Helpers、Express 4、Security 钩子、大量移除项
1.1.0 渐进增强 updateOne()/destroyOne()/archiveOne()、可省略 exits、.timeout()/.retry()
1.2.0 稳定性优化 sails migrate、依赖安全升级、蓝图内部简化

1.2.0:实验性迁移命令与稳定性收尾

1.2.0 是 CHANGELOG 记录的最近一个完整版本条目,其改动集中在 CLI 工具、加载逻辑、蓝图实现与依赖安全四个方面。

新增 sails migrate 命令

Added sails migrate for quickly running auto-migrations by hand

该命令的实现位于 bin/sails-migrate.js,并在 bin/sails.js 中注册。其工作流程为:

  1. 加载(但不 lift)当前工作目录下的 Sails 应用;
  2. 跳过 Grunt 钩子(grunt: false),因为自动迁移不需要前端构建;
  3. 运行应用的 bootstrap 函数后直接退出;
  4. 优先使用应用本地安装的 Sails(node_modules/sails),否则回退到全局安装版本。

源码中的注释给出了两种典型用法:

# 运行 "alter" 自动迁移,尝试调整所有数据(但可能删除数据)
sails migrate

# 运行 "drop" 自动迁移,清空所有数据
sails migrate --drop

需要特别注意的是,sails migrate 在源码中明确标注为 @stability EXPERIMENTAL(实验性),因此生产环境中使用前应先评估其风险。

钩子加载的显式白名单语义

When loading user hooks, if sails.config.loadHooks is specified, skip hooks whose names aren't explicitly included

这条改动强化了 sails.config.loadHooks 的白名单语义:一旦你在配置中显式指定了要加载的钩子列表,未列入其中的钩子将被跳过。这与 1.2.0 之前"loadHooks 只影响加载顺序、不影响加载集合"的行为不同,是升级时需要留意的行为变化。钩子机制本身是 Sails 一切功能的载体,核心钩子列表可在 lib/hooks/index.js 中查看,从源码结构看包括 blueprints、helpers、http、i18n、logger、policies、pubsub、request、responses、security、services、session、views 等。

bootstrap 超时警告从 5 秒放宽到 30 秒

Increased time to display warning message in config/bootstrap.js from 5 seconds to 30 seconds

对应源码在 lib/app/private/bootstrap.js:当 bootstrap 函数执行超过 sails.config.bootstrapTimeout(默认 30000 毫秒)时,Sails 才会在控制台输出警告。这意味着 bootstrap 中如果包含耗时较长的初始化逻辑(如预热缓存、建立第三方连接),默认有 30 秒的宽限期,不再像 0.x 时代那样 5 秒就报警。

蓝图 update 动作改用 updateOne

Switched to using updateOne in the "update" blueprint Blueprint queries no longer include fetch: true by default, to avoid warnings from updateOne

在 lib/hooks/blueprints/actions/update.js 中可以看到,update 蓝图动作现在调用 Model.updateOne(criteria).set(queryOptions.valuesToSet).meta(queryOptions.meta)。该动作的完整流程是:

  1. 先用 Model.findOne() 找到原始记录(为前端提供更好的集成体验,并可广播 previous 值);
  2. 用 updateOne() 精确更新单条记录;
  3. 若存在 pubsub 钩子,向订阅者广播更新事件;
  4. 最后再查询一次以返回填充(populate)关联后的完整记录。

同时,蓝图查询默认不再附带 fetch: true,以避免 updateOne 产生多余警告。create 蓝图(lib/hooks/blueprints/actions/create.js)仍使用 Model.create(),但在创建多对一关联时会预先检查子记录是否已有父记录,以发送正确的 removedFrom 通知。

虚拟响应解释器的 content-type 修复

In lib/router/res.js, instead of always setting 'content-type' to 'application/json', only set it if res.get('content-type') is falsy

对应实现位于 lib/router/res.js:当响应体不是字符串时,Sails 会将其 JSON.stringify(),但只有当前响应头中不存在 content-type 时才强制设为 application/json。这样,调用方显式设置过的 text/plain、application/xml 等类型就不会被覆盖,虚拟请求(virtual request,用于 Socket.io 与 sails.request() 的请求解释器)的行为与真实 HTTP 更一致。

默认 serverError 响应改用 flaverr

Update error mesage in default serverError response to use flaverr

lib/hooks/responses/defaults/serverError.js 使用 flaverr.parseError(data) 来解析并输出错误信息。该默认响应还具备生产环境保护逻辑:NODE_ENV === 'production' 时不会把错误数据随响应体返回(dontRevealErrorInResponse),而是返回空 500。这一行为与 0.12 时代引入的 sails.config.keepResponseErrors 选项一脉相承。

依赖安全升级

1.2.0 集中升级了 flaverr、i18n-2、rc、machinepack-process、machinepack-redis 等依赖,以"address potential vulnerabilities"(解决潜在安全漏洞)为目标。这在 package.json 的 dependencies 中可以印证:i18n-2: 0.7.3、machinepack-process: ^4.0.1、machinepack-redis: ^2.0.2。

1.1.0:模型方法现代化与异步友好化

1.1.0 是 1.x 系列中最具实质功能增量的一版,核心围绕 Waterline ORM 的模型方法、helper/action 的异步签名约定以及 Parley 异步库的性能优化展开。

新模型方法:.updateOne()、.destroyOne()、.archiveOne()

这是 1.1.0 的头号特性。此前开发者只能用 .update()/.destroy() 批量操作,或手动 findOne + 更新。新方法专门服务"单条记录"这一最常用场景:

// 更新单条记录(未命中时给出清晰错误)
await User.updateOne({ id: 37 })
  .set({ emailAddress: 'new@example.com' });

// 删除单条记录
await Product.destroyOne({ id: 9 });

// 归档单条记录(软删除,为记录添加 archived 标记)
await Order.archiveOne({ id: 12 });

CHANGELOG 同时记录了一个细节:archiveOne() 和 destroyOne() 不使用 skipEncryption 选项。此外,Waterline 针对这三个方法改进了"WHERE 条件过于宽泛"时的错误提示,避免开发者误用批量条件导致意外。

可省略的 exits 参数与"智能实现探测"

1.1.0 之前,helper、actions2 定义和 shell 脚本的 fn 函数必须显式声明 exits 参数。1.1.0 起,只要函数签名中没有第二个参数,就无需再编写 exits:

// 之前
fn: async function (inputs, exits) { ... }

// 之后(更简洁)
fn: async function (inputs) { ... }

这一特性依赖"implementation sniffing"(实现探测):Sails 通过检查函数 length(形参个数)和是否为 AsyncFunction 来判断该采用何种调用约定。CHANGELOG 明确记录了 implementationSniffingTactic 可自定义、且对 helpers 与 actions 默认强制采用同一种探测策略(Force homogeneous sniffing tactic),并可设置 implementationType: 'classical' 兼容老式回调风格。

.stream()、.transaction()、.leaseConnection() 支持省略回调

1.1.0 让这些过程式调用更"现代":只要函数签名中省略第二个回调参数,during 回调与迭代函数就无需再手动调用 proceed/回调,直接 return 即可:

await Model.getDatastore().transaction(async (db) => {
  // ... 使用 db 执行事务内查询
  // 无需调用 proceed(),直接 return
});

该行为的边界是:一旦你在函数签名中显式声明了第二个回调参数,就必须遵循旧的回调约定。

bootstrap 与钩子 initialize 同样支持无回调签名

The bootstrap function (config/bootstrap.js) and the initialize function of hooks no longer expect a callback to be invoked, as long as the callback argument is excluded from the function signature.

这与上面的实现探测一脉相承。新版生成器生成的 lib/app/private/bootstrap.js 调用约定已更新,配合 30 秒超时警告,开发者在 bootstrap 中直接 await 初始化逻辑即可。

辅助调用新增链式方法:.timeout() 与 .retry()

helper 调用(基于 Parley)在 1.1.0 中新增了超时与重试能力:

const result = await sails.helpers.sendWelcomeEmail.with({ emailAddress: 'x@y.com' })
  .timeout(5000)        // 5 秒超时
  .retry(3);            // 失败最多重试 3 次

CHANGELOG 详细记录了 Parley 内部为支撑这两个能力所做的性能调优:通过"collapsing IIFE"将吞吐提升到 500K+ ops/sec,随后又通过将 IIFE 移出再提升 1MM ops/sec;.retry() 的元数据在进入时做浅克隆以避免后续调用的边角问题;还实现了 getInvocationInfo() 公开 API 以暴露 _timeout 等内部信息,支持 .interruptions。Machine(actions2/helpers/shell 脚本的运行时)侧实现了"Too many retries"错误与"尊重原始调用超时"(Respect original invocation timeout),并支持 instructionTimeout meta 键。

值得注意的一个细节:CHANGELOG 提到 Parley 曾尝试实现 .retry(),但"Rip out retry from parley (realized it needs to live a level higher up in the stack)"——即重试最终被提升到 Machine 层实现,而非 Parley 底层。这类内部折中记录对理解框架分层很有价值。

生成器与模板的全面翻新

1.1.0 对 sails new/sails generate 产出的样板代码做了大量更新,包括:

  • 默认不再捆绑 async 依赖(新应用默认排除 async,改用 await 与 sails.helpers.flow);
  • 更新的 helper、action、hook 生成器模板;
  • 前端默认采用 Vue.js + VueRouter 的虚拟页面方案;
  • 改进 Windows 兼容性(尤其 sails generate page、sails generate action 在嵌套目录下的路径问题);
  • 模板内置了 Google Fonts/typekit/GTM/GA 接入、Bowser 浏览器检测、<ajax-form> 表单组件(支持 is 规则、required: false、纯数字密码等)等前端基础设施;
  • 邮件模板、bootstrap-overrides 样式、eslintrc 模板(容忍 unused 前缀变量、lint 警告显示为黄色而非红色)等细节优化。

运行时与工具链

  • req.path 在 socket 请求中有了定义且保证为字符串;
  • res.redirect() 等响应的 2-ary 用法被废弃(lib/router/res.js 中的 shim 明确提示改用 res.status(statusCode).send(body));
  • 强制 sails-generate@1.15.19,并带动了水线生态(waterline-utils、anchor、skipper 等)的同步更新;
  • anchor 验证库升级 validator 版本以缓解安全公告(CHANGELOG.md 中的 anchor 条目)。

1.0.0:里程碑重构——Actions 2、Helpers 与大规模清理

1.0.0 是 Sails 历史上最重要的破坏性大版本,CHANGELOG 以 <a href="https://link.gitcode.com/i/6959a1927239d2c52a0b986a94ec9d60" target="_blank">ENHANCEMENT]/[REMOVAL]/[BUGFIX]/[INTERNAL]/[UPGRADE]/[SECURITY] 标签分类记录了全部变更。官方在条目中提示升级者查阅迁移指南(本仓库 [docs/upgrading/To1.0.md 即对应内容)。

Actions 2:以"机器"(Machine)方式声明动作

Introduce Actions 2 -- ability to declare actions as Machines in individual files.

Actions 2 允许把单个 action 写成独立的 Machine 定义文件,自动获得参数校验、类型强制与规范化 exits 处理:

// api/controllers/user/signup.js
module.exports = {
  friendlyName: 'Sign up',
  inputs: {
    emailAddress: { type: 'string', required: true, isEmail: true }
  },
  exits: {
    emailAlreadyInUse: { statusCode: 409 }
  },
  fn: async function (inputs, exits) {
    // ...
  }
};

围绕 Actions 2,1.0.0 新增了四个程序化 API,本仓库均有对应实现:

API 源码 说明
sails.getActions() lib/app/get-actions.js 返回已注册 actions 字典的浅克隆,按唯一标识索引(如 'duck/quack')
sails.registerAction() lib/app/register-action.js 在运行时以编程方式注册 action
sails.registerActionMiddleware() lib/app/register-action-middleware.js 为单个或多个 action 编程注册中间件
sails.reloadActions() lib/app/reload-actions.js 应用运行期间从磁盘/配置重新加载 actions

此外还支持通过 sails.config.controllers.moduleDefinitions 在配置中显式定义 action。lib/app/ 目录下这些文件的存在本身就是 1.0.0 引入能力的源码证据。

Helpers:Services 的继任者

Introduce Helpers -- the successor to services.

Helpers 是 1.0.0 引入、1.1.0 继续强化的可复用逻辑单元,存放于 api/helpers/,由 lib/hooks/helpers/index.js 加载,其加载逻辑(含目录遍历)见 lib/hooks/helpers/private/iterate-helpers.js 与 lib/hooks/helpers/private/load-helpers.js。相比传统 Services,Helper 具备声明式输入校验、标准化错误出口、可链式调用(.with()、.timeout()、.retry())等优势。

移除项清单(升级必读)

1.0.0 移除了一批历史包袱,理解这些移除有助于诊断升级后"找不到功能"的问题:

  • 移除未文档化的 "action/model" 路由语法与 blueprint 路由目标语法;
  • 移除自定义 blueprint(Custom Blueprints),官方建议用普通 actions 替代;
  • 移除 req.validate(),改用 Actions 2 的自动参数校验;
  • 移除 req.params.all()、res.created()、sails.getBaseUrl()、.jsonx()、connect-flash、method-override、ejs-locals(EJS layout 代码直接并入 Sails)、Consolidate 依赖(视图引擎改用 sails.config.views.getRenderFn 配置);
  • 移除 Resourceful PubSub 的大部分方法,仅保留 .subscribe()、.unsubscribe()、.publish();
  • 移除 0.9.x 的 socket 支持与 RPS "firehose";
  • 蓝图 JSONP 支持被移除(官方认为 CORS 已足够普及);
  • 移除 Express 3 的 session adapter 支持。

Express 4 升级与中间件栈重组

  • 升级到 Express 4.14.0(当前仓库 package.json 中为 express: 4.22.2);
  • 404、500 与 startRequestTimer 被自动加入中间件顺序,并从默认的 sails.config.http.middleware.order 中移除;
  • handleBodyParserError 中间件被移除,改用 Skipper 的 onBodyParserError 选项;
  • 静态资源请求默认跳过 session 中间件(性能优化);
  • session 的 routesDisabled 支持完整 Sails 路由地址语法(含正则)。

Security 钩子与安全配置统一

1.0.0 将 CORS 与 CSRF 钩子合并为新的 "Security" 钩子(见 lib/hooks/security/index.js):

  • CSRF 的 /csrfToken 路由被替换为可绑定到任意路由的 action(源码见 lib/hooks/security/csrf/grant-csrf-token.js);
  • 启用 CSRF 时 res.locals._csrf 会提供给所有路由(修复 #3865);
  • 不通过 websocket 提供 CSRF token(安全考虑);
  • CORS 支持大幅改进,且 0.12.7 起在 production 环境 lift 时会警告过宽的 CORS 设置;
  • 策略(Policies)语法更新,被拒绝访问时使用 res.forbidden();
  • 路由自动排序(依赖 sort-route-addresses 模块),避免通配符路由吞掉静态路由。

其他值得注意的 1.0.0 变更

  • 模块加载支持任意文件扩展名(.md 与 .txt 除外),CoffeeScript/TypeScript 需在 app.js 中注册(参见 docs/tutorials/coffeeScript.md 与 docs/tutorials/typeScript.md);
  • 不再基于 Sails 环境擅自设置 NODE_ENV(特殊情况除外);
  • 修复了 Redis session 在服务器意外断开后收到请求导致崩溃的问题,并增加 onDisconnect/onReconnect 回调;
  • 引入基准测试(benchmarks),见 test/benchmarks/ 下的 sails.load.test.js 与 sails.request.generic.test.js;
  • 从 i18n 切换到 i18n-2;
  • 移除了 16 个未使用的依赖。

0.10–0.12:1.0 之前的积淀

CHANGELOG 对旧版本的记录相对简略,但仍有若干影响深远的条目值得提取:

0.12.x:稳定性与现代化

  • 0.12.2:路由展开目标支持 fn;update 蓝图支持非 id 主键的黑名单;res.view()/res.render() 的第三个可选参数强制异步,防止用户代码抛错时回调被二次调用;
  • 0.12.4:sails.config.session.routesDisabled 新增;CSRF 的 routesDisabled 支持 Express 风格路径与正则;修复参数名为 length 时的查询问题;
  • 0.12.5:实验性 sails console --dontLift 选项;include-all 升级到 1.0(sails-build-dictionary 被废弃并合并入 include-all);
  • 0.12.7:production 下对过宽 CORS 配置发出警告;
  • 0.12.8:为 find 和 findOne 蓝图动作增加 criteria 校验;
  • 0.12.10:修复多文件上传时 skipper-disk/skipper-s3 计算文件大小错误的问题;
  • 0.12.11:回迁 Lodash 4 的 _.isFunction() 修复。

0.12.0:功能密集

0.12.0 包含不少如今仍在使用的机制起源:sails.getRouteFor() 与 sails.getUrlFor()(反向路由工具,本仓库 lib/app/get-route-for.js、lib/app/get-url-for.js);sails.config.keepResponseErrors;JSON 排序语法;命名空间钩子与可覆盖默认名称的安装式钩子;sails deploy 命令;虚拟请求解释器的互操作性改进(lib/router/ 下的 mock-req/mock-res 即此机制的载体)。

0.11.x:架构拆分

0.11.0 把 sockets 钩子拆到独立仓库,sails.io.js 也拆为独立生成器;Socket.IO 从 0.9.17 升级到 1.2.1;引入 restPrefix 与 prefix 双配置;蓝图创建返回 201 状态码;0.11.4 因安全漏洞升级了若干依赖。

0.10.x:早期基础

0.10.5 记录了两个至今沿用的小功能:CSRF 的 routesDisabled 选项、从 express3-handlebars 切换到 express-handlebars。更早的变更在 CHANGELOG 末尾以外部链接的形式指引读者查看提交历史(此处不展开外部链接)。

从 CHANGELOG 反推 Sails 的核心架构

CHANGELOG 的价值不仅在于记录版本,更在于它清晰暴露了 Sails 的架构骨架,可与本仓库源码一一对应:

  • 钩子系统(Hooks):几乎所有功能(HTTP、ORM、pubsub、security、views、responses 等)都是钩子,见 lib/hooks/。sails.config.loadHooks 白名单、钩子超时(sails.config.hookTimeout)都是围绕这套体系设计的;
  • 虚拟请求解释器(Virtual Request Interpreter):sails.request() 与 Socket.io 共用同一套请求处理管线(lib/router/req.js、lib/router/res.js、lib/router/mock-req.js),因此 req.path、req.param() 优先级等行为在 HTTP 与 socket 间保持一致;
  • 蓝图(Blueprints):基于模型约定自动生成的 REST 路由,实现集中在 lib/hooks/blueprints/actions/,1.2.0 的 updateOne 切换说明蓝图仍在随 Waterline API 演进;
  • 异步约定统一(Parley/Machine/whelk):helpers、actions2、shell 脚本共享同一套"实现探测 + 链式调用"约定,.timeout()/.retry()/intercept()/tolerate() 全部建立在这一层之上;
  • 生成器生态(sails-generate):sails new/sails generate 的模板由 sails-generate 包驱动(package.json 依赖 sails-generate: ^2.0.11),因此 1.1.0 的大量"Also in new Sails apps"条目实际上是对模板的批量刷新。

如何基于 CHANGELOG 做升级规划

在实际项目中应用这份 CHANGELOG,建议按以下路径操作:

  1. 先确定当前版本与目标版本:查看项目的 node_modules/sails/package.json 或执行 sails version(CLI 文档见 docs/reference/cli/sailsversion.md);
  2. 跨大版本优先读迁移指南:0.x→1.0 必须阅读 docs/upgrading/To1.0.md,其中覆盖了 policies 语法、CSRF 配置迁移(cors.js → security.js)、视图引擎配置、globals 行为等关键变化;更早的迁移指南见 docs/upgrading/To0.12.md 等;
  3. 逐条核对 REMOVAL 清单:1.0.0 的移除项是最常见的升级报错来源(如 res.created、req.validate、JSONP 蓝图);
  4. 关注安全条目:0.11.4、1.2.0 等版本均因安全公告升级依赖,升级时应一并更新到包含安全修复的版本;
  5. 用小项目做冒烟验证:仓库自带的集成测试(test/integration/)与单元测试(test/unit/)是很好的行为参考,例如 hook.blueprints.action.routes.test.js、middleware.404.test.js、app.registerAction.test.js 分别验证了蓝图路由、404 中间件与 action 注册的行为。

结语

从 0.10 到 1.2,Sails 的 CHANGELOG 完整记录了一个实时 MVC 框架的现代化历程:Actions 2 与 Helpers 取代了旧的控制器/服务模式,Express 4 与虚拟请求解释器统一了 HTTP 与 socket 的请求模型,Parley/Machine 层的"实现探测"让异步代码彻底拥抱 async/await,而 Waterline 的 updateOne/destroyOne/archiveOne 则让模型操作更精确、更安全。对于正在使用或计划升级 Sails 的开发者而言,这份 CHANGELOG 配合仓库源码,就是最可靠的行为规范与升级手册。

登录后查看全文
sails