.Net orm 開源項目 FreeSql 2.0.0(滿意的答卷)

寫在開頭

2018年11月頭腦發熱到今天,一晃已經兩年,當初從舒服區走向一個巨大的坑,回頭一看後背一涼。

兩年時間從無到有,經曆數不清的日夜奮鬥(有人問花了多長時間投入,答案:全職x2 + 兩年無休息)。

今天 FreeSql 已經很強大,感謝第一批、第二批、第N批持續提出建議的朋友,總算給社區交了一個滿意答卷。

v2.0.0 是一個穩定的版本,主要體現:

  • 用戶 API 已經確定,不會輕易推翻又作調整,堅持五年不變的原則,讓使用者真真正正的不再關心 ORM 使用問題;
  • 單元測試覆蓋面廣,5500+個單元測試,小版本更新升級無須考慮修東牆、補西牆的問題;
  • 經歷兩年時間的生產考驗,nuget下載量已超過25萬,平均每日350+;

感嘆:有些人說 .Net 陷入 orm 怪圈,動手的沒幾個,指點江山的一堆,.Net orm 真的如他們所講的簡單嗎?

項目簡介

溫馨提醒:以下內容無商吹成份,FreeSql 不打誑語

溫馨提醒:以下內容無商吹成份,FreeSql 不打誑語

溫馨提醒:以下內容無商吹成份,FreeSql 不打誑語

FreeSql 是 .Net ORM,能支援 .NetFramework4.0+、.NetCore、Xamarin、MAUI、Blazor、以及還有說不出來的運行平台,因為程式碼綠色無依賴,支援新平台非常簡單。目前單元測試數量:5400+,Nuget下載數量:260K+,源碼幾乎每天都有提交。值得高興的是 FreeSql 加入了 ncc 開源社區://github.com/dotnetcore/FreeSql,加入組織之後社區責任感更大,需要更努力做好品質,為開源社區出一份力。

QQ群:4336577(已滿)、8578575(在線)、52508226(在線)

為什麼要重複造輪子?

FreeSql 主要優勢在於易用性上,基本是開箱即用,在不同資料庫之間切換兼容性比較好。作者花了大量的時間精力在這個項目,肯請您花半小時了解下項目,謝謝。FreeSql 整體的功能特性如下:

  • 支援 CodeFirst 對比結構變化遷移;
  • 支援 DbFirst 從資料庫導入實體類;
  • 支援 豐富的表達式函數,自定義解析;
  • 支援 批量添加、批量更新、BulkCopy;
  • 支援 導航屬性,貪婪載入、延時載入、級聯保存;
  • 支援 讀寫分離、分表分庫,租戶設計;
  • 支援 MySql/SqlServer/PostgreSQL/Oracle/Sqlite/Firebird/達夢/神通/人大金倉/翰高/MsAccess Ado.net 實現包,以及 Odbc 的專門實現包;

5500+個單元測試作為基調,支援10多數資料庫,我們提供了通用Odbc理論上支援所有資料庫,目前已知有群友使用 FreeSql 操作華為高斯、mycat、tidb 等資料庫。

安裝時選擇對應的資料庫包:

dotnet add packages FreeSql.Provider.MySql

CodeFirst

FreeSql 使用 CodeFirst 模式開發,簡直不要再簡單,只需要如下定義:

static IFreeSql fsql = new FreeSql.FreeSqlBuilder()
    .UseConnectionString(FreeSql.DataType.MySql, @"Data Source=127.0.0.1;Port=3306;User ID=root;Password=root;Initial Catalog=cccddd_mysqlconnector;Charset=utf8;SslMode=none;Max pool size=10")
    .UseAutoSyncStructure(true) //自動同步實體結構到資料庫
    .UseMonitorCommand(cmd => Console.WriteLine(cmd.CommandText + "\r\n")) //列印 SQL
    .Build(); //請務必定義成 Singleton 單例模式

UseAutoSyncStructure(true) 這個設置開啟自動遷移功能,啥意思?如下實體類:

class Blog {
    [Column(IsIdentity = true, IsPrimary = true)]
    public int BlogId { get; set; }
    public string Url { get; set; }
    public int Rating { get; set; }
}

fsql 對 Blog 進行 CRUD 時,比如:

fsql.Select<Blog>().First();
fsql.Select<Blog>().First();

會執行 SQL 如下:

CREATE TABLE IF NOT EXISTS `cccddd_mysqlconnector`.`Blog` (  
  `BlogId` INT(11) AUTO_INCREMENT, 
  `Url` VARCHAR(255), 
  `Rating` INT(11) NOT NULL, 
  PRIMARY KEY (`BlogId`)
) Engine=InnoDB;

SELECT a.`BlogId`, a.`Url`, a.`Rating` 
FROM `Blog` a 
limit 0,1

SELECT a.`BlogId`, a.`Url`, a.`Rating` 
FROM `Blog` a 
limit 0,1

程式運行過程中,首次 CRUD 操作實體類會創建表,之後不再執行該操作。

這是表不存在的情況,如果表存在的時候會怎樣?會對比更新結構。FreeSql 對比表結構和實體類的差異部分,執行遷移盡量保證不丟數據(無法100%保證,請三思使用在生產環境)

除了自動遷移功能,我們還提供以幾個常用 API fsql.CodeFirst 方法:

方法 返回值 參數 說明
GetComparisonDDLStatements string Type 將實體類型與資料庫對比,返回DDL語句
SyncStructure bool Type 同步實體類型到資料庫
ConfigEntity ICodeFirst Action<TableFluent<T>> FluentAPI 配置實體的特性
GetTableByEntity TableInfo Type 獲取類型在ORM內部的元數據

實體特性

.NET ORM 幾乎都是通過實體與表進行映射,怎麼少得了靈活的特性設置呢。

提示:FreeSql 可以自動識別 EFCore 實體特性 Key/Required/NotMapped/MaxLength/StringLength/DatabaseGenerated/Table/Column

[Table(Name = "topic")]
class Topic {
    [Column(IsPrimary = true, IsIdentity = true, Name = "id")]
    public int Id { get; set; }
}

如上 Name 設置實體類與資料庫小寫映射,其實還提供統一處理的方法:

static IFreeSql fsql = new FreeSql.FreeSqlBuilder()
    //..
    UseNameConvert(NameConvertType.ToLower)
    //..
    .Build();

// PascalCaseToUnderscore: BigApple -> Big_Apple
// PascalCaseToUnderscoreWithUpper: BigApple -> BIG_APPLE
// PascalCaseToUnderscoreWithLower: BigApple -> big_apple
// ToUpper: BigApple -> BIGAPPLE
// ToLower: BigApple -> bigapple
// 感謝【曉晨】提供的這個思路和功能

CRUD

FreeSql CRUD 命名習慣遵從 SQL,程式碼寫起來就像寫 SQL 一樣,如下:

  • 插入數據:fsql.Insert(item).ExecuteAffrows();
  • 更新數據:fsql.Update<T>().Where(..).Set(..).ExecuteAffrows();
  • 刪除數據:fsql.Delete<T>().Where(..).ExecuteAffrows();
  • 查詢數據:fsql.Select<T>().Where(..).ToList();

Repository

FreeSql.Repository 作為擴展,實現了通用倉儲層功能。與其他規範標準一樣,倉儲層也有相應的規範定義。FreeSql.Repository 參考 abp vnext 介面,定義和實現基礎的倉儲層(CURD),應該算比較通用的方法吧。倉儲可以:

  • Select/Attach 快照對象,Update 只更新變化的欄位;
  • Insert 插入數據,適配各資料庫優化執行 ExecuteAffrows/ExecuteIdentity/ExecuteInserted;
  • InsertOrUpdate 插入或更新;
  • SaveMany 方法快速保存導航對象(一對多、多對多);
  • UnitOfWork 工作單元設置;

導航屬性

微軟製造了優秀的語言 c#,利用語言特性可以做一些非常好用的功能,在 ORM 中使用導航屬性非常適合。

  • FreeSql ManyToOne(N對1) 提供了簡單的多表 join 查詢;

  • FreeSql OneToMany(1對N) 提供了簡單可控的級聯查詢、級聯保存功能;

  • FreeSql ManyToMany(多對多) 提供了簡單的多對多過濾查詢、級聯查詢、級聯保存功能;

  • FreeSql 父子關係 提供了常用的 CTE查詢、刪除、遞歸功能;

關於導航屬性,我們寫了一篇專門介紹的文章,可跳轉查看:.NET ORM 導航屬性【到底】可以解決什麼問題?

分表分庫

關於分表分庫,我們寫了一篇專門介紹的文章,可跳轉查看:.NET ORM 分表分庫【到底】怎麼做?

事務

關於事務,我們寫了一篇專門介紹的文章,可跳轉查看:.NET 資料庫事務的各種玩法進化

寫在最後

FreeSql 2.0.0 他是免費自由的 ORM,也可以說是寶藏 ORM。更多文檔請前往 wiki 查看。

下一個五年,期待少年的你還能歸來在此貼回復,兌現五年不變的承諾。

多的不說了,希望民間的開源力時越來越強大。

希望作者的努力能打動到你,請求正在使用的、善良的您能動一動小手指,把文章轉發一下,讓更多人知道 .NET 有這樣一個好用的 ORM 存在。謝謝!!

FreeSql 使用最寬鬆的開源協議 MIT //github.com/dotnetcore/FreeSql,完全可以商用,文檔齊全。QQ群:4336577(已滿)、8578575(在線)、52508226(在線)