Sails 框架 CHANGELOG 全解读:从 0.10 到 1.2 的关键演进、破坏性变更与源码级验证
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 migratefor quickly running auto-migrations by hand
该命令的实现位于 bin/sails-migrate.js,并在 bin/sails.js 中注册。其工作流程为:
- 加载(但不 lift)当前工作目录下的 Sails 应用;
- 跳过 Grunt 钩子(
grunt: false),因为自动迁移不需要前端构建; - 运行应用的 bootstrap 函数后直接退出;
- 优先使用应用本地安装的 Sails(
node_modules/sails),否则回退到全局安装版本。
源码中的注释给出了两种典型用法:
# 运行 "alter" 自动迁移,尝试调整所有数据(但可能删除数据)
sails migrate
# 运行 "drop" 自动迁移,清空所有数据
sails migrate --drop
需要特别注意的是,sails migrate 在源码中明确标注为 @stability EXPERIMENTAL(实验性),因此生产环境中使用前应先评估其风险。
钩子加载的显式白名单语义
When loading user hooks, if
sails.config.loadHooksis 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.jsfrom 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
updateOnein the "update" blueprint Blueprint queries no longer includefetch: trueby default, to avoid warnings fromupdateOne
在 lib/hooks/blueprints/actions/update.js 中可以看到,update 蓝图动作现在调用 Model.updateOne(criteria).set(queryOptions.valuesToSet).meta(queryOptions.meta)。该动作的完整流程是:
- 先用
Model.findOne()找到原始记录(为前端提供更好的集成体验,并可广播previous值); - 用
updateOne()精确更新单条记录; - 若存在 pubsub 钩子,向订阅者广播更新事件;
- 最后再查询一次以返回填充(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 ifres.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
serverErrorresponse 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 theinitializefunction 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,建议按以下路径操作:
- 先确定当前版本与目标版本:查看项目的
node_modules/sails/package.json或执行sails version(CLI 文档见 docs/reference/cli/sailsversion.md); - 跨大版本优先读迁移指南:0.x→1.0 必须阅读 docs/upgrading/To1.0.md,其中覆盖了 policies 语法、CSRF 配置迁移(cors.js → security.js)、视图引擎配置、globals 行为等关键变化;更早的迁移指南见 docs/upgrading/To0.12.md 等;
- 逐条核对 REMOVAL 清单:1.0.0 的移除项是最常见的升级报错来源(如
res.created、req.validate、JSONP 蓝图); - 关注安全条目:0.11.4、1.2.0 等版本均因安全公告升级依赖,升级时应一并更新到包含安全修复的版本;
- 用小项目做冒烟验证:仓库自带的集成测试(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 配合仓库源码,就是最可靠的行为规范与升级手册。