Sails 數(shù)據(jù)源Datastore實戰(zhàn)指南配置、無模型訪問與底層數(shù)據(jù)庫操作【免費下載鏈接】sailsRealtime MVC Framework for Node.js項目地址: https://gitcode.com/gh_mirrors/sa/sails**Datastore數(shù)據(jù)源**是 Sails 應(yīng)用訪問數(shù)據(jù)庫的入口抽象它代表應(yīng)用所配置的一個具體數(shù)據(jù)源通常對應(yīng)一個真實的數(shù)據(jù)庫實例。本文以 docs/reference/waterline/datastores/datastores.md 為主線完整講解數(shù)據(jù)源的配置方式、Sails 啟動時自動注冊的數(shù)據(jù)源實例、如何脫離模型直接訪問底層數(shù)據(jù)庫以及.manager、.driver、.leaseConnection()、.sendNativeQuery()、.transaction()五個核心 API 的用法與源碼印證。讀完本文你將能夠為應(yīng)用配置單庫或多庫環(huán)境并在需要原生 SQL、事務(wù)或連接池復(fù)用等場景下直接操控底層數(shù)據(jù)庫。什么是 DatastoreDatastores代表為應(yīng)用配置的數(shù)據(jù)源。一個 datastore 通常對應(yīng)一個特定的數(shù)據(jù)庫例如本地 MySQL 服務(wù)器中運行的數(shù)據(jù)庫公司數(shù)據(jù)中心里遠程部署的 PostgreSQL 數(shù)據(jù)庫云服務(wù)商托管的遠程 MongoDB 數(shù)據(jù)庫。在 Sails 中所有數(shù)據(jù)庫訪問最終都經(jīng)由 datastore 完成。每個 模型 都與某一個 datastore 建立綁定關(guān)系因此每當調(diào)用模型的內(nèi)置方法如.find()、.create()時模型都會隱式地與其配置的 datastore 通信開發(fā)者在大多數(shù)場景下無需關(guān)心底層連接細節(jié)。配置 Datastores數(shù)據(jù)源在sails.config.datastores中配置。在標準 Sails 應(yīng)用中對應(yīng)的物理文件是config/datastores.js。該文件是一組告訴 Sails 在執(zhí)行內(nèi)置模型方法如.find()、.create()時到哪里讀取或保存數(shù)據(jù)的配置主要用于配置開發(fā)數(shù)據(jù)庫以及被個別模型使用的獨立數(shù)據(jù)庫詳見 docs/anatomy/config/datastores.js.md。Sails 應(yīng)用默認自帶一個隱式implicitdatastore所有模型默認都會使用它。對很多應(yīng)用來說這一個默認數(shù)據(jù)源已經(jīng)足夠但如果你的應(yīng)用需要同時操作多個數(shù)據(jù)庫可以為額外的、具名的 datastore 添加配置例如legacyProductDb// config/datastores.js module.exports.datastores { // 隱式默認數(shù)據(jù)源所有未顯式指定 datastore 的模型都會使用它 default: { adapter: sails-mysql, url: mysql://rootlocalhost:3306/my_app_db, }, // 額外的具名數(shù)據(jù)源供特定模型或代碼顯式引用 legacyProductDb: { adapter: sails-mysql, url: mysql://rootlocalhost:3306/legacy_products, }, };配置好具名數(shù)據(jù)源后可以讓某個模型單獨綁定它在模型的datastore屬性中聲明也可以在運行時通過sails.getDatastore(legacyProductDb)直接獲取該數(shù)據(jù)源實例。關(guān)于各配置項的詳細說明可參閱 sails.config.models 與 sails.config.connections 相關(guān)文檔。無模型使用 Datastore注冊的數(shù)據(jù)源實例雖然模型會自動與其 datastore 通信但有時我們需要脫離任何特定模型直接與數(shù)據(jù)源對話。為此當應(yīng)用啟動lift時Sails 會為每個配置的數(shù)據(jù)源自動實例化一個對象稱為注冊的數(shù)據(jù)源實例registered datastore instances。在運行時獲取某個數(shù)據(jù)源實例有兩種方式全局方法sails.getDatastore()// 獲取默認數(shù)據(jù)源 var datastore sails.getDatastore(); // 獲取具名數(shù)據(jù)源 var legacyDatastore sails.getDatastore(legacyProductDb);模型方法.getDatastore()獲取某個特定模型所綁定的數(shù)據(jù)源var datastore Pet.getDatastore();注意.getDatastore()是同步方法無需await、Promise 鏈或傳統(tǒng) Node 回調(diào)。獲取到的注冊數(shù)據(jù)源實例對外暴露了自己的方法與屬性例如.leaseConnection()和.manager它們提供了直接與底層數(shù)據(jù)庫對話的便捷途徑。本小節(jié)文檔的其余頁面正是對這些數(shù)據(jù)源方法/屬性的詳細說明下面逐一展開。.manager底層連接管理器.manager是當前數(shù)據(jù)源的實時連接管理器live connection manager。根據(jù)所使用適配器的不同它可能代表一個連接池connection pool單個連接或者一個預(yù)配置的客戶端庫實例的引用。用法datastore.manager;示例直連 MongoDB 集合由于sails-mongo暴露的連接管理器實際上就是 Mongo 客戶端driver的db實例可以直接把它當作 Mongo 的db使用// sails-mongo 的連接管理器就是 Mongo 客戶端的 db 實例可以當作 db 使用 var db Pet.getDatastore().manager; // 現(xiàn)在可以做任何我們能用 Mongo db 實例做的事 var rawMongoCollection db.collection(Pet.tableName);這里使用Pet.tableName而非硬編碼表名可以保證即使在模型表名改變時代碼仍然正確。該屬性的完整說明見 .manager。.driver通用的底層驅(qū)動.driver是當前數(shù)據(jù)源的通用、無狀態(tài)、底層驅(qū)動如果適配器支持的話。?? 該屬性不保證對所有數(shù)據(jù)庫適配器都存在。如果數(shù)據(jù)源底層適配器不支持標準化的驅(qū)動接口那么.driver將不存在。用法datastore.driver;示例動態(tài)連接任意數(shù)據(jù)庫想象你在構(gòu)建一個類似 phpMyAdmin 的結(jié)構(gòu)化數(shù)據(jù)可視化工具可能需要動態(tài)地連接各種不同的數(shù)據(jù)庫。此時.driver的通用性就派上用場了// 獲取我們數(shù)據(jù)庫例如 MySQL的通用無狀態(tài)驅(qū)動 var Driver sails.getDatastore().driver; // 用它創(chuàng)建我們自己的動態(tài)連接管理器例如連接池 var managerReport await Driver.createManager({ connectionString: req.param(connectionUrl) }); var manager managerReport.manager; var db; try { db (await Driver.getConnection({ manager: managerReport.manager })).connection; } catch (err) { await Driver.destroyManager({ manager: managerReport.manager }); throw err; } // - - - - - - - - - - - - - - - - - - - - - - - - - - - - // 在這里做一些操作…… // 例如 // await Driver.sendNativeQuery({ // connection: db, // nativeQuery: ... // }); // - - - - - - - - - - - - - - - - - - - - - - - - - - - - // 最后在繼續(xù)之前拆除動態(tài)連接管理器 // 同時也會釋放上面獲取的活動連接 await Driver.destroyManager({ manager: managerReport.manager }); return res.ok();可以看到.driver提供了createManager、getConnection、sendNativeQuery、destroyManager等標準驅(qū)動接口方法適合需要完全掌控連接生命周期的高級場景。詳見 .driver。.leaseConnection()租用連接執(zhí)行多條查詢.leaseConnection()從數(shù)據(jù)源租用一個新的連接用于在同一條連接上執(zhí)行多條查詢即讓during函數(shù)中提供的邏輯可以復(fù)用這條數(shù)據(jù)庫連接。用法await datastore.leaseConnection(during);或者var result await datastore.leaseConnection(during);參數(shù)參數(shù)類型說明1during((function))一個過程參數(shù)procedural parameter。當連接就緒后 Sails 會自動調(diào)用它并傳入下方表格中的參數(shù)。during函數(shù)收到的參數(shù)參數(shù)類型說明1db((ref))新租用的數(shù)據(jù)庫連接。關(guān)于用它做什么可參見.usingConnection()。注意在 Sails 1.1.0 之前.leaseConnection()的推薦用法是讓during代碼在結(jié)束時調(diào)用回調(diào)proceed。只要你的during函數(shù)簽名中不包含第二個參數(shù)這個回調(diào)就不再必要——直接用async/await或返回 Promise 即可。返回值類型說明((Ref?))during函數(shù)返回的可選結(jié)果數(shù)據(jù)。例如你在during中寫了return foo;那么這里就是foo。錯誤名稱類型拋出時機UsageError((Error))傳入了無效參數(shù)時AdapterError((Error))數(shù)據(jù)庫適配器內(nèi)部出錯時Error((Error))發(fā)生其他意外情況時Sails 與 Waterline 中錯誤的協(xié)商方式可參考 Concepts Models and ORM Errors。示例租用連接執(zhí)行兩條查詢后歸還從默認數(shù)據(jù)源租用一個數(shù)據(jù)庫連接用它發(fā)送兩條查詢再將其釋放回連接池var inventory await sails.getDatastore() .leaseConnection(async (db) { var location await Location.findOne({ id: inputs.locationId }) .usingConnection(db); if (!location) { let err new Error(Cannot find location with that id (inputs.locationId)); err.code E_NO_SUCH_LOCATION; throw err; } // 獲取該位置的所有產(chǎn)品 var productOfferings await ProductOffering.find({ location: inputs.locationId }) .populate(productType) .usingConnection(db); return productOfferings; }) .intercept(E_NO_SUCH_LOCATION, notFound); // 完成我們對數(shù)據(jù)庫連接所做的操作都成功了。 // 現(xiàn)在可以繼續(xù)執(zhí)行業(yè)務(wù)邏輯。關(guān)鍵點在于Location.findOne(...)與ProductOffering.find(...)都通過.usingConnection(db)顯式指定使用租來的這條連接從而保證兩條查詢落在同一條連接上。完整文檔見 .leaseConnection()。.sendNativeQuery()執(zhí)行原生 SQL.sendNativeQuery()使用當前數(shù)據(jù)源執(zhí)行原生 SQL 查詢。??.sendNativeQuery()僅對配置了 SQL 數(shù)據(jù)庫例如 MySQL、SQL Server、PostgreSQL的 Sails/Waterline 數(shù)據(jù)源可用。具體的 SQL 語法與結(jié)果格式因數(shù)據(jù)庫而異需要查閱你所使用的底層數(shù)據(jù)庫適配器的文檔。用法var rawResult await datastore.sendNativeQuery(sql, valuesToEscape);參數(shù)參數(shù)類型說明1sql((string))以對應(yīng)數(shù)據(jù)庫方言書寫的 SQL 字符串。支持$1、$2等模板語法見下方示例。如果你使用了自定義表名或列名務(wù)必直接引用這些物理名稱而不是模型標識符和屬性名。2valuesToEscape((array?))需要被 SQL 轉(zhuǎn)義并注入sql的動態(tài)、不可信字符串數(shù)組。如果沒有動態(tài)值需要注入省略該參數(shù)或傳入空數(shù)組即可。返回值類型說明((Ref?))數(shù)據(jù)庫適配器返回的原始結(jié)果如果有。具體格式取決于傳入的 SQL 查詢以及所使用的適配器/方言。錯誤名稱類型拋出時機UsageError((Error))傳入了無效參數(shù)時AdapterError((Error))數(shù)據(jù)庫適配器內(nèi)部出錯時Error((Error))發(fā)生其他意外情況時示例參數(shù)化查詢下面是一個通用示例適用于幾乎所有關(guān)系型數(shù)據(jù)庫。請記住用法與結(jié)果數(shù)據(jù)會隨 SQL 查詢以及適配器/方言的不同而變化。Sails/Waterline 的標準 MySQL 適配器 使用mysqlNPM 包PostgreSQL 適配器 使用pg包。// 構(gòu)建我們的 SQL 查詢模板 var NAMES_OF_PETS_SQL SELECT pet.name FROM pet WHERE pet.species_label $1 OR pet.species_label $2; // 發(fā)送給數(shù)據(jù)庫 var rawResult await sails.getDatastore().sendNativeQuery(NAMES_OF_PETS_SQL, [ dog, cat ]); sails.log(rawResult); // (結(jié)果格式取決于傳入的 SQL 查詢以及所使用的適配器/方言) // 然后解析原始結(jié)果做你想做的事 return exits.success();示例中$1、$2是占位符實際值由valuesToEscape數(shù)組按順序注入由適配器負責 SQL 轉(zhuǎn)義從而避免 SQL 注入。自定義表名/列名的處理你書寫的 SQL 應(yīng)引用表名和列名而不是模型標識符和屬性名。如果你的模型定義了自定義表名或?qū)傩远x了自定義列名請確保在原生 SQL 中使用這些自定義名稱。如果擔心自定義表名/列名散落在代碼中難以維護可以借助 Waterline 模型暴露的tableName與columnName引用動態(tài)構(gòu)建 SQL 模板var NAMES_OF_PETS_SQL SELECT ${Pet.tableName}.${Pet.schema.name.columnName} FROM ${Pet.tableName} WHERE ${Pet.tableName}.${Pet.schema.speciesLabel.columnName} $1 OR ${Pet.tableName}.${Pet.schema.speciesLabel.columnName} $2 ;但請注意返回結(jié)果中的自定義列名問題仍需要自己處理。.sendNativeQuery()返回的rawResult本質(zhì)上與數(shù)據(jù)庫強相關(guān)、綁定在物理層因此它會繼承你在物理層設(shè)置的各種復(fù)雜性包括模型定義中的自定義表名/列名。注意事項該方法只適用于 SQL 數(shù)據(jù)庫。如果使用的是 MongoDB 等其他數(shù)據(jù)庫請通過.manager獲取原始 MongoDB 客戶端或通過.driver獲取靜態(tài)底層數(shù)據(jù)庫庫如mysql、pg等。取決于所使用的適配器valuesToEscape可能會被原地修改mutated。這是出于性能考慮做出的刻意設(shè)計可能在 Sails 未來的大版本中改變。因此如果你把某個變量傳給valuesToEscape且后續(xù)還要用到該變量請先克隆一份再傳入。完整文檔見 .sendNativeQuery()。.transaction()數(shù)據(jù)庫事務(wù).transaction()獲取一個預(yù)配置的、延遲執(zhí)行deferred的對象它掛接在sails-mysql或sails-postgresql適配器以及相應(yīng)的 driver上用于在事務(wù)中執(zhí)行一組操作。用法await datastore.transaction(during);或者var result await datastore.transaction(during);參數(shù)參數(shù)類型說明1during((function))見下方 during參數(shù) 表格。during函數(shù)收到的參數(shù)參數(shù)類型說明1db((ref))租用的事務(wù)性數(shù)據(jù)庫連接。參見.usingConnection()。注意在 Sails 1.1.0 之前.transaction()的推薦用法是讓during代碼在結(jié)束時調(diào)用回調(diào)proceed。只要during函數(shù)簽名中不包含第二個參數(shù)就不再需要該回調(diào)。返回值類型說明((Ref?))during函數(shù)返回的可選結(jié)果數(shù)據(jù)。例如在during中寫了return foo;則這里就是foo。錯誤名稱類型拋出時機UsageError((Error))傳入了無效參數(shù)時AdapterError((Error))數(shù)據(jù)庫適配器內(nèi)部出錯時Error((Error))發(fā)生其他意外情況時示例賬戶轉(zhuǎn)賬將指定金額從一個用戶余額中減去并加到另一個用戶余額中// 例如在某個 action 中 var flaverr require(flaverr); await sails.getDatastore() .transaction(async (db) { var myAccount await BankAccount.findOne({ owner: this.req.session.userId }) .usingConnection(db); if (!myAccount) { throw new Error(Consistency violation: Database is corrupted-- logged in user record has gone missing); } var recipientAccount await BankAccount.findOne({ owner: inputs.recipientId }).usingConnection(db) if (!recipientAccount) { throw flaverr(E_NO_SUCH_RECIPIENT, new Error(There is no recipient with that id)); } // 計算從當前登錄用戶余額中扣除后的新余額 var myNewBalance myAccount.balance - inputs.amount; // 如果這會讓當前用戶余額為負則中止 // 事務(wù)會自動回滾 if (myNewBalance 0) { throw flaverr(E_INSUFFICIENT_FUNDS, new Error(Insufficient funds)); } // 更新當前用戶賬戶 await BankAccount.update({ owner: this.req.session.userId }) .set({ balance: myNewBalance }) .usingConnection(db); // 更新收款人賬戶 await BankAccount.update({ owner: inputs.recipientId }) .set({ balance: recipientAccount.balance inputs.amount }) .usingConnection(db); }) .intercept(E_INSUFFICIENT_FUNDS, ()badRequest) .intercept(E_NO_SUCH_RECIPIENT, ()notFound);事務(wù)機制保證只要during內(nèi)任何一步拋出錯誤例如余額不足整個事務(wù)都會自動回滾兩個賬戶的余額不會出現(xiàn)只扣不增或只增不扣的不一致狀態(tài)。通過.intercept()可以把自定義錯誤碼優(yōu)雅地映射為badRequest、notFound等 Sails 響應(yīng)。提示上面的示例僅為演示用途在實際項目中這類增減/遞減邏輯還應(yīng)包含行級鎖row-level locking以避免并發(fā)場景下的競態(tài)條件。完整文檔見 .transaction()。源碼印證數(shù)據(jù)源 API 在 Sails 內(nèi)部的實際使用Sails 自身的 Blueprint 路由實現(xiàn)就大量使用了本文介紹的數(shù)據(jù)源 API。以 lib/hooks/blueprints/actions/create.js 和 lib/hooks/blueprints/actions/update.js 為例其中都有如下形式的調(diào)用注釋// Model.getDatastore().transaction(function during(db, proceed){ ... })在 lib/hooks/blueprints/actions 目錄下create.js、update.js、destroy.js、add.js、remove.js、replace.js等多個內(nèi)置 action 都引用了getDatastore這表明Sails 在框架內(nèi)部正是通過Model.getDatastore()獲取數(shù)據(jù)源實例再在其上執(zhí)行事務(wù)等底層操作。你在自定義代碼中通過sails.getDatastore()/Model.getDatastore()獲得的正是同一類數(shù)據(jù)源實例API 完全一致?？偨Y(jié)與最佳實踐場景推薦 API對應(yīng)文檔獲取默認/具名數(shù)據(jù)源實例sails.getDatastore(name?)sails.getDatastore()獲取某模型綁定的數(shù)據(jù)源Model.getDatastore().getDatastore()訪問底層連接池/客戶端datastore.manager.manager動態(tài)創(chuàng)建連接管理器連接池datastore.driver.driver同一條連接上執(zhí)行多條查詢datastore.leaseConnection(during).leaseConnection()執(zhí)行原生 SQL僅 SQL 數(shù)據(jù)庫datastore.sendNativeQuery(sql, values).sendNativeQuery()事務(wù)性多步數(shù)據(jù)庫操作datastore.transaction(during).transaction()實踐要點絕大多數(shù)場景無需直接操作數(shù)據(jù)源——模型方法會自動與綁定數(shù)據(jù)源通信多數(shù)據(jù)庫應(yīng)用通過在config/datastores.js中配置具名數(shù)據(jù)源并用sails.getDatastore(name)獲取需要事務(wù)、原生 SQL 或連接復(fù)用時記得配合.usingConnection()讓查詢顯式使用租來的連接使用.sendNativeQuery()時務(wù)必通過$1、$2占位符配合valuesToEscape注入動態(tài)值防止 SQL 注入并注意valuesToEscape可能被適配器原地修改只有 SQL 數(shù)據(jù)源支持.sendNativeQuery()與.transaction()MongoDB 等場景請使用.manager或.driver?！久赓M下載鏈接】sailsRealtime MVC Framework for Node.js項目地址: https://gitcode.com/gh_mirrors/sa/sails創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考