LnskyDB là một thư viện mã nguồn mở, mở rộng khả năng của Dapper bằng cách tích hợp hỗ trợ biểu thức Lambda. Nó được thiết kế để đơn giản hóa các thao tác cơ sở dữ liệu, đặc biệt là trong các kịch bản phức tạp yêu cầu phân chia cơ sở dữ liệu và bảng (sharding) theo thời gian hoặc các quy tắc tùy chỉnh. Một trong những tính năng nổi bật của thư viện này là khả năng tự động sinh mã các lớp thực thể (entity classes) thông qua template T4, giúp giảm đáng kể công sức lập trình thủ công.

Kho Lưu Trữ (Repository)

Để tương tác với cơ sở dữ liệu bằng LnskyDB, có hai cách chính để lấy một thể hiện của kho lưu trữ (repository). Cách thứ nhất là gọi phương thức tĩnh RepositoryFactory.Create<T>(). Cách thứ hai là định nghĩa lớp kho lưu trữ của riêng bạn và kế thừa từ lớp Repository<T>. Nếu kiến trúc dự án yêu cầu, bạn cũng có thể định nghĩa một interface kế thừa từ IRepository<T>. Thuộc tính CommandTimeout trong kho lưu trữ cho phép bạn cấu hình thời gian chờ tối đa cho việc thực thi các lệnh cơ sở dữ liệu.

Lớp Thực Thể (Entity Class)

Các lớp thực thể trong LnskyDB phải kế thừa từ lớp trừu tượng BaseDBModel. Lớp cơ sở này cung cấp cơ sở hạ tầng cần thiết và yêu cầu triển khai một số phương thức trừu tượng để định nghĩa các đặc tính của thực thể.

1. Cấu hình Khóa Chính

Phương thức GetDBModel_PKCols() là bắt buộc để chỉ định tên các cột khóa chính của bảng.

private static readonly ImmutableList<string> _keyColumns = ImmutableList.Create("MaSanPham");

public override ImmutableList<string> GetDBModel_PKCols() => _keyColumns;

2. Cấu hình Cột Tự Tăng

Các phương thức GetDBModel_IncrementCol() và SetIncrementValue(int value) được sử dụng để định nghĩa cột tự tăng và gán giá trị cho nó. Chúng là bắt buộc nếu bảng có cột tự tăng.

public override string GetDBModel_IncrementCol() => "MaSo"; // Ví dụ: Cột tự tăng có tên là 'MaSo'

public override void SetIncrementValue(int value)
{
    // Gán giá trị tự tăng vào thuộc tính tương ứng của thực thể
    MaSo = value;
}

3. Cấu hình Tên Cơ Sở Dữ Liệu và Bảng

Các phương thức GetDBModel_TableName() và GetDBModel_DBName() là bắt buộc để cung cấp tên bảng và tên cơ sở dữ liệu. Đối với các bảng hoặc cơ sở dữ liệu được phân chia (sharded), placeholder {0} được sử dụng để chỉ ra vị trí sẽ chèn định danh shard.

public override string GetDBModel_TableName() => "DonHangChiTiet{0}"; // Ví dụ: Bảng DonHangChiTiet, {0} cho sharding
public override string GetDBModel_DBName() => "DuLieuChinh{0}";     // Ví dụ: CSDL DuLieuChinh, {0} cho sharding

4. Cấu hình Phân Chia Dữ Liệu (Sharding)

Các phương thức này dùng để cấu hình cách thực thể tham gia vào cơ chế sharding. Phương thức GetShuffledModel() xác định logic sharding dựa trên một thuộc tính (ví dụ: ngày phân chia), trong khi SetShuffledData() dùng để truyền giá trị sharding vào thực thể.

private DateTime _dataPartitionDate;

[JsonIgnore]
public DateTime DataPartitionDate
{
    get => _dataPartitionDate != DateTime.MinValue ? _dataPartitionDate : DateTime.MinValue;
    set => _dataPartitionDate = value;
}

public override ShuffledModel GetShuffledModel()
{
    if (DataPartitionDate == DateTime.MinValue)
    {
        throw new NoShuffledException(GetDBModel_TableName(), "Cần cung cấp thời gian phân chia dữ liệu.");
    }
    // Giả sử có một phương thức tĩnh để xử lý logic phân chia dựa trên ngày
    return ShuffledByDate(DataPartitionDate);
}

public override void SetShuffledData(object obj)
{
    if (obj is DateTime dateValue)
    {
        DataPartitionDate = dateValue;
    }
    // Có thể thêm xử lý lỗi nếu obj không phải DateTime
}

Ghi Nhật Ký Lỗi

LnskyDB cung cấp sự kiện DBTool.Error, được kích hoạt bất cứ khi nào có ngoại lệ xảy ra trong quá trình thực thi lệnh SQL. Điều này cho phép các nhà phát triển triển khai cơ chế ghi nhật ký lỗi hoặc xử lý lỗi tùy chỉnh.

Tạo Mã bằng Template T4

LnskyDB bao gồm các template T4 để tự động sinh mã các lớp thực thể. Các template này thường có thể được tìm thấy trong thư mục T4 của các dự án mẫu (ví dụ: LnskyDB.Demo). Chúng có thể được tùy chỉnh cao để phù hợp với yêu cầu cụ thể của từng dự án.

Cấu hình trong DbHelper.ttinclude

Phần Config.DbConfigs trong file DbHelper.ttinclude là nơi định nghĩa các cấu hình sinh mã. Một số tham số cấu hình chính bao gồm:

• ConnectionString: Chuỗi kết nối đến cơ sở dữ liệu.
• Database: Tên cơ sở dữ liệu thực tế.
• DatabaseName: Tên logic của cơ sở dữ liệu, thường được lưu trữ trong appsettings.json.
• TableNames: Danh sách các bảng cần sinh thực thể (ví dụ: * cho tất cả, Prefix_ cho các bảng bắt đầu bằng Prefix_).
• ExcludeTableName: Các bảng cần loại trừ khỏi quá trình sinh mã.
• ShuffledConfigs: Định nghĩa cấu hình sharding cho các bảng, dưới dạng cặp khóa-giá trị.
• ShuffledConfig: Chi tiết cụ thể về sharding, bao gồm ShuffledData (cột được sử dụng để sharding) và MinShuffledTempDate (ngày tối thiểu cho sharding dựa trên thời gian).

File Entity.tt

File template Entity.tt chứa logic cốt lõi để sinh mã các lớp thực thể, interface repository và triển khai repository. File này có thể được sửa đổi để phù hợp với tiêu chuẩn mã hóa hoặc các mẫu kiến trúc cụ thể của dự án.