編輯頁面

升級至 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 核心團隊聊天。）

重點檢查清單：升級到 1.0 版本時您必須執行的事項

升級工具會盡力協助處理其中一些項目，但它不會為您變更應用程式特定的程式碼！

• 步驟 0：檢查您的 Node 版本
• 步驟 1：安裝 Hook & 更新相依性
• 步驟 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：安裝 Hook & 更新相依性

Sails v1 引入了 自訂建置。這表示某些核心 Hook 現在會以您應用程式的直接相依性安裝，讓您對相依性有更多控制權，並使 npm install sails 的執行速度顯著提升。因此，您需要做的第一件事是安裝您正在使用的核心 Hook。（同時，請務必更新以下清單中提及的其他相依性。）

• 將 sails-hook-orm 套件 安裝到您的應用程式中，指令為 npm install --save sails-hook-orm，除非您的應用程式已停用 ORM Hook。
• 將 sails-hook-sockets 套件 安裝到您的應用程式中，指令為 npm install --save sails-hook-sockets，除非您的應用程式已停用 Socket Hook。
• 將 sails-hook-grunt 套件 安裝到您的應用程式中，指令為 npm install --save sails-hook-grunt，除非您的應用程式已停用 Grunt Hook。
• 安裝最新版本的資料庫配接器。例如，如果您使用 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 將載入組態檔中引用的所有資料庫配接器，無論模型是否實際使用它們。有關更多資訊，請參閱關於資料庫設定的遷移指南章節。
• 使用 CSRF 時，/csrfToken 路由 不再預設提供給所有應用程式。如果您在應用程式中使用此路由，則需要手動將其添加到 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 方法（又稱動詞）已變更
  • add 的 RESTful 藍圖路由位址已從 POST 變更為 PUT。
  • update 的 RESTful 藍圖路由位址已從 PUT 變更為 PATCH。
• 如果您的應用程式依賴藍圖動作的預設 Socket 通知，請注意，為提升效能進行了一些升級，這會稍微變更這些訊息的結構
  • 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 檔案，則需要建立一個。
  • 與此相關的是，藍圖 create 動作 現在在成功時將傳回 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 方法的實驗性「switchback 風格」用法不再受支援。只有函數回呼可以與 Waterline 模型方法一起使用。
• 實驗性的 create 自動遷移方案不再受支援。強烈建議您使用遷移工具（例如 Knex）來處理生產資料庫的遷移。
• 實驗性的 forceLoadAdapter 資料儲存區設定不再受支援。相反地，每當 Sails 啟動時，都會自動載入 config/datastores.js（以前是 config/connections.js）中引用的所有配接器。
• 實驗性的 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 issue 中閱讀更多相關資訊

資料庫設定的變更

• 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，然後將 myPostgresqlDb 金鑰添加到 config/datastores.js 的方法。這使得變更不同環境使用的資料儲存區變得容易得多（例如，透過變更 config/env/production.js 中 default 資料儲存區的配置）。
• 應用程式中配置的所有資料儲存區都將在執行時載入（而不是僅載入至少一個模型正在使用的資料儲存區）。這的好處是允許在單個模型上下文之外使用資料儲存區，但這確實意味著，如果您不希望在 Sails 啟動時連接到特定資料庫，則應註解掉該資料儲存區連線配置！

巢狀建立和更新

• .create()、.update() 和 .add() 模型方法不再支援建立新的「子」記錄以立即連結到新的或現有的父記錄。例如，給定一個 User 模型，透過名為 pet 的屬性與 Animal 模型具有單數關聯，則無法將 pet 設定為表示全新 Animal 值（又稱「巢狀建立」）的字典。相反地，先建立新的 Animal，然後在建立新的 User 時使用其主鍵設定 pet。
• 同樣地，create、update 和 add 藍圖動作不再支援巢狀建立。
• .update() 模型方法及其相關聯的 藍圖動作 不再支援取代整個複數關聯。如果記錄透過 「一對多」 或 「多對多」 關聯連結到一個或多個其他記錄，並且您希望將其連結到完全不同的記錄集，請使用 .replaceCollection() 模型方法 或 replace 藍圖動作。

模型設定的變更

重點摘要

從您的模型中移除任何 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 模型方法的 criteria（條件）在大多數情況下會直接就地修改（但在 Sails/Waterline v0.12 中，情況不一定如此）。
• 彙總子句 (sum、average、min、max 和 groupBy) 不再於 criteria（條件）中支援。請改為參閱新的模型方法 .sum() 和 .avg()。
• 關於 limit 和 skip 的變更
  • limit: 0 不再與 limit: undefined 作用相同。它現在匹配 0 個結果，而不是匹配無限多個結果。
  • 避免指定小於 0 的 limit。它仍然會被忽略，行為如同 limit: undefined，但現在會將棄用警告記錄到 console。
  • skip: -20 不再與 skip: undefined 作用相同。它現在會拒絕執行並拋出錯誤，而不是跳過零個結果。
  • Limit 必須小於 Number.MAX_SAFE_INTEGER（...但有一個例外：為了相容性/便利性，Infinity 會被容許並自動標準化為 Number.MAX_SAFE_INTEGER。）
  • Skip 必須小於 Number.MAX_SAFE_INTEGER

混合 where 子句支援的變更

不再支援具有混合 where 子句的 criteria（條件）字典。例如，請勿使用

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

您應該改用

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

請注意，您仍然可以使用 { username: 'santaclaus' } 作為 { where: { username: 'santaclaus' } } 的簡寫，但您不能將其他頂層 criteria（條件）子句（如 limit）與限制條件（例如 username）混合使用。

對於您使用 Waterline 的可鏈式延遲物件來建構 criteria（條件）的情況，請不用擔心 — 這部分已為您處理好。

安全性

使用 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: false 新增到您希望不受 CSRF 保護的任何路由，例如

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

• sails.config.csrf.origin 不再受支援。您可以將任何自訂 CORS 設定直接新增到您的 CSRF token 路由設定中，例如

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

• sails.config.csrf.grantTokenViaAjax 不再受支援。此設定用於開啟或關閉 CSRF token 授予路由。在 Sails 1.0 中，您需要在 config/routes.js 檔案中手動新增該路由（請參閱上文）。如果您不想通過 AJAX 授予 CSRF token，只需將該路由從 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）的版面配置支援。

資源型 PubSub

• 已移除已棄用的 backwardsCompatibilityFor0.9SocketClients 設定。
• 已移除已棄用的 .subscribers() 方法。
• 已移除已棄用的「firehose」功能。
• 已移除對 0.9.x socket client API 的支援。
• 以下資源型 pubsub 方法也已移除
  • .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 設計的 Session 中介軟體（例如非常舊版本的 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']）可以避免 session 的問題（有關詳細資訊，請參閱 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 應用程式安裝它，請切換到該應用程式的目錄，然後執行 npm install sails@^1.0.0 --save。（在本機安裝後，請務必也安裝必要的 hooks — 請參閱上文。）