簡介dataDemo.rar 是一份面向中初級 C# 開發(fā)者、在校學(xué)生及數(shù)據(jù)庫入門者的多數(shù)據(jù)庫操作演示包圍繞 Oracle、MySQL、SQL Server、SQLite 的連接配置、SQL 執(zhí)行、結(jié)果集讀取與事務(wù)處理展開適合對比 ADO.NET 訪問不同數(shù)據(jù)庫的共性與差異。壓縮包共 38 個(gè)文件約 623KB以 12 個(gè) cs 源碼、3 個(gè) exe、3 個(gè) dll、3 個(gè) config 配置、1 個(gè) sln 解決方案和 1 個(gè) db 數(shù)據(jù)庫文件為主另有 resx、resources 等窗體資源體量輕便且工程結(jié)構(gòu)完整。已有 755 人學(xué)習(xí)。讀者可獲得可運(yùn)行的窗體示例、數(shù)據(jù)庫輔助類封裝思路、連接字符串配置參考以及多數(shù)據(jù)庫切換的對照案例也能了解命令對象、數(shù)據(jù)適配器、異常處理與事務(wù)管理在示例中的組織方式便于快速理解 C# 數(shù)據(jù)庫訪問項(xiàng)目的搭建流程并注意不同數(shù)據(jù)庫驅(qū)動、命名空間與連接參數(shù)的差異在此基礎(chǔ)上改造成自己的練習(xí)或小型應(yīng)用。1. 三種數(shù)據(jù)庫一套代碼這個(gè) Demo 到底解決了什么問題有個(gè)場景在交付型項(xiàng)目里反復(fù)出現(xiàn)同一套業(yè)務(wù)系統(tǒng)要裝到三個(gè)客戶那里A 客戶機(jī)房只給一臺 OracleB 客戶運(yùn)維只認(rèn) SQL ServerC 客戶要求單機(jī)部署、數(shù)據(jù)落在本地文件里。業(yè)務(wù)邏輯只有一份數(shù)據(jù)庫方言卻有三套每接一個(gè)客戶就把數(shù)據(jù)訪問層重寫一遍維護(hù)成本很快就失控。dataDemo 這個(gè) C# 示例包解決的就是這件事——用一層不厚的抽象把 Oracle、SQL Server、SQLite 在連接串、參數(shù)占位符、自增主鍵、分頁語法上的差異收攏到一處上層業(yè)務(wù)代碼只認(rèn)一套接口。它適合兩類人一類是剛接手多庫適配任務(wù)的 C# 開發(fā)者需要一份能跑、能改的參照另一類是想搞清楚 ADO.NET 工廠模式到底怎么落地的人光看文檔容易停在概念上抄一遍代碼才知道哪些地方會翻車。后面按「結(jié)構(gòu)長什么樣、核心代碼怎么寫、怎么跑起來、哪里容易踩坑、怎么改成能上生產(chǎn)的樣子」的順序拆代碼都可以直接抄進(jìn)項(xiàng)目里改。2. 工程結(jié)構(gòu)與技術(shù)選型先看清目錄再動手改拿到一個(gè)壓縮包我習(xí)慣先看目錄再動手因?yàn)槟夸浗Y(jié)構(gòu)基本暴露了作者的取舍。dataDemo 的組織方式是按「抽象層 各庫實(shí)現(xiàn) 演示入口」三段拆的而不是把所有邏輯塞進(jìn)一個(gè)DbHelper.cs里用switch分支判斷數(shù)據(jù)庫類型。這個(gè)選擇看起來只是文件多了幾個(gè)實(shí)際影響的是編譯依賴和發(fā)布體積——用 SQLite 的客戶不需要在機(jī)器上裝 Oracle 驅(qū)動。2.1 目錄分層與項(xiàng)目組織解壓后的結(jié)構(gòu)大致是這樣中間省略了bin/obj和資源文件dataDemo/ ├── DataDemo.sln ├── src/ │ ├── DataDemo.Core/ # 抽象層接口、工廠、配置模型 │ │ ├── IDbProvider.cs │ │ ├── DbProviderFactory.cs │ │ ├── DatabaseKind.cs │ │ ├── QueryParameter.cs │ │ └── ConnectionOptions.cs │ ├── DataDemo.Providers.SqlServer/ # 只引用 Microsoft.Data.SqlClient │ ├── DataDemo.Providers.Oracle/ # 只引用 Oracle.ManagedDataAccess.Core │ ├── DataDemo.Providers.Sqlite/ # 只引用 Microsoft.Data.Sqlite │ └── DataDemo.App/ # 控制臺入口跑演示用例 ├── sql/ │ ├── oracle/01_schema.sql │ ├── sqlserver/01_schema.sql │ └── sqlite/01_schema.sql └── README.mdDataDemo.Core里沒有任何數(shù)據(jù)庫驅(qū)動的引用只定義接口和值對象這一層可以被打包成獨(dú)立的 NuGet 包給別的項(xiàng)目用。三個(gè)Providers.*項(xiàng)目各自只依賴一個(gè)驅(qū)動互不干擾。DataDemo.App引用 Core 加任意一個(gè) Provider 就能跑——這一點(diǎn)很關(guān)鍵意味著發(fā)布給 SQLite 客戶時(shí)產(chǎn)物里不會混進(jìn)一個(gè)幾十兆的 Oracle 托管程序集。sql/目錄下三份建表腳本是另一個(gè)容易被忽略的重點(diǎn)。同一個(gè)業(yè)務(wù)表在三套庫里的寫法差異比想象中大-- OracleNUMBER(19) 做主鍵VARCHAR2 存字符串時(shí)間用 TIMESTAMP CREATE TABLE T_ORDER ( ID NUMBER(19) GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY, ORDER_NO VARCHAR2(64) NOT NULL, AMOUNT NUMBER(18,2) NOT NULL, CREATED_AT TIMESTAMP NOT NULL );-- SQL ServerBIGINT IDENTITY字符串用 NVARCHAR 避免中文丟失 CREATE TABLE T_ORDER ( ID BIGINT IDENTITY(1,1) PRIMARY KEY, ORDER_NO NVARCHAR(64) NOT NULL, AMOUNT DECIMAL(18,2) NOT NULL, CREATED_AT DATETIME2 NOT NULL );-- SQLite沒有真正的 decimal日期只能存字符串或整數(shù) CREATE TABLE T_ORDER ( ID INTEGER PRIMARY KEY AUTOINCREMENT, ORDER_NO TEXT NOT NULL, AMOUNT NUMERIC NOT NULL, CREATED_AT TEXT NOT NULL -- ISO8601 字符串如 2024-05-01T10:00:00 );三份腳本的字段名刻意保持一致這樣上層 SQL 的列名不用改差異全部集中到類型映射和分頁語法上。SQLite 那份的CREATED_AT用 TEXT 存 ISO8601是踩過坑之后的做法——早期用DATETIME聲明寫入時(shí)被驅(qū)動按本地時(shí)區(qū)轉(zhuǎn)成字符串跨時(shí)區(qū)讀回來就對不上改成顯式 TEXT 后行為完全可控。2.2 數(shù)據(jù)訪問層的抽象設(shè)計(jì)抽象層的核心是一個(gè)接口把「一個(gè)數(shù)據(jù)庫需要提供的能力」列全。寫得薄一點(diǎn)沒關(guān)系但不能少方法否則上層遲早要if (kind ...)兜底public interface IDbProvider { // 數(shù)據(jù)庫類型標(biāo)識用于日志和分支判斷 DatabaseKind Kind { get; } // 創(chuàng)建一個(gè)未打開的連接由調(diào)用方負(fù)責(zé) Open/Dispose DbConnection CreateConnection(string connectionString); // 把統(tǒng)一的 {name} 占位符翻譯成當(dāng)前方言的寫法 string TranslateSql(string templateSql); // 創(chuàng)建參數(shù)并綁定值內(nèi)部處理類型映射 DbParameter CreateParameter(string name, object? value); // 表名/列名包裹Oracle 用雙引號SQL Server 用方括號 string QuoteIdentifier(string rawName); // 生成分頁 SQL三套庫寫法完全不同 string BuildPagingSql(string baseSql, string orderBy, int skip, int take); }CreateConnection返回未打開的連接而不是直接Open()是因?yàn)檎{(diào)用方往往需要在打開后立刻設(shè)置CommandTimeout或者掛事件提前打開會讓這些操作無處安放。這個(gè)約定寫在接口注釋里實(shí)際項(xiàng)目中最容易被后來的人改壞。配套的工廠類負(fù)責(zé)根據(jù)配置創(chuàng)建具體實(shí)現(xiàn)用的是延遲加載避免在只跑 SQLite 的環(huán)境里觸發(fā) Oracle 程序集的加載public static class DbProviderFactory { // 緩存已創(chuàng)建的 providerConfiguration 里通常是單例注冊 private static readonly ConcurrentDictionaryDatabaseKind, FuncIDbProvider Registry new() { [DatabaseKind.SqlServer] () new SqlServerProvider(), [DatabaseKind.Oracle] () new OracleProvider(), [DatabaseKind.Sqlite] () new SqliteProvider() }; public static IDbProvider Create(DatabaseKind kind) { // 用函數(shù)注冊而不是直接 new保證只有被選中的那個(gè) provider 才會加載對應(yīng)程序集 if (!Registry.TryGetValue(kind, out var factory)) throw new NotSupportedException($未注冊的數(shù)據(jù)庫類型: {kind}); return factory(); } }這里用FuncIDbProvider而不是直接存實(shí)例原因是程序集加載時(shí)機(jī)如果字典里直接new SqlServerProvider()靜態(tài)構(gòu)造函數(shù)執(zhí)行時(shí)就會去解析Microsoft.Data.SqlClient的引用在沒裝這個(gè)包的機(jī)器上會直接拋FileNotFoundException報(bào)錯(cuò)信息還很難看懂。改成函數(shù)之后只有真正調(diào)用Create的那一刻才會觸發(fā)加載。ConnectionOptions是一個(gè)簡單的配置模型對應(yīng)appsettings.json里的一段屬性類型說明KindDatabaseKind枚舉值SqlServer / Oracle / SqliteConnectionStringstring原始連接串不做任何加工CommandTimeoutSecondsint默認(rèn) 30報(bào)表類查詢要調(diào)到 120 以上EnableSensitiveLoggingbool打開后日志里會打印參數(shù)值測試環(huán)境用生產(chǎn)必須關(guān)2.3 依賴與版本三個(gè)驅(qū)動怎么選選型這塊沒有太多懸念但每個(gè)包都有坑值得單獨(dú)說一句數(shù)據(jù)庫推薦 NuGet 包關(guān)鍵取舍SQL ServerMicrosoft.Data.SqlClient不要再用System.Data.SqlClient后者已停止演進(jìn)且不支持新版 TLSOracleOracle.ManagedDataAccess.Core純托管實(shí)現(xiàn)不需要在機(jī)器上裝 Instant ClientSQLiteMicrosoft.Data.Sqlite輕量底層是 SQLitePCLRaw跨平臺打包省事.csproj里按項(xiàng)目分別引用不要圖省事全塞進(jìn) App!-- DataDemo.Providers.SqlServer.csproj -- ItemGroup PackageReference IncludeMicrosoft.Data.SqlClient Version5.* / /ItemGroup !-- DataDemo.Providers.Oracle.csproj -- ItemGroup PackageReference IncludeOracle.ManagedDataAccess.Core Version23.* / /ItemGroup !-- DataDemo.Providers.Sqlite.csproj -- ItemGroup PackageReference IncludeMicrosoft.Data.Sqlite Version8.* / /ItemGroup版本號用5.*這種浮動寫法是因?yàn)檫@幾個(gè)包的安全補(bǔ)丁發(fā)得比較勤鎖死小版本過幾個(gè)月就會在漏洞掃描里被標(biāo)紅。但如果項(xiàng)目要發(fā)布到客戶現(xiàn)場且長時(shí)間不更新我一般會把*換成具體版本并在 README 里記一筆避免不同機(jī)器還原出不同版本導(dǎo)致行為不一致。如果團(tuán)隊(duì)里還有人在用System.Data.OracleClient那套東西早就從 .NET Core 里移除了遷移成本比想象中高——連接串格式、異常類型、參數(shù)綁定行為都不一樣別指望改個(gè)包名就能編譯通過。3. 核心代碼拆解一次查詢從模板到結(jié)果的完整鏈路抽象層定義好之后真正花時(shí)間的是三套 Provider 的具體實(shí)現(xiàn)。這一章按調(diào)用鏈順序拆先創(chuàng)建連接再把統(tǒng)一 SQL 模板翻譯成方言然后綁定參數(shù)執(zhí)行最后處理分頁和自增主鍵。這四步每一步都有方言差異抄代碼的時(shí)候按順序?qū)φ罩木托小?.1 連接創(chuàng)建與生命周期管理連接對象必須由調(diào)用方用using釋放這一點(diǎn)三套庫都一樣但連接池的行為差別不小。SQL Server 和 SQLite 的驅(qū)動默認(rèn)開啟池化Oracle 托管驅(qū)動也默認(rèn)開啟問題在于很多人不知道「關(guān)閉連接」只是把連接還給池真正的物理連接還掛著public sealed class SqliteProvider : IDbProvider { public DatabaseKind Kind DatabaseKind.Sqlite; public DbConnection CreateConnection(string connectionString) { // Microsoft.Data.Sqlite 默認(rèn) Poolingtrue連接串里不需要再寫 // 注意SQLite 的 Data Source 是文件路徑相對路徑會以工作目錄為基準(zhǔn) var builder new SqliteConnectionStringBuilder(connectionString) { // 開啟外鍵約束SQLite 默認(rèn)是關(guān)的這個(gè)坑很深 ForeignKeys true, // 忙等待超時(shí)單位秒并發(fā)寫的時(shí)候能少一堆 database is locked DefaultTimeout 30 }; return new SqliteConnection(builder.ToString()); } }ForeignKeys true這行不是可有可無的裝飾。SQLite 的外鍵約束默認(rèn)關(guān)閉建表腳本里寫了REFERENCES也不會生效測試時(shí)插一堆臟數(shù)據(jù)都不報(bào)錯(cuò)等上線后發(fā)現(xiàn)關(guān)聯(lián)表數(shù)據(jù)對不上排查起來非常痛苦。這個(gè)開關(guān)只能在連接級別打開寫在建表腳本里是無效的。Oracle 那邊需要注意連接串的寫法托管驅(qū)動支持 EZConnect 格式不需要tnsnames.orapublic sealed class OracleProvider : IDbProvider { public DatabaseKind Kind DatabaseKind.Oracle; public DbConnection CreateConnection(string connectionString) { // EZConnect 格式: User Idxxx;Passwordxxx;Data Sourcehost:1521/service_name // 如果用 SID 而不是 service_name要寫成 (DESCRIPTION(ADDRESS...)(CONNECT_DATA(SIDxxx))) var conn new OracleConnection(connectionString); // 關(guān)閉語句緩存可以規(guī)避某些版本的游標(biāo)泄漏問題代價(jià)是解析開銷上升 // 一般保持默認(rèn) true 即可只有在壓測發(fā)現(xiàn)游標(biāo)數(shù)持續(xù)上漲時(shí)才改 return conn; } }CreateConnection只創(chuàng)建不打開調(diào)用方拿到后自己Open()。這樣做的另一個(gè)好處是可以在Open()前后加日志計(jì)時(shí)統(tǒng)計(jì)連接建立耗時(shí)——Oracle 首次連接往往要一兩秒這個(gè)數(shù)據(jù)在排查「接口偶發(fā)超時(shí)」時(shí)很有用。3.2 參數(shù)占位符歸一化一處模板三處方言這是整個(gè) Demo 里最值得抄的一段。三套庫的參數(shù)前綴和綁定規(guī)則完全不同數(shù)據(jù)庫參數(shù)前綴參數(shù)名大小寫備注SQL Servername不敏感后跟標(biāo)識符Oracle:name不敏感但綁定按位置參數(shù)名不要帶冒號SQLite$name/name/:name敏感三種前綴都支持選一種統(tǒng)一即可統(tǒng)一的做法是在業(yè)務(wù) SQL 里寫{name}執(zhí)行前翻譯public sealed class ParameterBinder { private readonly char _prefix; public ParameterBinder(DatabaseKind kind) { _prefix kind switch { DatabaseKind.SqlServer , DatabaseKind.Oracle :, DatabaseKind.Sqlite $, _ throw new NotSupportedException(kind.ToString()) }; } /// summary /// 把 {name} 形式的模板翻譯成方言占位符。 /// 注意這里替換的是占位符名稱不是值值仍然走 DbParameter 綁定不存在注入風(fēng)險(xiǎn)。 /// /summary public string Translate(string templateSql) { if (string.IsNullOrWhiteSpace(templateSql)) throw new ArgumentException(SQL 不能為空, nameof(templateSql)); var sb new StringBuilder(templateSql.Length 16); var i 0; while (i templateSql.Length) { // 找到 { 并且后面緊跟合法標(biāo)識符才認(rèn)定是占位符 if (templateSql[i] {) { var end templateSql.IndexOf(}, i 1); if (end i 1) { var name templateSql.Substring(i 1, end - i - 1); if (IsValidName(name)) { sb.Append(_prefix).Append(name); i end 1; continue; } } } sb.Append(templateSql[i]); i; } return sb.ToString(); } // 只允許字母、數(shù)字、下劃線避免把 SQL 里的其他花括號誤判成占位符 private static bool IsValidName(string name) name.Length 0 name.All(c char.IsLetterOrDigit(c) || c _); }逐字掃描而不是用Regex.Replace是因?yàn)檎齽t在超長 SQL 上會有性能開銷而且{在 JSON 函數(shù)、正則表達(dá)式字面量里出現(xiàn)得很頻繁誤傷概率不低。逐字判斷「{ 合法標(biāo)識符 }」這個(gè)組合實(shí)際項(xiàng)目里幾乎不會誤判。翻譯完之后綁定參數(shù)這一步是類型映射的戰(zhàn)場public DbParameter CreateParameter(string name, object? value) { var p _command.CreateParameter(); // Oracle 的參數(shù)名不能帶冒號且 ParameterName 大小寫要與 SQL 中一致 p.ParameterName name; // DBNull 和 null 要區(qū)分開直接賦 null 會拋異常 p.Value value ?? DBNull.Value; // 顯式指定類型避免驅(qū)動做隱式轉(zhuǎn)換導(dǎo)致索引失效 if (value is DateTime dt) { // Oracle 的 DATE 只精確到秒TIMESTAMP 才有毫秒 // 這里統(tǒng)一按 TIMESTAMP 處理建表腳本里對應(yīng)字段也必須是 TIMESTAMP p.DbType DbType.DateTime2; p.Value dt; } return p; }p.Value value ?? DBNull.Value這一行看著簡單實(shí)際是新手最容易寫錯(cuò)的地方之一。直接給null在 SQL Server 上可能不報(bào)錯(cuò)但在 Oracle 托管驅(qū)動上會拋ArgumentNullException而且異常信息不指向具體參數(shù)名調(diào)試時(shí)只能一個(gè)個(gè)排除。SQLite 的類型映射更寬松NUMERIC存的是 double金額字段如果直接走decimal會有精度損失。Demo 里的做法是在寫入前把decimal轉(zhuǎn)成string存 TEXT讀取時(shí)再decimal.Parse犧牲一點(diǎn)查詢靈活性換取精度準(zhǔn)確。這個(gè)取舍在財(cái)務(wù)類字段上是必須的。3.3 事務(wù)與批量寫入單條插入通常不是瓶頸真正要處理的是批量。三套庫的批量方式完全不同Demo 里用同一個(gè)入口方法封裝public int InsertOrders(IDbProvider provider, string connStr, IReadOnlyListOrderRow rows) { if (rows.Count 0) return 0; using var conn provider.CreateConnection(connStr); conn.Open(); // 顯式事務(wù)SQLite 如果不包事務(wù)每條 insert 都會 fsync 一次速度差幾十倍 using var tx conn.BeginTransaction(); try { using var cmd conn.CreateCommand(); cmd.Transaction tx; cmd.CommandText provider.Translate( INSERT INTO T_ORDER (ORDER_NO, AMOUNT, CREATED_AT) VALUES ({no}, {amount}, {created})); // 參數(shù)只創(chuàng)建一次循環(huán)里改 Value這是批量插入的標(biāo)準(zhǔn)寫法 var pNo provider.CreateParameter(no, null); var pAmount provider.CreateParameter(amount, null); var pCreated provider.CreateParameter(created, null); cmd.Parameters.Add(pNo); cmd.Parameters.Add(pAmount); cmd.Parameters.Add(pCreated); foreach (var row in rows) { pNo.Value row.OrderNo; pAmount.Value row.Amount; pCreated.Value row.CreatedAt; cmd.ExecuteNonQuery(); } tx.Commit(); return rows.Count; } catch { // 不吞異?；貪L后原樣拋出讓上層決定重試還是記日志 tx.Rollback(); throw; } }參數(shù)對象在循環(huán)外創(chuàng)建、循環(huán)內(nèi)改Value這是 ADO.NET 的標(biāo)準(zhǔn)復(fù)用方式。如果在循環(huán)里cmd.Parameters.Clear()再重新Add每次都會觸發(fā)一次參數(shù)解析實(shí)測在十萬條量級上能差出三四倍時(shí)間。行數(shù)上到十萬級以上逐條ExecuteNonQuery就不夠看了。SQL Server 用SqlBulkCopyOracle 用ArrayBindingcmd.ArrayBindCountSQLite 只能靠事務(wù)包裹加PRAGMA synchronousOFF提速。Demo 里預(yù)留了IBulkInserter接口但沒全部實(shí)現(xiàn)改的時(shí)候按目標(biāo)庫補(bǔ)上就行。分批次提交也是常見做法每 5000 條Commit一次再開新事務(wù)避免一個(gè)超大事務(wù)把回滾段撐爆。Oracle 對這個(gè)特別敏感一個(gè)幾十萬行的事務(wù)很容易把 UNDO 表空間寫滿。3.4 分頁與自增主鍵的方言處理分頁語法三套庫各寫各的而且同一套庫的不同版本還不一樣public string BuildPagingSql(string baseSql, string orderBy, int skip, int take) { return Kind switch { // SQL Server 2012 支持 OFFSET/FETCH必須帶 ORDER BY DatabaseKind.SqlServer ${baseSql} ORDER BY {orderBy} OFFSET {skip} ROWS FETCH NEXT {take} ROWS ONLY, // Oracle 12c 才有 OFFSET/FETCH之前的版本要套兩層 ROWNUM DatabaseKind.Oracle $SELECT * FROM (SELECT a.*, ROWNUM rn FROM ({baseSql} ORDER BY {orderBy}) a $WHERE ROWNUM {skip take}) WHERE rn {skip}, // SQLite 最直接LIMIT 在前 OFFSET 在后 DatabaseKind.Sqlite ${baseSql} ORDER BY {orderBy} LIMIT {take} OFFSET {skip}, _ throw new NotSupportedException(Kind.ToString()) }; }這里把skip和take直接拼進(jìn) SQL 而不是走參數(shù)是因?yàn)?Oracle 的 ROWNUM 分頁在外層還要再包一層參數(shù)位置不好統(tǒng)一。安全上沒問題因?yàn)檫@兩個(gè)值來自代碼內(nèi)部的int不來自用戶輸入——但如果哪天有人把它們改成從請求里取必須加校驗(yàn)。自增主鍵的獲取方式差異更大。SQL Server 用SCOPE_IDENTITY()Oracle 12c 之前要靠序列加RETURNING INTOOracle 12c 之后可以用GENERATED BY DEFAULT AS IDENTITYSQLite 用last_insert_rowid()而且必須在同一個(gè)連接上調(diào)用// SQL Server cmd.CommandText INSERT INTO T_ORDER (...) VALUES (...); SELECT CAST(SCOPE_IDENTITY() AS BIGINT);; var id Convert.ToInt64(cmd.ExecuteScalar()); // SQLite必須在同一連接、同一事務(wù)內(nèi) cmd.CommandText INSERT INTO T_ORDER (...) VALUES (...); SELECT last_insert_rowid();; var id Convert.ToInt64(cmd.ExecuteScalar()); // Oracle 12c cmd.CommandText INSERT INTO T_ORDER (...) VALUES (...) RETURNING ID INTO :newId; var outParam new OracleParameter(newId, OracleDbType.Decimal, ParameterDirection.Output); cmd.Parameters.Add(outParam); cmd.ExecuteNonQuery(); var id Convert.ToInt64(outParam.Value.ToString());Oracle 那段用了輸出參數(shù)返回的是decimal轉(zhuǎn)long時(shí)要注意別直接強(qiáng)轉(zhuǎn)。last_insert_rowid()是連接級別的如果用連接池拿到的是另一個(gè)連接返回的會是 0 或者別的表的 ID這個(gè)坑在并發(fā)場景下很難復(fù)現(xiàn)。4. 跑起來三套環(huán)境從零連通看完代碼就該動手了。建議的順序是先 SQLite 后 SQL Server 最后 Oracle——SQLite 零配置能最快驗(yàn)證抽象層和 SQL 翻譯邏輯是否正常SQL Server 本地實(shí)例好搞Oracle 最麻煩放在最后前面跑通了心里有底。4.1 第一步用 SQLite 把鏈路跑通SQLite 不需要裝任何服務(wù)端一個(gè)文件就是一個(gè)庫。先確認(rèn) .NET SDK 版本然后還原依賴# 查看 SDK 版本Demo 用的是 .NET 8最低要求 6.0 dotnet --list-sdks # 還原所有項(xiàng)目依賴 dotnet restore DataDemo.sln # 編譯先確保沒有引用錯(cuò)誤 dotnet build DataDemo.sln -c Debug建庫直接執(zhí)行腳本用sqlite3命令行或者任意可視化工具都行# 創(chuàng)建庫文件并導(dǎo)入建表腳本 sqlite3 ./data/demo.db ./sql/sqlite/01_schema.sql # 驗(yàn)證表和字段 sqlite3 ./data/demo.db .schema T_ORDER配置文件里把Kind改成SqliteConnectionString指向剛生成的庫文件。注意相對路徑的基準(zhǔn)是進(jìn)程工作目錄dotnet run的時(shí)候是項(xiàng)目目錄發(fā)布之后是 exe 所在目錄兩邊不一致會導(dǎo)致「本地能跑、發(fā)布后找不到庫」。穩(wěn)妥的寫法是用AppContext.BaseDirectory拼絕對路徑var dbPath Path.Combine(AppContext.BaseDirectory, data, demo.db); var connStr $Data Source{dbPath};跑起來之后控制臺會依次輸出插入條數(shù)、分頁查詢結(jié)果、事務(wù)回滾驗(yàn)證。三個(gè)用例都通過說明抽象層和 SQLite Provider 是通的。4.2 SQL Server本地實(shí)例與容器二選一本機(jī)已經(jīng)裝了 SQL Server Express 或者 LocalDB 的直接改連接串就行Serverlocalhost\SQLEXPRESS;DatabaseDataDemo;Trusted_ConnectionTrue;TrustServerCertificateTrue;TrustServerCertificateTrue在新版驅(qū)動里幾乎是必加項(xiàng)。Microsoft.Data.SqlClient4.0 之后默認(rèn)EncryptTrue本地實(shí)例用的是自簽證書不加這個(gè)參數(shù)會直接報(bào)證書鏈錯(cuò)誤錯(cuò)誤碼還比較繞第一次遇到容易懵。沒有本地實(shí)例的用容器起一個(gè)最省事docker run -d --name demodbsql \ -e ACCEPT_EULAY \ -e MSSQL_SA_PASSWORDStr0ng!Passw0rd \ -p 1433:1433 \ mcr.microsoft.com/mssql/server:2022-latest起來之后用sqlcmd或者任意客戶端執(zhí)行sql/sqlserver/01_schema.sql。連接串換成Serverlocalhost,1433;DatabaseDataDemo;User Idsa;PasswordStr0ng!Passw0rd;TrustServerCertificateTrue;注意端口那里是逗號不是冒號這是 SQL Server 連接串的固定格式寫錯(cuò)了會一直超時(shí)。4.3 Oracle托管驅(qū)動省掉客戶端安裝用Oracle.ManagedDataAccess.Core的最大好處是不用裝 Instant Client省掉一堆ORA-12154之類的環(huán)境問題。有現(xiàn)成 Oracle 實(shí)例的連接串按 EZConnect 寫User Iddemo;Passworddemo123;Data Source192.168.1.10:1521/ORCLPDB1;Data Source最后那段是 service name不是 SID。這兩個(gè)搞混會報(bào)ORA-12505: TNS:listener does not currently know of SID given in connect descriptor看起來像網(wǎng)絡(luò)問題實(shí)際是名字寫錯(cuò)了。查 service name 可以連上去執(zhí)行-- 查當(dāng)前實(shí)例的 service name SELECT value FROM v$parameter WHERE name service_names;如果只有 SID 沒有 service name連接串要寫成完整描述符Data Source(DESCRIPTION(ADDRESS(PROTOCOLTCP)(HOST192.168.1.10)(PORT1521))(CONNECT_DATA(SIDORCL)));執(zhí)行建表腳本時(shí)Oracle 的IDENTITY列需要 12c 及以上版本。老版本要改成序列加觸發(fā)器CREATE SEQUENCE SEQ_T_ORDER START WITH 1 INCREMENT BY 1; CREATE OR REPLACE TRIGGER TRG_T_ORDER_ID BEFORE INSERT ON T_ORDER FOR EACH ROW WHEN (NEW.ID IS NULL) BEGIN SELECT SEQ_T_ORDER.NEXTVAL INTO :NEW.ID FROM DUAL; END;這種寫法在并發(fā)下有序列緩存丟失的問題但業(yè)務(wù)上一般不敏感。改的時(shí)候記得把 Provider 里獲取自增 ID 的邏輯一起換掉用RETURNING INTO配合序列的NEXTVAL。4.4 配置開關(guān)與運(yùn)行命令三種環(huán)境都準(zhǔn)備好之后靠配置文件切換不用改代碼{ Database: { Kind: Sqlite, ConnectionString: Data Source./data/demo.db, CommandTimeoutSeconds: 30, EnableSensitiveLogging: false } }啟動時(shí)按Kind走工廠# 用 SQLite 跑 dotnet run --project src/DataDemo.App -- --dbSqlite # 用 SQL Server 跑 dotnet run --project src/DataDemo.App -- --dbSqlServer # 用 Oracle 跑 dotnet run --project src/DataDemo.App -- --dbOracle三個(gè)都跑通再往下看踩坑章節(jié)因?yàn)橄旅媪械膯栴}基本都出現(xiàn)在「一套代碼三套庫」這種組合場景里單庫環(huán)境反而遇不到。5. 踩坑排查跨庫適配最容易翻車的五個(gè)地方這一章是血淚經(jīng)驗(yàn)匯總。多庫適配的坑有個(gè)共同特點(diǎn)單庫測試時(shí)完全正常切到另一套庫才暴露而且報(bào)錯(cuò)信息往往指向錯(cuò)誤的地方。下面五條按「現(xiàn)象 → 原因 → 解決」寫遇到對應(yīng)的現(xiàn)象直接對照。5.1 連接與字符集相關(guān)的坑現(xiàn)象一中文寫成問號讀出來是???。在 SQL Server 上一切正常切到 Oracle 或者 SQLite 就變問號。原因通常有兩層Oracle 那邊是客戶端字符集NLS_LANG和服務(wù)端字符集不一致托管驅(qū)動雖然不依賴NLS_LANG環(huán)境變量但數(shù)據(jù)庫本身的字符集如果是WE8ISO8859P1這類單字節(jié)集中文根本存不進(jìn)去SQLite 那邊則是列類型用了VARCHAR而不是TEXT雖然 SQLite 類型親和性會兜底但某些 ORM 會按聲明類型做轉(zhuǎn)換。解決方式Oracle 建庫時(shí)確認(rèn)字符集是AL32UTF8查詢用SELECT * FROM nls_database_parameters WHERE parameter NLS_CHARACTERSET;字段類型統(tǒng)一用NVARCHAR2。SQLite 的字符串列一律寫TEXT不要寫VARCHAR(n)長度限制在 SQLite 里本來也不生效?，F(xiàn)象二連接池耗盡報(bào)Timeout expired... The pool has reached its maximum size。本地開發(fā)不復(fù)現(xiàn)壓測或者上生產(chǎn)之后偶發(fā)。原因八成是某處DbConnection沒有Dispose異常分支里提前return了連接一直掛在池里不還。解決方式所有連接創(chuàng)建必須包在using里異常路徑也不例外。檢查時(shí)可以臨時(shí)把Max Pool Size調(diào)小到 5 再壓測問題會暴露得非?？臁racle 那邊還要注意DbDataReader也必須Dispose只關(guān)連接不關(guān) reader游標(biāo)數(shù)會一直漲。5.2 參數(shù)與類型映射相關(guān)的坑現(xiàn)象三ORA-01008: not all variables bound。SQL 里明明寫了三個(gè)參數(shù)也Add了三個(gè)Oracle 就是不認(rèn)。原因通常是參數(shù)名帶了冒號p.ParameterName :no或者 SQL 里的占位符和參數(shù)名大小寫不一致。Oracle 綁定按名字匹配帶前綴會匹配不上。解決方式ParameterName一定不帶前綴SQL 里的:no和參數(shù)名no嚴(yán)格對應(yīng)。翻譯層統(tǒng)一處理前綴別在業(yè)務(wù)代碼里手寫?，F(xiàn)象四時(shí)間字段讀出來少了毫秒或者差 8 小時(shí)。SQL Server 用DATETIME只精確到 3.33 毫秒Oracle 的DATE只到秒SQLite 存字符串的格式和時(shí)區(qū)更是完全靠自己控制?？鐜鞂r(shí)間做比較或者排序時(shí)結(jié)果會不一致。解決方式建表時(shí)統(tǒng)一用高精度類型SQL ServerDATETIME2(3)、OracleTIMESTAMP(3)、SQLite TEXT 存 ISO8601 帶時(shí)區(qū)偏移寫入前統(tǒng)一轉(zhuǎn) UTC讀出后由展示層轉(zhuǎn)本地時(shí)區(qū)。這一條定死之后跨庫的時(shí)間比較才可靠。5.3 并發(fā)與資源釋放相關(guān)的坑現(xiàn)象五SQLite 報(bào)database is locked。單線程跑沒問題一旦有并發(fā)寫入就偶發(fā)。原因是 SQLite 的寫鎖是庫級別的同一時(shí)刻只允許一個(gè)寫事務(wù)另一個(gè)連接寫入時(shí)會等待超過DefaultTimeout就拋異常。解決方式連接串里加DefaultTimeout30寫操作全部包在事務(wù)里減少持鎖時(shí)間讀多寫少的場景開啟 WAL 模式PRAGMA journal_modeWAL;讀寫可以并發(fā)。如果業(yè)務(wù)上寫并發(fā)確實(shí)高SQLite 就不是合適的選擇該換庫就換庫別硬扛。再補(bǔ)一條容易被忽略的事務(wù)里調(diào)用另一個(gè) Provider 的方法。比如在 SQL Server 的事務(wù)里順手調(diào)了一個(gè)走 SQLite 的日志方法兩個(gè)事務(wù)互不相干回滾的時(shí)候日志已經(jīng)寫進(jìn)去了數(shù)據(jù)對不上還查不出原因。跨庫操作要么走分布式事務(wù)成本高要么改成事務(wù)提交后再寫日志后者在實(shí)際項(xiàng)目里更常見。6. 二次開發(fā)把 Demo 改成能上生產(chǎn)的數(shù)據(jù)訪問層Demo 能跑通不等于能上生產(chǎn)中間差的那層?xùn)|西才是真正花時(shí)間的。這部分說的是改造思路不是讓你把 Demo 原樣搬進(jìn)項(xiàng)目里。6.1 抽出倉儲接口讓業(yè)務(wù)層不認(rèn)識 DbCommand最該做的第一件事是把IDbProvider再包一層。業(yè)務(wù)代碼里到處都是DbCommand、DbDataReader換庫的時(shí)候改起來很痛苦。加一層倉儲接口泛型約束到實(shí)體類型public interface IOrderRepository { Tasklong InsertAsync(OrderRow row, CancellationToken ct default); TaskOrderRow? GetByNoAsync(string orderNo, CancellationToken ct default); TaskPagedResultOrderRow QueryAsync(OrderQuery query, int page, int size, CancellationToken ct default); }實(shí)現(xiàn)類里用IDbProvider完成方言處理業(yè)務(wù)層只依賴接口。這樣即使將來要加第四種數(shù)據(jù)庫比如 PostgreSQL只需要新增一個(gè) Provider 和一個(gè)倉儲實(shí)現(xiàn)業(yè)務(wù)代碼一行不改。PagedResultT里放Items、Total、Page分頁總數(shù)的查詢單獨(dú)寫一條COUNT(*)別指望OFFSET/FETCH能順手帶回來。6.2 異步、取消與重試Demo 里的同步方法在生產(chǎn)環(huán)境基本不能用。改造時(shí)把ExecuteNonQuery換成ExecuteNonQueryAsyncDbDataReader換成ExecuteReaderAsync并且每個(gè)方法都帶上CancellationTokenpublic async Taskint InsertAsync(OrderRow row, CancellationToken ct default) { await using var conn _provider.CreateConnection(_connStr); await conn.OpenAsync(ct); await using var cmd conn.CreateCommand(); cmd.CommandText _provider.Translate( INSERT INTO T_ORDER (ORDER_NO, AMOUNT, CREATED_AT) VALUES ({no}, {amount}, {created})); cmd.Parameters.Add(_provider.CreateParameter(no, row.OrderNo)); cmd.Parameters.Add(_provider.CreateParameter(amount, row.Amount)); cmd.Parameters.Add(_provider.CreateParameter(created, row.CreatedAt)); // CommandTimeout 對異步方法同樣生效超時(shí)后取消令牌會觸發(fā) cmd.CommandTimeout _options.CommandTimeoutSeconds; return await cmd.ExecuteNonQueryAsync(ct); }這里注意await using而不是using連接和命令對象的異步釋放會等著底層資源真正歸還。CommandTimeout是秒級不設(shè)的話默認(rèn) 30 秒報(bào)表查詢很容易超時(shí)。重試策略要小心用。插入類操作重試必須靠唯一索引兜底否則網(wǎng)絡(luò)抖動時(shí)會插重復(fù)數(shù)據(jù)。查詢類操作可以放心重試。加一個(gè)輕量的策略操作類型是否重試重試次數(shù)備注單條查詢是2指數(shù)退避100ms 起批量插入否-改為冪等寫入靠唯一鍵去重連接獲取失敗是3池滿或網(wǎng)絡(luò)抖動間隔 500ms6.3 上線前的驗(yàn)證清單改造完之后別急著上按下面幾步走一遍能省掉很多回滾三個(gè) Provider 用同一套集成測試跑一遍測試用例里包含中文、emoji、null、超長字符串、邊界時(shí)間用Max Pool Size5壓測觀察連接數(shù)是否穩(wěn)定回落斷網(wǎng) 30 秒再恢復(fù)看重試邏輯是否按預(yù)期生效日志里能不能看出重試了幾次故意在事務(wù)中途拋異常確認(rèn)回滾干凈關(guān)聯(lián)表沒有殘留把 Oracle 的DATE字段改成TIMESTAMP之后重新跑一次全量測試這條最容易漏。最后說一句經(jīng)驗(yàn)之談跨庫適配這件事代碼本身不難難的是「一套代碼在三套庫上行為一致」。我現(xiàn)在的習(xí)慣是每加一個(gè)新 SQL先在三個(gè)庫上手工跑一遍確認(rèn)結(jié)果集、字段類型、錯(cuò)誤信息都符合預(yù)期再合進(jìn)主分支。那一次因?yàn)?Oracle 的DATE精度問題在凌晨三點(diǎn)排查數(shù)據(jù)的教訓(xùn)讓我從那以后每次改 SQL 都強(qiáng)制走一遍這個(gè)流程。這份 dataDemo 的價(jià)值不在代碼有多復(fù)雜而在于它把三套方言的差異擺在一張桌面上讓你改的時(shí)候知道該動哪里。倉庫里的sql/目錄和三個(gè) Provider 對照著看基本一下午就能把骨架摸清。希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取