基於SqlSugar的開發框架的循序漸進介紹（1）–框架基礎類的設計和使用
在實際項目開發中，我們可能會碰到各種各樣的項目環境，有些項目需要一個大而全的整體框架來支撐開發，有些中小項目這需要一些簡單便捷的系統框架靈活開發。目前大型一點的框架，可以採用ABP或者ABP VNext的框架，兩者整體思路和基礎設計類似，不過ABP側重於一個獨立完整的項目框架，開發的時候統一整合處理；而ABP VNext則是以微服務架構為基礎，各個模組獨立開發，既可以整合在一個項目中，也可以以微服務進行單獨發布，並統一通過網關處理進行交流。不管ABP或者ABP VNext框架，都集合了.NET CORE領域眾多技術為一體，並且基礎類設計上，錯綜複雜，關係較多，因此開發學習有一定的門檻，中小型項目應用起來有一定的費勁之處。本系列隨筆介紹底層利用SqlSugar來做ORM數據訪問模組，設計一個簡單便捷一點的框架，本篇從基礎開始介紹一些框架內容，參照一些ABP/ABP VNext中的一些類庫處理，來承載類似條件分頁資訊，查詢條件處理等處理細節。
1、基於SqlSugar開發框架的架構設計
主要的設計模組場景如下所示。
為了避免像ABP VNext框架那樣分散幾十個項目，我們儘可能聚合內容放在一個項目裡面。
1）其中一些常用的類庫，以及SqlSugar框架的基類放在框架公用模組裡面。
2）Winform開發相關的基礎介面以及通用組件內容，放在基礎Winform介面庫BaseUIDx項目中。
3）基礎核心數據模組SugarProjectCore，主要就是開發業務所需的數據處理和業務邏輯的項目，為了方便，我們區分Interface、Modal、Service三個目錄來放置不同的內容，其中Modal是SqlSugar的映射實體，Interface是定義訪問介面，Service是提供具體的數據操作實現。其中Service裡面一些框架基類和介面定義，統一也放在公用類庫裡面。
4）Winform應用模組，主要就是針對業務開發的WInform介面應用，而WInform開發為了方便，也會將一些基礎組件和基類放在了BaseUIDx的Winform專用的介面庫裡面。
5）WebAPI項目採用基於.net Core6的項目開發，通過調用SugarProjectCore實現相關控制器API的發布，並整合Swagger發布介面，供其他前端介面應用進行調用。
6）純前端通過API進行調用Web API的介面，純前端模組可以包含Vue3&Element項目，以及基於EelectronJS應用，發布跨平台的基於瀏覽器的應用介面，以及其他App或者小程式整合Web API進行業務數據的處理或者展示需要。
如後端開發，我們可以在VS2022中進行管理，管理開發Winform項目、Web API項目等。
Winform介面，我們可以採用基於.net Framework開發或者.net core6進行開發均可，因為我們的SugarProjectCore項目是採用.net Standard模式開發，兼容兩者。這裡以許可權模組來進行演示整合使用。
而純前端的項目，我們可以基於VSCode或者 HBuilderX等工具進行項目的管理開發工作。
2、框架基礎類的定義和處理
在開發一個易於使用的框架的時候，主要目的就是減少程式碼開發，並儘可能通過基類和泛型約束的方式，提高介面的通用性，並通過結合程式碼生成工具的方式，來提高標準項目的開發效率。
那麼我們這裡基於SqlSugar的ORM處理，來實現常規數據的增刪改查等常規操作的時候，我們是如何進行這些介面的封裝處理的呢。
例如，我們對於一個簡單的客戶資訊表，如下所示。
那麼它生成的SqlSugar實體類如下所示。
/// <summary> /// 客戶資訊 /// 繼承自Entity，擁有Id主鍵屬性 /// </summary> [SugarTable("T_Customer")] public class CustomerInfo : Entity<string> { /// <summary> /// 默認構造函數（需要初始化屬性的在此處理） /// </summary> public CustomerInfo() { this.CreateTime = System.DateTime.Now; } #region Property Members /// <summary> /// 姓名 /// </summary> public virtual string Name { get; set; } /// <summary> /// 年齡 /// </summary> public virtual int Age { get; set; } /// <summary> /// 創建人 /// </summary> public virtual string Creator { get; set; } /// <summary> /// 創建時間 /// </summary> public virtual DateTime CreateTime { get; set; } #endregion }
其中 Entity<string> 是我們根據需要定義一個基類實體對象，主要就是定義一個Id的屬性來處理，畢竟對於一般表對象的處理，SqlSugar需要Id的主鍵定義（非中間表處理）。
[Serializable] public abstract class Entity<TPrimaryKey> : IEntity<TPrimaryKey> { /// <summary> /// 實體類唯一主鍵 /// </summary> [SqlSugar.SugarColumn(IsPrimaryKey = true, ColumnDescription = "主鍵")] public virtual TPrimaryKey Id { get; set; } }
而IEntity<T>定義了一個介面
public interface IEntity<TPrimaryKey> { /// <summary> /// 實體類唯一主鍵 /// </summary> TPrimaryKey Id { get; set; } }
以上就是實體類的處理，我們一般為了查詢資訊，往往通過一些條件傳入進行處理，那麼我們就需要定義一個通用的分頁查詢對象，供我們精準進行條件的處理。
生成一個以***PageDto的對象類，如下所示。
/// <summary> /// 用於根據條件分頁查詢，DTO對象 /// </summary> public class CustomerPagedDto : PagedAndSortedInputDto, IPagedAndSortedResultRequest { /// <summary> /// 默認構造函數 /// </summary> public CustomerPagedDto() : base() { } /// <summary> /// 參數化構造函數 /// </summary> /// <param name="skipCount">跳過的數量</param> /// <param name="resultCount">最大結果集數量</param> public CustomerPagedDto(int skipCount, int resultCount) : base(skipCount, resultCount) { } /// <summary> /// 使用分頁資訊進行初始化SkipCount 和 MaxResultCount /// </summary> /// <param name="pagerInfo">分頁資訊</param> public CustomerPagedDto(PagerInfo pagerInfo) : base(pagerInfo) { } #region Property Members /// <summary> /// 不包含的對象的ID,用於在查詢的時候排除對應記錄 /// </summary> public virtual string ExcludeId { get; set; } /// <summary> /// 姓名 /// </summary> public virtual string Name { get; set; } /// <summary> /// 年齡-開始 /// </summary> public virtual int? AgeStart { get; set; } /// <summary> /// 年齡-結束 /// </summary> public virtual int? AgeEnd { get; set; } /// <summary> /// 創建時間-開始 /// </summary> public DateTime? CreateTimeStart { get; set; } /// <summary> /// 創建時間-結束 /// </summary> public DateTime? CreateTimeEnd { get; set; } #endregion }
其中PagedAndSortedInputDto, IPagedAndSortedResultRequest都是參考來自於ABP/ABP VNext的處理方式，這樣我們可以便於數據訪問基類的查詢處理操作。
接著我們定義一個基類MyCrudService，並傳遞如相關的泛型約束，如下所示
/// <summary> /// 基於SqlSugar的資料庫訪問操作的基類對象 /// </summary> /// <typeparam name="TEntity">定義映射的實體類</typeparam> /// <typeparam name="TKey">主鍵的類型，如int，string等</typeparam> /// <typeparam name="TGetListInput">或者分頁資訊的條件對象</typeparam> public abstract class MyCrudService<TEntity, TKey, TGetListInput> : IMyCrudService<TEntity, TKey, TGetListInput> where TEntity : class, IEntity<TKey>, new() where TGetListInput : IPagedAndSortedResultRequest
我們先忽略基類介面的相關實現細節，我們看看對於這個MyCrudService和 IMyCrudService 我們應該如何使用的。
首先我們定義一個應用層的介面ICustomerService如下所示。
/// <summary> /// 客戶資訊服務介面 /// </summary> public interface ICustomerService : IMyCrudService<CustomerInfo, string, CustomerPagedDto>, ITransientDependency { }
然後實現在CustomerService中實現它的介面。
/// <summary> /// 應用層服務介面實現 /// </summary> public class CustomerService : MyCrudService<CustomerInfo, string, CustomerPagedDto>, ICustomerService
這樣我們對於特定Customer的介面在ICustomer中定義，標準介面直接調用基類即可。
基類MyCrudService提供重要的兩個介面，讓子類進行重寫，以便於進行準確的條件處理和排序處理，如下程式碼所示。
/// <summary> /// 基於SqlSugar的資料庫訪問操作的基類對象 /// </summary> /// <typeparam name="TEntity">定義映射的實體類</typeparam> /// <typeparam name="TKey">主鍵的類型，如int，string等</typeparam> /// <typeparam name="TGetListInput">或者分頁資訊的條件對象</typeparam> public abstract class MyCrudService<TEntity, TKey, TGetListInput> : IMyCrudService<TEntity, TKey, TGetListInput> where TEntity : class, IEntity<TKey>, new() where TGetListInput : IPagedAndSortedResultRequest { /// <summary> /// 留給子類實現過濾條件的處理 /// </summary> /// <returns></returns> protected virtual ISugarQueryable<TEntity> CreateFilteredQueryAsync(TGetListInput input) { return EntityDb.AsQueryable(); } /// <summary> /// 默認排序，通過ID進行排序 /// </summary> /// <param name="query"></param> /// <returns></returns> protected virtual ISugarQueryable<TEntity> ApplyDefaultSorting(ISugarQueryable<TEntity> query) { if (typeof(TEntity).IsAssignableTo<IEntity<TKey>>()) { return query.OrderBy(e => e.Id); } else { return query.OrderBy("Id"); } } }
對於Customer特定的業務對象來說，我們需要實現具體的條件查詢細節和排序條件，畢竟我們父類沒有約束確定實體類有哪些屬性的情況下，這些就交給子類做最合適了。
/// <summary> /// 應用層服務介面實現 /// </summary> public class CustomerService : MyCrudService<CustomerInfo, string, CustomerPagedDto>, ICustomerService { /// <summary> /// 自定義條件處理 /// </summary> /// <param name="input">查詢條件Dto</param> /// <returns></returns> protected override ISugarQueryable<CustomerInfo> CreateFilteredQueryAsync(CustomerPagedDto input) { var query = base.CreateFilteredQueryAsync(input); query = query .WhereIF(!input.ExcludeId.IsNullOrWhiteSpace(), t => t.Id != input.ExcludeId) //不包含排除ID .WhereIF(!input.Name.IsNullOrWhiteSpace(), t => t.Name.Contains(input.Name)) //如需要精確匹配則用Equals //年齡區間查詢 .WhereIF(input.AgeStart.HasValue, s => s.Age >= input.AgeStart.Value) .WhereIF(input.AgeEnd.HasValue, s => s.Age <= input.AgeEnd.Value) //創建日期區間查詢 .WhereIF(input.CreateTimeStart.HasValue, s => s.CreateTime >= input.CreateTimeStart.Value) .WhereIF(input.CreateTimeEnd.HasValue, s => s.CreateTime <= input.CreateTimeEnd.Value) ; return query; } /// <summary> /// 自定義排序處理 /// </summary> /// <param name="query">可查詢LINQ</param> /// <returns></returns> protected override ISugarQueryable<CustomerInfo> ApplyDefaultSorting(ISugarQueryable<CustomerInfo> query) { return query.OrderBy(t => t.CreateTime, OrderByType.Desc); //先按第一個欄位排序，然後再按第二欄位排序 //return base.ApplySorting(query, input).OrderBy(s=>s.Customer_ID).OrderBy(s => s.Seq); } }
通過 CreateFilteredQueryAsync 的精確條件處理，我們就可以明確實體類的查詢條件處理，因此對於CustomerPagedDto來說，就是可以有客戶端傳入，服務後端的基類進行處理了。
如基類的分頁條件查詢函數GetListAsync就是根據這個來處理的，它的實現程式碼如下所示。
/// <summary> /// 根據條件獲取列表 /// </summary> /// <param name="input">分頁查詢條件</param> /// <returns></returns> public virtual async Task<PagedResultDto<TEntity>> GetListAsync(TGetListInput input) { var query = CreateFilteredQueryAsync(input); var totalCount = await query.CountAsync(); query = ApplySorting(query, input); query = ApplyPaging(query, input); var list = await query.ToListAsync(); return new PagedResultDto<TEntity>( totalCount, list ); }
而其中 ApplySorting 就是根據條件決定是否選擇子類實現的默認排序進行處理的。
/// <summary> /// 記錄排序處理 /// </summary> /// <returns></returns> protected virtual ISugarQueryable<TEntity> ApplySorting(ISugarQueryable<TEntity> query, TGetListInput input) { //Try to sort query if available if (input is ISortedResultRequest sortInput) { if (!sortInput.Sorting.IsNullOrWhiteSpace()) { return query.OrderBy(sortInput.Sorting); } } //IQueryable.Task requires sorting, so we should sort if Take will be used. if (input is ILimitedResultRequest) { return ApplyDefaultSorting(query); } //No sorting return query; }
對於獲取單一對象，我們一般提供一個ID主鍵獲取即可。
/// <summary> /// 根據ID獲取單一對象 /// </summary> /// <param name="id">主鍵ID</param> /// <returns></returns> public virtual async Task<TEntity> GetAsync(TKey id) { return await EntityDb.GetByIdAsync(id); }
也可以根據用戶的Express條件進行處理，在基類我們定義很多這樣的Express條件處理，便於子類進行條件處理的調用。如對於刪除，可以指定ID，也可以指定條件刪除。
/// <summary> /// 刪除指定ID的對象 /// </summary> /// <param name="id">記錄ID</param> /// <returns></returns> public virtual async Task<bool> DeleteAsync(TKey id) { return await EntityDb.DeleteByIdAsync(id); }
/// <summary> /// 根據指定條件，刪除集合 /// </summary> /// <param name="input">表達式條件</param> /// <returns></returns> public virtual async Task<bool> DeleteAsync(Expression<Func<TEntity, bool>> input) { var result = await EntityDb.DeleteAsync(input); return result; }
如判斷是否存在也是一樣處理
/// <summary> /// 判斷是否存在指定條件的記錄 /// </summary> /// <param name="id">ID 主鍵</param> /// <returns></returns> public virtual async Task<bool> IsExistAsync(TKey id) { var info = await EntityDb.GetByIdAsync(id); var result = (info != null); return result; } /// <summary> /// 判斷是否存在指定條件的記錄 /// </summary> /// <param name="input">表達式條件</param> /// <returns></returns> public virtual async Task<bool> IsExistAsync(Expression<Func<TEntity, bool>> input) { var result = await EntityDb.IsAnyAsync(input); return result; }
關於Web API的處理，我在隨筆《基於SqlSugar的資料庫訪問處理的封裝，在.net6框架的Web API上開發應用》中也有介紹，主要就是先弄好.net6的開發環境，然後在進行相關的項目開發即可。
根據項目的需要，我們定義了一些控制器的基類，用於實現不同的功能。
其中ControllerBase是.net core Web API中的標準控制器基類，我們由此派生一個LoginController用於登錄授權，而BaseApiController則處理常規介面用戶身份資訊，而BusinessController則是對標準的增刪改查等基礎介面進行的封裝，我們實際開發的時候，只需要開發編寫類似CustomerController基類即可。
BaseApiController沒有什麼好介紹的，就是封裝一下獲取用戶的身份資訊。
可以通過下面程式碼獲取介面用戶的Id
/// <summary> /// 當前用戶身份ID /// </summary> protected virtual string? CurrentUserId => HttpContext.User.FindFirst(JwtClaimTypes.Id)?.Value;
而BusinessController控制器則是繼承這個BaseApiController即可。通過泛型約束傳入相關的對象資訊。
/// <summary> /// 本控制器基類專門為訪問數據業務對象而設的基類 /// </summary> /// <typeparam name="TEntity">定義映射的實體類</typeparam> /// <typeparam name="TKey">主鍵的類型，如int，string等</typeparam> /// <typeparam name="TGetListInput">或者分頁資訊的條件對象</typeparam> [Route("[controller]")] [Authorize] //需要授權登錄訪問 public class BusinessController<TEntity, TKey, TGetListInput> : BaseApiController where TEntity : class, IEntity<TKey>, new() where TGetListInput : IPagedAndSortedResultRequest { /// <summary> /// 通用基礎操作介面 /// </summary> protected IMyCrudService<TEntity, TKey, TGetListInput> _service { get; set; } /// <summary> /// 構造函數，初始化基礎介面 /// </summary> /// <param name="service">通用基礎操作介面</param> public BusinessController(IMyCrudService<TEntity, TKey, TGetListInput> service) { this._service = service; } ....
這個基類接收一個符合基類介面定義的對象作為基類增刪刪改查等處理方法的介面對象。在具體的CustomerController中的定義處理如下所示。
/// <summary> /// 客戶資訊的控制器對象 /// </summary> public class CustomerController : BusinessController<CustomerInfo, string, CustomerPagedDto> { private ICustomerService _customerService; /// <summary> /// 構造函數，並注入基礎介面對象 /// </summary> /// <param name="customerService"></param> public CustomerController(ICustomerService customerService) :base(customerService) { this._customerService = customerService; } }
這樣就可以實現基礎的相關操作了。如果需要特殊的介面實現，那麼定義方法實現即可。
類似字典項目中的控制器處理程式碼如下所示。定義好HTTP方法，路由資訊等即可。
/// <summary> /// 根據字典類型ID獲取所有該類型的字典列表集合(Key為名稱，Value為值） /// </summary> /// <param name="dictTypeId">字典類型ID</param> /// <returns></returns> [HttpGet] [Route("by-typeid/{dictTypeId}")] public async Task<Dictionary<string, string>> GetDictByTypeID(string dictTypeId) { return await _dictDataService.GetDictByTypeID(dictTypeId); } /// <summary> /// 根據字典類型名稱獲取所有該類型的字典列表集合(Key為名稱，Value為值） /// </summary> /// <param name="dictTypeName">字典類型名稱</param> /// <returns></returns> [HttpGet] [Route("by-typename/{dictTypeName}")] public async Task<Dictionary<string, string>> GetDictByDictType(string dictTypeName) { return await _dictDataService.GetDictByDictType(dictTypeName); }
