[開源]OSharpNS 步步為營系列 - 2. 新增業務資料層
什麼是OSharp
OSharpNS全稱OSharp Framework with .NetStandard2.0,是一個基於.NetStandard2.0
開發的一個.NetCore
快速開發框架。這個框架使用最新穩定版的.NetCore SDK
(當前是.NET Core 2.2),對 AspNetCore 的配置、依賴注入、日誌、快取、實體框架、Mvc(WebApi)、身份認證、許可權授權等模組進行更高一級的自動化封裝,並規範了一套業務實現的程式碼結構與操作流程,使 .Net Core 框架更易於應用到實際專案開發中。
- 開源地址:https://github.com/i66soft/osharp
- 官方示例:https://www.osharp.org
- 文件中心:https://docs.osharp.org
- VS 外掛:https://marketplace.visualstudio.com/items?itemName=LiuliuSoft.osharp
概述
一個模組的資料層,主要包括如下幾個方面:
- 資料實體:資料實體是服務層向資料庫進行資料持久化的資料載體,也是資料層進行業務處理的資料載體,資料層與資料層的資料交換都應通過實體類來完成。
- 輸入DTO:InputDto用於前端向API層輸入資料,API層向服務層輸入資料
輸出DTO:OutputDto主要用於資料查詢服務,是API層向前端輸出資料的載體
資料實體對映配置:CodeFirst的開發模式,資料庫的設計細節完全靠程式碼來完成,資料實體對映配置正是負責這項工作的,針對一個實體,可以在這裡配置其在資料庫中的資料表關係、資料約束及各個資料欄位的每一個細節配置。
資料層資料夾佈局
src # 原始碼資料夾 ├─Liuliu.Blogs.Core # 專案核心工程 │ └─Blogs # 部落格模組資料夾 │ ├─Dtos # 部落格模組DTO資料夾 │ │ ├─BlogInputDto.cs # 部落格輸入DTO │ │ ├─BlogOutputDto.cs # 部落格輸出DTO │ │ ├─PostInputDto.cs # 文章輸入DTO │ │ └─PostOutputDto.cs # 文章輸出DTO │ └─Entities # 部落格模組實體類資料夾 │ ├─Blog.cs # 部落格實體類 │ └─Post.cs # 文章實體類 └─Liuliu.Blogs.EntityConfiguration # 實體對映配置工程 └─Blogs # 部落格模組資料夾 ├─BlogConfiguration.cs # 部落格實體對映配置類 └─PostConfiguration.cs # 文章實體對映配置類
實體類
必選介面
IEntity
資料實體介面:所有的實體類都必須實現 IEntity
介面,此介面給實體類新增一個 名為 Id
的實體唯一編號屬性,這個屬性是實體類的 主鍵 屬性
/// <summary>
/// 資料模型介面
/// </summary>
/// <typeparam name="TKey">實體主鍵型別</typeparam>
public interface IEntity<out TKey>
{
/// <summary>
/// 獲取 實體唯一標識,主鍵
/// </summary>
TKey Id { get; }
}
EntityBase
實體類基類:為了方便實體類快速實現 IEntity
介面,定義了一個通用基類 EntityBase
,所有實體都可以通過繼承此基類方便實現 IEntity
介面
/// <summary>
/// 實體類基類
/// </summary>
public abstract class EntityBase<TKey> : IEntity<TKey> where TKey : IEquatable<TKey>
{
/// <summary>
/// 初始化一個<see cref="EntityBase{TKey}"/>型別的新例項
/// </summary>
protected EntityBase()
{
if (typeof(TKey) == typeof(Guid))
{
Id = CombGuid.NewGuid().CastTo<TKey>();
}
}
/// <summary>
/// 獲取或設定 編號
/// </summary>
[DisplayName("編號")]
public TKey Id { get; set; }
// ...
}
可選的裝配功能介面與特性
OSharp框架給實體類設計了一些可裝配的功能,通過特定的介面來提供,實體類實現了特定的介面,則實體類在系統中將自動擁有一些額外的功能。
ICreatedTime
定義建立時間:ICreatedTime
介面給實體類新增一個 建立時間CreatedTime
的屬性,該屬性將在資料層執行 建立Insert
操作時,自動賦予系統當前時間。
/// <summary>
/// 定義建立時間
/// </summary>
public interface ICreatedTime
{
/// <summary>
/// 獲取或設定 建立時間
/// </summary>
DateTime CreatedTime { get; set; }
}
ILockable
定義可鎖定功能:ILockable
介面給實體類新增一個 是否鎖定IsLocked
的屬性
/// <summary>
/// 定義可鎖定功能
/// </summary>
public interface ILockable
{
/// <summary>
/// 獲取或設定 是否鎖定當前資訊
/// </summary>
bool IsLocked { get; set; }
}
IEntityHash
定義實體Hash功能:給實體新增 GetHash
擴充套件方法,用於對實體的屬性值進行Hash,確定實體是否存在變化,這些變化可用於系統初始化時確定是否需要進行資料同步。
當前系統中 實體資訊EntityInfo
, 功能點Function
, API模組Module
在系統啟動時與資料庫中的相應資料進行對比同步時,使用的就是這個介面的特性
/// <summary>
/// 定義實體Hash功能,對實體的屬性值進行Hash,確定實體是否存在變化,
/// 這些變化可用於系統初始化時確定是否需要進行資料同步
/// </summary>
public interface IEntityHash
{ }
IExpirable
定義可過期性,包含生效時間和過期時間:給實體新增 生效時間BeginTime
,過期時間EndTime
的屬性
/// <summary>
/// 定義可過期性,包含生效時間和過期時間
/// </summary>
public interface IExpirable
{
/// <summary>
/// 獲取或設定 生效時間
/// </summary>
DateTime? BeginTime { get; set; }
/// <summary>
/// 獲取或設定 過期時間
/// </summary>
DateTime? EndTime { get; set; }
}
ICreationAudited
定義建立審計資訊:給實體新增建立時的 建立人CreatorId
,建立時間CreatedTime
的審計資訊,這些值將在資料層執行 建立Insert
時自動賦值。
/// <summary>
/// 定義建立審計資訊
/// </summary>
public interface ICreationAudited<TUserKey> : ICreatedTime
where TUserKey : struct
{
/// <summary>
/// 獲取或設定 建立者編號
/// </summary>
TUserKey? CreatorId { get; set; }
}
ICreationAudited
已繼承了ICreatedTime
介面,不會重複新增CreatedTime
屬性
IUpdateAudited
定義更新審計的資訊:給實體新增更新時的 最後更新人LastUpdaterId
,最後更新時間LastUpdatedTime
的審計資訊,這些值將在資料層執行 更新Update
操作時自動賦值。
/// <summary>
/// 定義更新審計的資訊
/// </summary>
public interface IUpdateAudited<TUserKey> where TUserKey : struct
{
/// <summary>
/// 獲取或設定 更新者編號
/// </summary>
TUserKey? LastUpdaterId { get; set; }
/// <summary>
/// 獲取或設定 最後更新時間
/// </summary>
DateTime? LastUpdatedTime { get; set; }
}
ISoftDeletable
定義邏輯刪除功能:給實體新增一個用於邏輯刪除的 刪除時間DeletedTime
屬性,當實體實現了 ISoftDeletable
介面之後,資料層執行 刪除 Delete
操作時,將 DeletedTime
賦予當前時間,即表示資料已被刪除。資料查詢的時候通過全域性過濾器自動過濾掉 DeletedTime
不為 null 的資料,從而查詢出正常資料。
/// <summary>
/// 定義邏輯刪除功能
/// </summary>
public interface ISoftDeletable
{
/// <summary>
/// 獲取或設定 資料邏輯刪除時間,為null表示正常資料,有值表示已邏輯刪除,同時刪除時間每次不同也能保證索引唯一性
/// </summary>
DateTime? DeletedTime { get; set; }
}
UserFlagAttribute
使用者標記特性:此特性與資料許可權有關,用於實體類的 使用者編號UserId
屬性,用於標記實體類中與使用者私有資料相關聯的使用者編號,以在資料許可權判斷時,將實體的使用者編號與當前線上使用者的使用者編號進行對比,找出使用者的私有資料。
/// <summary>
/// 使用者標記,用於標示使用者屬性/欄位
/// </summary>
[AttributeUsage(AttributeTargets.Property)]
public class UserFlagAttribute : Attribute
{ }
部落格模組的實體類定義
回到我們的 Liuliu.Blogs
專案,根據 業務模組設計#模組資料夾結構佈局給出的結構,在 Liuliu.Blogs.Core
專案中建立 Blogs/Entities
的資料夾存放實體類,新增如下實體類檔案。
部落格實體 - Blog
namespace Liuliu.Blogs.Blogs.Entities
{
/// <summary>
/// 實體類:部落格資訊
/// </summary>
public class Blog : EntityBase<int>, ICreatedTime, ISoftDeletable
{
/// <summary>
/// 獲取或設定 部落格地址
/// </summary>
[Required]
public string Url { get; set; }
/// <summary>
/// 獲取或設定 顯示名稱
/// </summary>
[Required]
public string Display { get; set; }
/// <summary>
/// 獲取或設定 已開通
/// </summary>
public bool IsEnabled { get; set; }
/// <summary>
/// 獲取或設定 建立時間
/// </summary>
public DateTime CreatedTime { get; set; }
/// <summary>
/// 獲取或設定 資料邏輯刪除時間,為null表示正常資料,有值表示已邏輯刪除
/// </summary>
public DateTime? DeletedTime { get; set; }
/// <summary>
/// 獲取或設定 作者編號
/// </summary>
[UserFlag]
public int UserId { get; set; }
/// <summary>
/// 獲取或設定 作者
/// </summary>
public virtual User User { get; set; }
}
}
文章實體 - Post
namespace Liuliu.Blogs.Blogs.Entities
{
/// <summary>
/// 實體類:文章資訊
/// </summary>
public class Post:EntityBase<int>,ICreatedTime,ISoftDeletable
{
/// <summary>
/// 獲取或設定 文章標題
/// </summary>
[Required]
public string Title { get; set; }
/// <summary>
/// 獲取或設定 文章內容
/// </summary>
[Required]
public string Content { get; set; }
/// <summary>
/// 獲取或設定 建立時間
/// </summary>
public DateTime CreatedTime { get; set; }
/// <summary>
/// 獲取或設定 資料邏輯刪除時間,為null表示正常資料,有值表示已邏輯刪除
/// </summary>
public DateTime? DeletedTime { get; set; }
/// <summary>
/// 獲取或設定 所屬部落格編號
/// </summary>
public int BlogId { get; set; }
/// <summary>
/// 獲取或設定 所屬部落格
/// </summary>
public virtual Blog Blog { get; set; }
/// <summary>
/// 獲取或設定 作者編號
/// </summary>
[UserFlag]
public int UserId { get; set; }
/// <summary>
/// 獲取或設定 作者
/// </summary>
public virtual User User { get; set; }
}
}
輸入輸出DTO
輸入輸出DTO:輸入輸出DTO主要負責各層次之間的資料傳輸工作,避免在外層暴露實體類。
輸入輸出DTO相關介面
InputDto
定義輸入DTO:輸入DTO 需實現此介面,作為 業務層引數型別、DTO屬性合法性驗證資料型別 的約束。
/// <summary>
/// 定義輸入DTO
/// </summary>
/// <typeparam name="TKey"></typeparam>
public interface IInputDto<TKey>
{
/// <summary>
/// 獲取或設定 主鍵,唯一標識
/// </summary>
TKey Id { get; set; }
}
IOutputDto
定義輸出DTO:輸出DTO 需實現此介面,此介面將作為 分頁查詢 返回型別的約束。
/// <summary>
/// 定義輸出DTO
/// </summary>
public interface IOutputDto
{ }
資料實體對映
定義資料許可權的更新,刪除狀態:用於 輸入DTOIOutputDto
,此介面為輸出DTO提供 是否允許更新Updatable
、是否允許刪除Deletable
兩個資料許可權屬性,輸出DTO實現了此介面,在進行資料分頁查詢時,將使用 全實體 查詢模式並進行 資料許可權校驗,在輸出DTO中自動附加資料許可權(是否可更新、是否可刪除)資訊。
/// <summary>
/// 定義資料許可權的更新,刪除狀態
/// </summary>
public interface IDataAuthEnabled
{
/// <summary>
/// 獲取或設定 是否可更新的資料許可權狀態
/// </summary>
bool Updatable { get; set; }
/// <summary>
/// 獲取或設定 是否可刪除的資料許可權狀態
/// </summary>
bool Deletable { get; set; }
}
部落格模組的輸入輸出DTO類定義
回到我們的 Liuliu.Blogs
專案,根據 業務模組設計#模組資料夾結構佈局給出的結構,在 Liuliu.Blogs.Core
專案中建立 Blogs/Dtos
的資料夾存放實體類,新增如下輸入輸出DTO類檔案。
部落格 - Blog
部落格 InputDto
namespace Liuliu.Blogs.Blogs.Dtos
{
/// <summary>
/// 輸入DTO:部落格資訊
/// </summary>
public class BlogInputDto : IInputDto<int>
{
/// <summary>
/// 獲取或設定 部落格編號
/// </summary>
public int Id { get; set; }
/// <summary>
/// 獲取或設定 部落格地址
/// </summary>
[Required]
public string Url { get; set; }
/// <summary>
/// 獲取或設定 顯示名稱
/// </summary>
[Required]
public string Display { get; set; }
}
}
部落格 OutputDto
namespace Liuliu.Blogs.Blogs.Dtos
{
/// <summary>
/// 輸出DTO:部落格資訊
/// </summary>
public class BlogOutputDto : IOutputDto, IDataAuthEnabled
{
/// <summary>
/// 獲取或設定 部落格編號
/// </summary>
public int Id { get; set; }
/// <summary>
/// 獲取或設定 部落格地址
/// </summary>
public string Url { get; set; }
/// <summary>
/// 獲取或設定 顯示名稱
/// </summary>
public string Display { get; set; }
/// <summary>
/// 獲取或設定 已開通
/// </summary>
public bool IsEnabled { get; set; }
/// <summary>
/// 獲取或設定 建立時間
/// </summary>
public DateTime CreatedTime { get; set; }
/// <summary>
/// 獲取或設定 作者編號
/// </summary>
public int UserId { get; set; }
/// <summary>
/// 獲取或設定 是否可更新的資料許可權狀態
/// </summary>
public bool Updatable { get; set; }
/// <summary>
/// 獲取或設定 是否可刪除的資料許可權狀態
/// </summary>
public bool Deletable { get; set; }
}
}
文章 - Post
文章 InputDto
namespace Liuliu.Blogs.Blogs.Dtos
{
/// <summary>
/// 輸入DTO:文章資訊
/// </summary>
public class PostInputDto : IInputDto<int>
{
/// <summary>
/// 獲取或設定 文章編號
/// </summary>
public int Id { get; set; }
/// <summary>
/// 獲取或設定 文章標題
/// </summary>
[Required]
public string Title { get; set; }
/// <summary>
/// 獲取或設定 文章內容
/// </summary>
[Required]
public string Content { get; set; }
}
}
文章 OutputDto
namespace Liuliu.Blogs.Blogs.Dtos
{
/// <summary>
/// 輸出DTO:文章資訊
/// </summary>
public class PostOutputDto : IOutputDto, IDataAuthEnabled
{
/// <summary>
/// 獲取或設定 文章編號
/// </summary>
public int Id { get; set; }
/// <summary>
/// 獲取或設定 文章標題
/// </summary>
public string Title { get; set; }
/// <summary>
/// 獲取或設定 文章內容
/// </summary>
public string Content { get; set; }
/// <summary>
/// 獲取或設定 建立時間
/// </summary>
public DateTime CreatedTime { get; set; }
/// <summary>
/// 獲取或設定 所屬部落格編號
/// </summary>
public int BlogId { get; set; }
/// <summary>
/// 獲取或設定 作者編號
/// </summary>
[UserFlag]
public int UserId { get; set; }
/// <summary>
/// 獲取或設定 是否可更新的資料許可權狀態
/// </summary>
public bool Updatable { get; set; }
/// <summary>
/// 獲取或設定 是否可刪除的資料許可權狀態
/// </summary>
public bool Deletable { get; set; }
}
}
資料實體對映配置
OSharp框架中,實體對映配置類主要有兩個作用:
- 在系統初始化時將實體類載入到上下文中
- 實現實體類到資料庫的對映細節配置
相關介面與基類
IEntityRegister
將實體配置類註冊到上下文中:IEntityRegister
介面定義了一個DbContextType
屬性,可將一個實體類註冊到指定的上下文中,這在自定義多個數據上下文的時候會用到。
在實體對映類中實現此介面,資料上下文初始化的時候,在OnModelCreating
方法中通過呼叫RegisterTo(ModelBuilder modelBuilder)
方法,將實體對映類的例項註冊到ModelBuilder
中。
/// <summary>
/// 定義將實體配置類註冊到上下文中
/// </summary>
public interface IEntityRegister
{
/// <summary>
/// 獲取所屬的上下文型別,如為null,將使用預設上下文,否則使用指定型別的上下文型別
/// </summary>
Type DbContextType { get; }
/// <summary>
/// 獲取 相應的實體型別
/// </summary>
Type EntityType { get; }
/// <summary>
/// 將當前實體類對映物件註冊到資料上下文模型構建器中
/// </summary>
/// <param name="modelBuilder">上下文模型構建器</param>
void RegisterTo(ModelBuilder modelBuilder);
}
EntityTypeConfigurationBase
資料實體對映配置基類:為方便實現實體對映配置類,OSharp定義了此基類,實現了 IEntityTypeConfiguration<TEntity>
,IEntityRegister
兩個介面,在實現實體對映配置類時,只需繼承此類,實現Configure(EntityTypeBuilder<TEntity> builder)
抽象方法即可。
/// <summary>
/// 資料實體對映配置基類
/// </summary>
/// <typeparam name="TEntity">實體型別</typeparam>
/// <typeparam name="TKey">主鍵型別</typeparam>
public abstract class EntityTypeConfigurationBase<TEntity, TKey> : IEntityTypeConfiguration<TEntity>, IEntityRegister
where TEntity : class, IEntity<TKey>
where TKey : IEquatable<TKey>
{
/// <summary>
/// 獲取 所屬的上下文型別,如為null,將使用預設上下文, 否則使用指定型別的上下文型別
/// </summary>
public virtual Type DbContextType => null;
/// <summary>
/// 獲取 相應的實體型別
/// </summary>
public Type EntityType => typeof(TEntity);
/// <summary>
/// 將當前實體類對映物件註冊到資料上下文模型構建器中
/// </summary>
/// <param name="modelBuilder">上下文模型構建器</param>
public void RegisterTo(ModelBuilder modelBuilder)
{
modelBuilder.ApplyConfiguration(this);
// 給軟刪除的實體新增全域性過濾器
if (typeof(ISoftDeletable).IsAssignableFrom(typeof(TEntity)))
{
modelBuilder.Entity<TEntity>().HasQueryFilter(m => ((ISoftDeletable)m).DeletedTime == null);
}
}
/// <summary>
/// 重寫以實現實體型別各個屬性的資料庫配置
/// </summary>
/// <param name="builder">實體型別建立器</param>
public abstract void Configure(EntityTypeBuilder<TEntity> builder);
}
部落格模組的實體對映配置類實現
回到我們的 Liuliu.Blogs
專案,根據 業務模組設計#模組資料夾結構佈局給出的結構,在 Liuliu.Blogs.EntityConfiguration
專案中建立 Blogs
的資料夾存放實體類,新增如下實體對映配置類檔案。
部落格 - Blog
根據 業務模組設計#資料層的定義,部落格實體的設計要求Url
屬性 唯一索引,並且 部落格與博主 之間的關係是 一對一,因此做如下約束:
- 建立
Url
屬性的唯一索引,形式本應是builder.HasIndex(m => m.Url)
,但部落格實體引入了邏輯刪除,因此唯一索引應加入邏輯刪除屬性DeletedTime
- 部落格實體與使用者實體之間以
UserId
為外來鍵,建立一對一關係,並且對於一個部落格來說,其擁有者是必須的,因此需要加上IsRequired
約束,並禁止級聯刪除。
/// <summary>
/// 實體對映配置類:部落格資訊
/// </summary>
public class BlogConfiguration : EntityTypeConfigurationBase<Blog, int>
{
/// <summary>
/// 重寫以實現實體型別各個屬性的資料庫配置
/// </summary>
/// <param name="builder">實體型別建立器</param>
public override void Configure(EntityTypeBuilder<Blog> builder)
{
builder.HasIndex(m => new {m.Url, m.DeletedTime}).HasName("BlogUrlIndex").IsUnique();
builder.HasOne(m => m.User).WithOne().HasForeignKey<Blog>(m => m.UserId).OnDelete(DeleteBehavior.Restrict).IsRequired();
}
}
文章 - Post
根據 業務模組設計#資料層的定義,文章實體的設計要求 文章與部落格 之間的關係是 多對一,文章與作者 之間的關係是 多對一,因此做如下約束:
- 文章實體與部落格實體之間以
BlogId
為外來鍵,建立多對一關係,並且對於一篇文章來說,其所在部落格是必須的,因此需要加上IsRequired
約束,並禁止級聯刪除。 - 文章實體與使用者實體之間以
UserId
為外來鍵,建立多對一關係,並且對於一篇文章來說,其作者是必須的,因此需要加上IsRequired
約束,並禁止級聯刪除。
/// <summary>
/// 實體對映配置類:文章資訊
/// </summary>
public class PostConfiguration : EntityTypeConfigurationBase<Post, int>
{
/// <summary>
/// 重寫以實現實體型別各個屬性的資料庫配置
/// </summary>
/// <param name="builder">實體型別建立器</param>
public override void Configure(EntityTypeBuilder<Post> builder)
{
builder.HasOne(m => m.Blog).WithMany().HasForeignKey(m => m.BlogId).OnDelete(DeleteBehavior.Restrict).IsRequired();
builder.HasOne(m => m.User).WithMany().HasForeignKey(m => m.UserId).OnDelete(DeleteBehavior.Restrict).IsRequired();
}
}
至此,部落格模組的資料層程式碼實現完畢。下面可進行資料遷移將資料結構更新到現有資料庫中。
資料遷移
開啟 VS2019 的 程式包管理器控制檯,將預設專案設定為 src\Liuliu.Blogs.Web
,執行如下命令新增名稱為AddBlogsEntities
的新的遷移記錄:
add-migration AddBlogsEntities
再執行資料庫更新命令,執行遷移
update-database
資料遷移完畢,整個過程輸出如下:
PM> add-migration AddBlogsEntities
entryAssemblyName: Liuliu.Blogs.Web
To undo this action, use Remove-Migration.
PM> update-database
entryAssemblyName: Liuliu.Blogs.Web
Applying migration '20190504130412_AddBlogsEntities'.
Done.
PM>
開啟資料庫,我們將看到新的資料表dbo.Blog
和dbo.Post
已經成功建立: