编辑页面

升级到 Sails v1.0

Sails v1.0 来了！请继续阅读以获取此版本中更改的高级概述，并了解您可能希望在应用中利用的一些新功能。

关于重大更改的说明

在开发此版本的 Sails 期间，我们做出的许多决策都优先考虑了更好的开发者体验而非向后兼容性。因此，升级到 Sails 1.0 将涉及处理比以前版本更多的重大更改。但是，完成后，您在 Sails 中使用的功能更有可能得到其作者和维护人员的充分理解并几乎每天都在使用。

有关 1.0 中许多重大更改背后的理念的更多信息，您可以阅读 Mike McNeil 的深入解释 此处。

使用自动化工具升级现有应用

准备好将您现有的 v0.12.x Sails 应用升级到 1.0 版了吗？首先，我们建议您使用 Sails 1.0 升级工具，该工具将帮助完成一些最常见的迁移任务。要使用该工具，请首先使用 npm install -g sails@^1.0.0 在全局安装 Sails 1.0，然后运行 sails upgrade。工具运行后，它将为您创建一个报告，其中列出了需要手动升级的剩余项目。

手动升级现有应用

以下清单涵盖了最可能影响大多数应用的更改。

如果您的应用在遵循此清单后启动时仍然存在错误或警告，或者如果您看到意外情况，请返回此文档并查看页面下方。（可能适用涵盖各种应用组件的指南之一。）

我们做了很多工作来使升级过程尽可能无缝，尤其是在您在控制台上看到的错误和警告方面。但是，如果您遇到问题或对以下任何更改有任何疑问，请随时 访问 Sails 社区 Gitter 频道。（如果您的公司使用 Sails Flagship，您也可以 此处 直接与 Sails 核心团队聊天。）

tl;dr 清单：升级到 1.0 版时您必须执行的操作

升级工具尽其所能帮助解决其中一些项目，但它不会为您更改特定于应用的代码！

• 步骤 0：检查您的 Node 版本
• 步骤 1：安装钩子和更新依赖项
• 步骤 2：更新配置
• 步骤 3：修改客户端代码以适应新的蓝图 API
• 步骤 4：采用 Waterline ORM 的新版本

步骤 0：检查您的 Node 版本！

如果您的应用需要支持低于 v4 的 Node 版本，则您将无法升级到 Sails 1.0，因为 Sails 1.0 不再支持 Node v0.x。Sails 1.0 支持的 Node 最早版本是 Node 4.x。

步骤 1：安装钩子和更新依赖项

Sails v1 引入了 自定义构建。这意味着某些核心钩子现在作为应用的直接依赖项安装，使您可以更好地控制依赖项并使 npm install sails 运行速度大大加快。因此，您需要做的第一件事是安装您正在使用的核心钩子。（并且在您这样做的时候，请务必更新下面列表中提到的其他依赖项。）

• 将 sails-hook-orm 包安装到您的应用中，使用 npm install --save sails-hook-orm，除非您的应用禁用了 ORM 钩子。
• 将 sails-hook-sockets 包安装到您的应用中，使用 npm install --save sails-hook-sockets，除非您的应用禁用了套接字钩子。
• 将 sails-hook-grunt 包安装到您的应用中，使用 npm install --save sails-hook-grunt，除非您的应用禁用了 Grunt 钩子。
• 安装数据库适配器的最新版本。例如，如果您使用的是 sails-mysql，请执行 npm install --save sails-mysql@latest。
• 使用 sails generate sails.io.js 升级您的 sails.io.js websocket 客户端。有关更多详细信息，请参阅 "下面的 Websockets 部分"。

步骤 2：更新配置

Sails v1 在应用配置方面提供了一些改进。例如，现在可以将 lodash 和 async 的自动安装自定义到任何版本，并且视图引擎配置语法现在与 Express v4+ 的语法一致。但是，配置方面最重大的变化与 Sails v1 中最令人兴奋的新功能之一相关：数据存储。为了确保您正确升级数据库和其他设置的配置，请务必仔细阅读以下步骤并应用必要的更改。

• 更新您的 config/globals.js 文件（除非您的应用将 sails.config.globals 设置为 false）
  • 将 models 和 sails 设置为具有布尔值（true 或 false）。
  • 将 async 和 lodash 设置为分别具有 require('async') 和 require('lodash')，或者 false。您可能还需要 npm install --save lodash 和 npm install --save async。
• 注释掉您未在 config/connections.js 中使用的任何数据库配置。与以前的版本不同，Sails 1.0 将加载配置文件中引用的所有数据库适配器，无论模型是否实际使用它们。有关更多信息，请参阅 数据库配置的迁移指南部分。
• /csrfToken 路由在使用 CSRF 时不再默认提供给所有应用。如果您在应用中使用了此路由，则需要将其手动添加到 config/routes.js 中，例如 'GET /csrfToken': { action: 'security/grant-csrf-token' }。
• 如果您的应用依赖于 操作阴影路由（其中每个自定义控制器操作都自动映射到一个路由），则需要更新您的 config/blueprints.js 文件并将 actions 设置为 true。此设置现在默认为 false。
• 如果您的应用使用 CoffeeScript 或 TypeScript，请参阅 CoffeeScript 和 TypeScript 教程以获取更新信息。
• 如果您的应用使用除 EJS 之外的视图引擎，则需要在 config/views.js 文件中自行配置它，并且您可能需要为您的项目运行 npm install --save consolidate。有关更多详细信息，请参阅下面的“视图”部分。
• 如果您的 api 或 config 文件夹和子文件夹包含任何非源文件，则需要将它们移动。例外情况是 Markdown (.md) 和文本 (.txt) 文件，它们将继续被忽略。Sails 将尝试将这些文件夹中的所有其他文件读取为代码，从而允许更灵活地选择 Javascript 方言（请参阅上面关于 CoffeeScript 和 TypeScript 的说明）。

步骤 3：修改客户端代码以适应新的蓝图 API

除了扩展到包含一个新的端点之外，蓝图 API 还有一些细微但破坏性的更改，您可能需要对客户端代码进行更改。

• 如果您的应用使用蓝图路由，请注意一些隐式“阴影”路由的 HTTP 方法（也称为动词）已更改
  • 添加 的 RESTful 蓝图路由地址已从 POST 更改为 PUT。
  • 更新 的 RESTful 蓝图路由地址已从 PUT 更改为 PATCH。
• 如果您的应用依赖于蓝图操作的默认套接字通知，请注意，进行了一些与性能相关的升级，这些升级在某种程度上更改了这些消息的结构
  • Sails 不再发布单独的 addedTo 通知，每个集合的新成员一个。这些单独的通知现在已汇总到一个通知中，新消息包含一个 id 数组（addedIds）而不是只有一个。
  • Sails 不再发布单独的 removedFrom 通知，每个集合的前成员一个。Sails 现在将它们汇总到一个通知中，新消息现在包含一个 id 数组（removedIds）而不是只有一个。

步骤 4：采用 Waterline ORM 的新版本

Waterline ORM (v0.13) 的新版本引入了对 SQL 事务的完全支持、能够在结果集中包含或省略属性（也称为“投影”）、动态数据库连接以及对查询行为的更广泛的粒度控制。它还包括一个主要的稳定性和性能改进，这带来了一些使用方面的重大更改。以下要点涵盖了您在 Waterline 升级过程中可能遇到的最常见问题。

• 如果您的应用依赖于从 .create()、.createEach()、.update() 或 .destroy() 调用中获取记录，则需要更新模型设置以指示您希望这些方法获取记录（或将 .fetch() 链到单个调用）。有关更多信息，请参阅 create()、.createEach()、.update() 和 .destroy() 结果的迁移指南部分。
• 如果您的应用依赖于使用 .add()、.remove() 和 .save() 方法修改集合，则需要将它们更新为使用新的 .addToCollection、.removeFromCollection 和 .replaceCollection 模型方法。
• Waterline 查询现在将依赖于数据库的大小写敏感性。这意味着在大多数适配器中，您的查询现在将区分大小写，而以前则不区分。如果您习惯于使用不区分大小写的查询，这可能会产生意想不到的后果。有关如何在 MySQL 等数据库中管理此问题的更多信息，请参阅 大小写敏感性文档。
• Waterline不再支持嵌套创建或更新操作，此更改也扩展到相关的蓝图。如果您的应用依赖于这些功能，请参阅迁移指南中关于嵌套创建和更新的部分以获取更多信息。
• 如果您的应用使用.create()、.findOrCreate()或.update()将模型属性设置为null，则需要将该属性的类型更改为json，或者使用现有属性类型的基础值，而不是null（例如，数字使用0）。请参阅验证文档以获取更多信息。
• create蓝图响应现在已完全填充，就像来自find、findOne、update和destroy的响应一样。要抑制记录的填充，请在蓝图配置或特定路由中添加parseBlueprintOptions。请参阅蓝图配置参考以获取更多信息。
• 如果您使用createEach将大量行插入数据库，请记住，大多数适配器的Sails 1.0兼容版本现在优化了createEach方法以使用单个查询，而不是每个行使用一个查询。根据您的数据库，可能存在每个请求的数据大小限制。请参阅.createEach()参考页面底部的说明以获取更多信息。
• 属性的size属性不再受支持。您可以使用columnType属性来指示列大小。
• 属性的defaultsTo属性不再可以定义为函数。您需要硬编码默认值，或者完全删除defaultsTo并在创建新记录之前更新代码以确定属性的适当值。（这可以在操作中调用.create()/.createEach()之前处理，或者在模型的beforeCreate中处理）。

其他重大更改

以上升级指南提供了Sails贡献者在将不同应用从版本0.12升级到版本1.0时遇到的最常见的升级问题。但是，每个应用都不同，因此我们建议您也通读以下要点。并非所有讨论的更改都一定会应用于您的应用，但某些更改可能会应用。

• req上的几个属性和方法现在的工作方式略有不同
  • req.accepted已被req.accepts()取代。
  • req.acceptedLanguages和req.acceptsLanguage()已被req.acceptsLanguages()取代。
  • req.acceptedCharsets和req.acceptsCharset()已被req.acceptsCharsets()取代。
• 与蓝图相关的几个req.options属性不再受支持。现在可以使用新的parseBlueprintOptions方法来完全控制蓝图的行为。请参阅蓝图配置参考以获取更多信息。
• defaultLimit和populate蓝图配置选项不再受支持。现在可以使用新的parseBlueprintOptions方法来完全控制蓝图的行为。请参阅蓝图配置参考以获取更多信息。
• .findOne()查询方法不再支持sort和limit修饰符，如果给定的条件匹配多个记录，则会抛出错误。如果您想使用除unique属性（如主键）以外的任何内容作为条件来查找单个记录，请改用.find(<criteria>).limit(1)（请记住，这将返回一个包含一个项目的数组）。
• autoPk、autoCreatedAt和autoUpdatedAt不再作为顶级模型属性受支持。请参阅迁移指南中关于模型配置更改的部分以获取更多信息。
• 动态查找器（例如User.findById()）不再自动添加到您的模型中。您可以将其作为自定义模型方法自行实现。
• 模型实例方法不再受支持。这允许从查找查询返回的记录成为纯JavaScript对象，而不是模型记录实例。
• 自定义.toJSON()实例方法不再受支持。请改在模型类中添加customToJSON方法（在attributes字典之外）。请参阅模型设置文档以获取更多信息。
• .toObject()实例方法不再添加到每个记录中。在为模型实现customToJSON时，请确保使用_.omit()、_.pick()或_.clone()克隆记录。
• autoUpdatedAt时间戳现在可以在.update()调用中手动更新（以前，传入的属性值将被忽略）。之前的行为促进了.save()的使用，而.save()现在不再受支持。现在，您可以根据需要更新updatedAt（但通常您应该让Sails为您执行此操作！）
• beforeValidate和afterValidate生命周期回调不再存在。使用其他众多生命周期回调之一来访问查询。
• afterDestroy生命周期回调现在接收单个记录。它已标准化为与afterUpdate回调相同的方式工作，并为每个已销毁的记录调用该函数一次，而不是一次调用所有已销毁的记录。
• 许多资源丰富的PubSub方法已更改（有关完整列表，请参阅下面的PubSub部分）。如果您的应用仅使用蓝图提供的自动RPS功能（并且不直接调用RPS方法），则无需更新。
• .find()模型方法不再自动强制转换未识别属性提供的约束。例如，如果您执行Purchase.find({ amount: '12' })，例如通过蓝图(https://127.0.0.1:1337/purchase?amount=12)，并且没有这样的“amount”属性，那么即使数据库包含具有数字等效值（12）的记录，它也不会被匹配。（这仅在使用MongoDB和sails-disk时才相关）。如果您因为此问题遇到问题，请将属性定义为数字，或者（如果您使用蓝图）改用显式where子句（例如https://127.0.0.1.com:1337/purchase?where={"amount":12}）。
• 自定义蓝图和相关的蓝图路由语法已被移除。此功能可以使用自定义操作、助手和路由来复制。请参阅下面的“替换自定义蓝图”部分以获取更多信息。
• 蓝图操作影子路由不再包含/:id?结尾 - 也就是说，如果您有一个带有tickle操作的UserController.js，您将不再获得/user/tickle/:id?路由（而是，它将只是/user/tickle）。依赖于这些路由的应用应该将其手动添加到其config/routes.js文件中。
• sails.getBaseUrl在v0.12.x中已弃用，现已移除。请参阅v0.12中关于getBaseUrl的文档以获取有关其移除原因以及如何替换它的更多信息。
• req.params.all()在v0.12.x中已弃用，现已移除。请改用req.allParams()。
• sails.config.dontFlattenConfig在v0.12.x中已弃用，现已移除。请参阅关于dontFlattenConfig的原始说明以获取详细信息。
• req.param()和req.allParams()的优先级顺序已更改。现在始终是路径 > 主体 > 查询（即，URL路径参数覆盖请求主体参数，后者覆盖查询字符串参数）。
• req.validate()已被移除。请改用actions2。
• 默认的res.created()响应已被移除。如果您在应用中直接调用res.created()，并且没有api/responses/created.js文件，则需要创建一个。
  • 相关的是，蓝图创建操作现在将在成功时返回200状态代码，而不是201。
• 默认的notFound和serverError响应不再接受pathToView参数。它们只会尝试提供404或500视图。如果您需要能够使用不同视图调用这些响应，可以通过将api/responses/notFound.js或api/responses/serverError.js文件添加到您的应用中来自定义响应。
• 默认的badRequest或forbidden响应不再显示视图。如果您还没有api/responses/badRequest.js和api/responses/forbidden.js文件，则需要自己添加它们并在需要它们显示视图文件时编写自定义代码。
• connect-flash中间件已被移除（因此req.flash()默认情况下将不再可用）。如果您希望继续使用req.flash()，请在您的应用文件夹中运行npm install --save connect-flash并手动添加中间件。
• POST /:model/:id蓝图RESTful路由已被移除。如果您的应用依赖于此路由，则需要将其手动添加到config/routes.js并将其绑定到自定义操作。
• handleBodyParserError中间件已被移除；取而代之的是，Skipper主体解析器现在拥有自己的onBodyParserError方法。
  • 如果您自定义了中间件顺序，则需要从数组中删除handleBodyParserError。
  • 如果您已覆盖handleBodyParserError，则需要改用您自己的自定义版本的Skipper覆盖bodyParser，并在onBodyParserError选项中包含您的错误处理逻辑。
• methodOverride中间件已被移除。如果您的应用使用了此中间件
  • npm install --save method-override
  • 确保您的sails.config.http.middleware.order数组（在config/http.js中）在router之前包含methodOverride。
  • 将methodOverride: require('method-override')()添加到sails.config.http.middleware中。
• router中间件不再可覆盖。而是，Express 4路由器用于路由外部和内部（也称为“虚拟”）请求。在sails.config.http.middleware.order中仍然需要一个router条目来界定应在路由器之前和之后添加哪些中间件。

• 已移除查询修饰符lessThan、lessThanOrEqual、greaterThan和greaterThanOrEqual。请改用简写版本（<、<=、>、>=）。
• find one和find蓝图操作现在接受populate=false而不是populate=来指定不填充任何属性。
• add和remove蓝图操作现在要求要添加或移除的子记录的主键作为URL的一部分提供，而不是允许它通过查询字符串或主体传递。
• destroy蓝图操作现在要求要销毁的记录的主键作为URL的一部分提供，而不是允许它通过查询字符串或主体传递。
• sails.config.session.routesDisabled设置已更改为sails.config.session.isSessionDisabled()，一个函数。有关配置isSessionDisabled()的更多信息，请参阅config/session.js文档。
• 不再支持Waterline方法的实验性“回退式”用法。Waterline模型方法只能使用函数回调。
• 不再支持实验性的create自动迁移方案。强烈建议您使用迁移工具（例如Knex）来处理生产数据库的迁移。
• 不再支持实验性的forceLoadAdapter数据存储设置。相反，在config/datastores.js（以前为config/connections.js）中引用的所有适配器都会在Sails启动时自动加载。
• 已移除实验性的usage路由选项。建议您在控制器代码中执行任何路由参数验证。
• 已移除实验性的“关联项目”蓝图影子路由。这些是类似GET /user/1/pets/2的路由，其功能可以通过使用更清晰的路由GET /pets/2来复制。
• 模型类中的实验性.validate()方法（例如User.validate()）现在已完全支持，但其用法已更改。有关更多信息，请参阅.validate()文档。
• 模型类内部表示中的属性顺序已更改（关联属性现在排序在底部）。这会导致使用migrate: 'alter'创建的表具有与以前版本的Waterline中不同的列顺序，因此如果列顺序在您的应用程序中很重要，请注意这一点。提醒一下，自动迁移旨在帮助您在构建应用程序时设计架构。除了设置列名、类型（包括指定的字符集/编码）和唯一性之外，它们不能保证数据库物理列的任何细节的一致性。
• 使用_config将控制器链接到模型将不再有效。这从未被支持过，但它被一些项目用来更改映射到模型蓝图操作的URL。请改用restPrefix。
• find()、destroy()和update()方法会忽略undefined属性。这些方法会从其搜索条件中删除未定义的属性，例如User.update({id: undefined}).with({ firstName: 'Finn'})将更新**所有**用户记录。在此Github问题中了解更多信息。

数据库配置更改

• sails.config.connections设置已被弃用，取而代之的是sails.config.datastores。如果您启动一个仍然配置了sails.config.connections的应用程序，您将收到一个警告，您可以通过简单地将config/connections.js中的module.exports.connections更改为module.exports.datastores来避免此警告。为了方便起见，建议您也将其文件名更改为config/datastores.js。
• sails.config.models.connection设置已被弃用，取而代之的是sails.config.models.datastore。与上面一样，更改config/models.js中属性的名称就足以关闭任何警告。
• 每个应用程序现在都有一个默认的数据存储（恰当地命名为default），该数据存储配置为使用sails-disk适配器的内置版本。在Sails 1.0中，sails.config.models.datastore的默认值为default（而不是localDiskDb）。设置模型默认数据存储的推荐方法是简单地在config/datastores.js中的default键下添加所需的配置，并将config/models.js中的datastore键保留为未定义，而不是以前的方法，即设置datastore为（例如）myPostgresqlDb，然后在config/datastores.js中添加一个myPostgresqlDb键。这使得更改不同环境使用的数据库变得更容易（例如，通过更改config/env/production.js中default数据存储的配置）。
• 应用程序中配置的所有数据存储都将在运行时加载（而不是仅加载至少一个模型正在使用的数据库）。这有利于允许在单个模型的上下文之外使用数据库，但这也意味着如果您不想在Sails启动时连接到某个数据库，则应注释掉该数据库连接配置！

嵌套创建和更新

• .create()、.update()和.add()模型方法不再支持创建新的“子”记录以立即链接到新的或现有的父级。例如，给定一个User模型，它通过名为pet的属性与Animal模型具有单数关联，则无法将pet设置为表示全新Animal值的字典（也称为“嵌套创建”）。相反，首先创建新的Animal，然后在创建新User时使用其主键设置pet。
• 类似地，create、update和add蓝图操作不再支持嵌套创建。
• .update()模型方法及其关联的蓝图操作不再支持替换整个复数关联。如果记录通过“一对多”或“多对多”关联链接到一个或多个其他记录，并且您希望将其链接到完全不同的记录集，请使用.replaceCollection()模型方法或替换蓝图操作。

模型配置更改

tl;dr

从您的模型中删除任何autoPK、autoCreatedAt和autoUpdatedAt属性，并将以下内容添加到您的config/models.js文件中

attributes: {
    createdAt: { type: 'number', autoCreatedAt: true, },
    updatedAt: { type: 'number', autoUpdatedAt: true, },
    id: { type: 'number', autoIncrement: true}, // <-- for SQL databases
    id: { type: 'string', columnName: '_id'}, // <-- for MongoDB
  }

不再支持autoPK顶级属性

此属性以前用于指示Waterline是否应创建id属性作为模型的主键。从Sails v1.0 / Waterline 0.13开始，Waterline将不再在后台创建任何属性。相反，必须显式定义id属性。还有一个新的顶级模型属性称为primaryKey，可以将其设置为应用作模型主键的属性的名称。此值默认为每个模型的id，因此通常您不必自己设置它。

autoUpdatedAt和autoCreatedAt模型设置现在是属性级属性

这些属性以前用于指示Waterline是否应为模型创建createdAt和updatedAt时间戳。从Sails v1.0 / Waterline 0.13开始，Waterline将不再在后台创建这些属性。相反，如果要使用它们，则必须显式定义createdAt和updatedAt属性。通过将autoCreatedAt: true或autoUpdatedAt: true添加到属性定义中，您可以指示Waterline在创建或更新记录时将该属性设置为当前时间戳。根据这些属性的类型，时间戳将采用以下两种格式之一生成

• 对于type: 'string'，这些时间戳以与Sails 0.12中相同的方式存储：作为不含时区的ISO 8601 JSON时间戳字符串（例如'2017-12-30T12:51:10Z'）。因此，如果您的任何前端代码依赖于字符串形式的时间戳，则务必将其设置为string。
• 对于type: 'number'，这些时间戳存储为JS时间戳（自1970年1月1日午夜UTC以来的毫秒数）。

此外，对于任何属性，如果在Waterline条件的where子句中、作为新记录或在.update()查询中要设置的值中传递new Date()，则会根据属性的类型应用相同的规则。如果属性为type: 'json'，则使用后一种方法。

.create()、.createEach()、.update()和.destroy()结果的更改

从Sails v1.0 / Waterline 0.13开始，.create()、.createEach()、.update()和.destroy()的默认结果已更改。

为了鼓励更好的性能和更轻松的可扩展性，.create()不再发送回已创建的记录。类似地，.createEach()不再发送回已创建记录的数组，.update()不再发送回已更新记录的数组，.destroy()不再发送回已销毁记录。相反，.exec()回调的第二个参数现在为undefined（或者如果您使用的是Promise，则为.then()的第一个参数）。

这通过删除不必要的find查询使您的应用程序更高效，并且可以利用.update()和.destroy()修改大型数据集中的许多不同记录，而不是回退到更低级的原生查询。

您仍然可以通过使用fetch方法指示适配器发送回单个查询的已创建或修改的记录。例如

Article.update({
  category: 'health-and-wellness',
  status: 'draft'
})
.set({
  status: 'live'
})
.fetch()
.exec(function(err, updatedRecords){
  //...
});

如果更改所有应用程序查询的前景看起来令人生畏，则您可以利用一个临时的便利功能。为了简化升级现有应用程序的过程，您可以告诉Sails/Waterline为应用程序的所有.create()/.createEach()/.update()/.destroy()查询获取已创建/更新/销毁的记录。只需编辑config/models.js中的应用程序范围模型设置

fetchRecordsOnUpdate: true,
fetchRecordsOnDestroy: true,
fetchRecordsOnCreate: true,
fetchRecordsOnCreateEach: true,

就是这样！但是，为了提高性能并使您的应用程序面向未来，您应该检查所有.create()、.createEach()、.update()和.destroy()调用，并在可能的情况下添加.fetch()。对这些模型设置的支持最终将在Sails v2中删除。

Waterline条件用法的更改

• 出于性能原因，从Sails v1.0 / Waterline 0.13开始，传递给Waterline模型方法的条件现在将在大多数情况下就地更改（而在Sails/Waterline v0.12中，情况并非总是如此）。

• 查询条件中不再支持聚合子句（sum、average、min、max 和 groupBy）。请改用新的模型方法 .sum() 和 .avg()。
• limit 和 skip 的更改
  • limit: 0 **不再与 limit: undefined 等效**。它不再匹配无限个结果，而是匹配 0 个结果。
  • 避免指定小于 0 的 limit 值。它仍然会被忽略，并像 limit: undefined 一样工作，但现在会向控制台输出弃用警告。
  • skip: -20 **不再与 skip: undefined 等效**。它不再跳过 0 个结果，而是会报错并拒绝执行。
  • limit 必须小于 Number.MAX_SAFE_INTEGER（…有一个例外：为了兼容性/方便起见，Infinity 会被自动容忍并规范化为 Number.MAX_SAFE_INTEGER）。
  • skip 必须小于 Number.MAX_SAFE_INTEGER

混合 where 子句的支持更改

不再支持包含混合 where 子句的查询条件字典。例如，不要使用

{
  username: 'santaclaus',
  limit: 4,
  select: ['beardLength', 'lat', 'long']
}

而应该使用

{
  where: { username: 'santaclaus' },
  limit: 4,
  select: ['beardLength', 'lat', 'long']
}

请注意，您仍然可以使用 { username: 'santaclaus' } 作为 { where: { username: 'santaclaus' } } 的简写，只是不能将其他顶级查询条件子句（如 limit）与约束条件（例如 username）混合使用。

对于使用 Waterline 的可链式延迟对象构建查询条件的地方，不用担心这个问题——它已经为您处理好了。

安全

使用 Sails 1.0 创建的新应用将包含一个 config/security.js 文件，而不是单独的 config/cors.js 和 config/csrf.js 文件。从早期版本迁移的应用可以保留其现有文件，只要它们执行以下升级

• 将 config/cors.js 中的 module.exports.cors 更改为 module.exports.security.cors
• 将 CORS 配置设置名称更改为与 参考 > 配置 > sails.config.security 中新文档中记录的名称匹配
• 将 config/csrf.js 中的 module.exports.csrf 更改为 module.exports.security.csrf。此值现在仅为 true 或 false；不支持其他 CSRF 选项（见下文）。
• 不再支持 sails.config.csrf.routesDisabled。相反，在您希望 config/routes.js 中的任何路由不受 CSRF 保护的情况下，向该路由添加 csrf: false，例如

'POST /some-thing': { action: 'do-a-thing', csrf: false },

• 不再支持 sails.config.csrf.origin。相反，您可以将任何自定义 CORS 设置直接添加到您的 CSRF 令牌路由配置中，例如

'GET /csrfToken': {
  action: 'security/grant-csrf-token',
  cors: {
    allowOrigins: ['http://foobar.com', 'https://owlhoot.com']
  }
}

• 不再支持 sails.config.csrf.grantTokenViaAjax。此设置用于启用或禁用 CSRF 令牌授予路由。在 Sails 1.0 中，您需要在 config/routes.js 文件中手动添加该路由（见上文）。如果您不想通过 AJAX 授予 CSRF 令牌，只需将该路由从 config/routes.js 中移除即可。

视图

为了获得最大的灵活性，Consolidate 不再与 Sails 捆绑在一起。如果您使用除 EJS 之外的视图引擎，您可能需要将 Consolidate 作为应用的直接依赖项进行安装。然后，您可以像这样在 config/views.js 中配置视图引擎

extension: 'swig',
getRenderFn: function() {
  // Import `consolidate`.
  var cons = require('consolidate');
  // Return the rendering function for Swig.
  return cons.swig;
}

在 Sails 1.0 中，向视图引擎添加自定义配置变得更加容易

extension: 'swig',
getRenderFn: function() {
  // Import `consolidate`.
  var cons = require('consolidate');
  // Import `swig`.
  var swig = require('swig');
  // Configure `swig`.
  swig.setDefaults({tagControls: ['{?', '?}']});
  // Set the module that Consolidate uses for Swig.
  cons.requires.swig = swig;
  // Return the rendering function for Swig.
  return cons.swig;
}

请注意，对布局的内置支持 仍然适用于默认的 EJS 视图，但 Sails 1.0 不包含对其他视图引擎（例如 Handlebars 或 Ractive）的布局支持。

资源型发布/订阅

• 已移除弃用的 backwardsCompatibilityFor0.9SocketClients 设置。
• 已移除弃用的 .subscribers() 方法。
• 已移除弃用的“firehose”功能。
• 已移除对 0.9.x socket 客户端 API 的支持。
• 以下资源型发布/订阅方法也已被移除
  • .publishAdd()
  • .publishCreate()
  • .publishDestroy()
  • .publishRemove()
  • .publishUpdate()
  • .watch()
  • .unwatch()
  • .message()

代替已移除的方法，您应该使用新的 .publish() 方法，或低级别的 sails.sockets 方法。请记住，与 .message() 不同，.publish() 不会将您的数据包装在一个包含记录 ID 的信封中，因此——如果很重要——您需要自己将 ID 作为数据的一部分包含在内。例如，在 Sails v0.12.x 中，User.message(123, {owl: 'hoot'}) 将导致以下通知广播给客户端

{
  verb: 'messaged',
  id: 123,
  data: {
    owl: 'hoot'
  }
}

相反，在 Sails v1.0 中，User.publish(123, {owl: 'hoot'}) 将简单地广播

{
  owl: 'hoot'
}

替换自定义蓝图

默认情况下，不再可以将文件添加到 api/blueprints/ 中，并将其自动用作所有模型的蓝图操作。但是，可以通过安装 sails-hook-custom-blueprints 轻松复制此行为。

Express 4

Sails 1.0 将内部 Express 服务器从版本 3 更新到版本 4（感谢 @josebaseba 的出色工作）。此更改主要与 Sails 框架的可维护性有关，并且应该对您的应用透明。但是，有一些差异值得注意

• 404、500 和 startRequestTimer 中间件现在已内置到每个 Sails 应用中，并已从 sails.config.http.middleware.order 数组中移除。如果您的应用具有覆盖的 404 或 500 处理程序，则应分别覆盖 api/responses/notFound.js 和 api/responses/serverError.js。
• 专为 Express 3 设计的会话中间件（例如，非常旧版本的 connect-redis 或 connect-mongo）将不再工作，因此您需要升级到更新的版本。
• sails.config.http.customMiddleware 功能在 Sails 1.0 中已弃用。它现在仍然可以工作，但可能会在以后的版本中移除。不要使用 customMiddleware 直接修改 Express 应用，而是使用常规的（req、res、next）中间件。例如，您可以替换以下内容

customMiddleware: function(app) {
  var passport = require('passport');
  app.use(passport.initialize());
  app.use(passport.session());
}

为以下内容

var passport = require('passport');
middleware: {
  passportInit: passport.initialize(),
  passportSession: passport.session()
},

确保将 passportInit 和 passportSession 插入到 config/http.js 中的 middleware.order 数组中。

响应方法

• .jsonx() 已弃用。如果您在 api/responses 中有尚未自定义的文件，您可以直接删除它们并让 Sails 默认响应发挥作用。如果您在 api/responses 中有想要保留的文件，请将这些文件中所有出现的 res.jsonx() 替换为 res.json()。
• res.negotiate() 已弃用。请改用 res.serverError()、res.badRequest() 或 自定义响应。

i18n

Sails 1.0 从使用 i18n 切换到更轻量级的 i18n-2 模块。绝大多数用户应该不会在他们的应用中看到任何区别。但是，如果您正在使用 sails.config.i18n.updateFiles 选项，请注意此选项不再受支持；相反，区域设置文件将在开发模式下始终更新，在生产模式下永远不会更新。如果这是一个问题，或者您错过了 i18n 模块中的某些其他功能，您可以安装 sails-hook-i18n 以恢复到 Sails 1.0 之前的功能。

如果您的 0.12 应用由于使用了 i18n 功能而在升级期间遇到问题，请参阅 #4343 获取更多故障排除技巧。

WebSockets

所有使用 websockets 的 Sails 1.0 项目都必须安装最新的 sails-hook-sockets 依赖项（npm install --save sails-hook-sockets）。此版本的 sails-hook-sockets 在几个方面与以前的版本不同

• 默认的 transports 设置仅为 ['websocket']。在大多数生产部署中，将您的应用限制为 websocket 传输（而不是使用 ['polling', 'websocket']）可以避免会话问题（有关详细信息，请参阅 1.0 之前的 扩展指南说明）。如果您正在使用 sails.io.js websocket 客户端，使您的应用与新的 websocket 设置兼容的最简单方法是使用 sails generate sails.io.js 安装新的 sails.io.js 版本。该软件包的最新版本也默认使用“仅 websocket”传输策略。如果您在前端代码和 config/sockets.js 文件中自定义了 transports 设置，那么您只需要继续确保这两个位置的值匹配即可。
• 最新的 sails-hook-sockets hook 使用了更新版本的 Socket.io。请参阅 Socket.io 变更日志 以获取完整更新，但请记住，socket ID 默认情况下不再以 /# 为前缀。

Grunt

以前是 Sails 核心一部分的 Grunt 任务管理功能现已移至单独的 sails-hook-grunt 模块。现有应用只需 npm install --save sails-hook-grunt 即可继续使用 Grunt。但是，通过修改应用的 Gruntfile.js，您可以利用 sails-hook-grunt 包含所有以前必须在项目级别安装的 grunt-contrib 模块这一事实。新的 Gruntfile.js 包含

module.exports = function(grunt) {

  var loadGruntTasks = require('sails-hook-grunt/accessible/load-grunt-tasks');

  // Load Grunt task configurations (from `tasks/config/`) and Grunt
  // task registrations (from `tasks/register/`).
  loadGruntTasks(__dirname, grunt);

};

假设您没有自定义应用中的 Gruntfile，您可以将 Gruntfile.js 替换为此代码，然后安全地运行

npm uninstall --save grunt-contrib-clean
npm uninstall --save grunt-contrib-coffee
npm uninstall --save grunt-contrib-concat
npm uninstall --save grunt-contrib-copy
npm uninstall --save grunt-contrib-cssmin
npm uninstall --save grunt-contrib-jst
npm uninstall --save grunt-contrib-less
npm uninstall --save grunt-contrib-uglify
npm uninstall --save grunt-contrib-watch
npm uninstall --save grunt-sails-linker
npm uninstall --save grunt-sync
npm uninstall --save grunt-cli

以从项目中移除这些依赖项。

故障排除

启动时仍然显示 v0.12？

确保您已在项目中本地安装了 sails，并且您正在使用 v1 版本的命令行工具。

要全局安装 v1.0，请运行 npm install sails@^1.0.0 -g。要为特定 Sails 应用安装它，请 cd 到该应用的目录中，然后运行 npm install sails@^1.0.0 --save。（本地安装后，请务必也安装必要的 hook——见上文。）