1. 程式人生 > >[開源]OSharpNS 步步為營系列 - 2. 新增業務資料層

[開源]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框架中,實體對映配置類主要有兩個作用:

  1. 在系統初始化時將實體類載入到上下文中
  2. 實現實體類到資料庫的對映細節配置

相關介面與基類

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屬性 唯一索引,並且 部落格與博主 之間的關係是 一對一,因此做如下約束:

  1. 建立Url屬性的唯一索引,形式本應是builder.HasIndex(m => m.Url),但部落格實體引入了邏輯刪除,因此唯一索引應加入邏輯刪除屬性DeletedTime
  2. 部落格實體與使用者實體之間以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

根據 業務模組設計#資料層的定義,文章實體的設計要求 文章與部落格 之間的關係是 多對一,文章與作者 之間的關係是 多對一,因此做如下約束:

  1. 文章實體與部落格實體之間以BlogId為外來鍵,建立多對一關係,並且對於一篇文章來說,其所在部落格是必須的,因此需要加上IsRequired約束,並禁止級聯刪除。
  2. 文章實體與使用者實體之間以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.Blogdbo.Post已經成功建立: