TGL.Backend.Core 3.2.3

TGL.Backend.Core

Core backend library cho các dịch vụ .NET của TGL Solutions. Thư viện gom sẵn các building block dùng chung: multi-tenant repository, Unit of Work, xác thực PASETO / API Key, event bus trên Kafka, cache Redis, S3, logging tập trung và global exception handling — giúp khởi tạo một microservice mới nhanh và nhất quán.

Mục lục

• Cài đặt
• Tính năng
• Bắt đầu nhanh
• Cấu hình chi tiết
  • Database & Unit of Work
  • Repository
  • Xác thực (PASETO & API Key)
  • Event Bus (Kafka)
  • Redis & S3
  • Pagination nâng cao
• Biến môi trường
• Yêu cầu hệ thống
• Author
• License

Cài đặt

dotnet add package TGL.Backend.Core

Hoặc thêm trực tiếp vào file .csproj:

<PackageReference Include="TGL.Backend.Core" Version="2.9.5" />

Tính năng

• Multi-tenant repository — BaseRepository<T> tự động lọc theo SiteId (tenant) và soft-delete (IsDeleted).
• Unit of Work — quản lý transaction, hỗ trợ nested transaction và truy xuất repository động.
• Xác thực linh hoạt — "Smart" scheme tự chọn giữa PASETO (Bearer token) và API Key (X-API-KEY).
• PASETO v4 — phát hành / xác thực access token (public) và refresh token (local).
• Event Bus trên Kafka — publish/subscribe integration event, tự sinh tên topic theo môi trường.
• Logging tập trung — Serilog + sink Kafka, enrich sẵn CorrelationId, Email, IpAddress.
• Global exception handling — chuẩn hóa mọi lỗi về BaseResponse<T>.
• Cache Redis — ICacheService với retry & reconnect policy.
• S3 storage — factory + service cho AWS S3 (đa cấu hình).
• Pagination nâng cao — filter/sort động theo dot-path, hỗ trợ navigation & collection (Any).
• Correlation ID — middleware + delegating handler tự truyền X-Correlation-Id giữa các service.

Bắt đầu nhanh

using BackendCore.Configuration;

var builder = WebApplication.CreateBuilder(args);

// Đăng ký toàn bộ cấu hình core (MediatR, AutoMapper, FluentValidation,
// Swagger, CORS, Auth, Kafka, JSON options...). Truyền vào 1 type bất kỳ
// nằm trong assembly ứng dụng để quét handler/validator/mapper.
builder.Services.AddServiceConfiguration<Program>(builder);

// Database + Unit of Work + Repository base
builder.Services.AddDatabaseConnection<AppDbContext>(
    Database.PostgreSQL,
    connectionString: null); // null -> đọc từ env DATABASE_CONNECTION

// Redis + S3
builder.Services.AddRedisInfrastructure(connectionString: null); // null -> env REDIS_CONNECTION

var app = builder.Build();

// Pipeline chuẩn: exception handler, swagger, cors, auth, correlation, site-key...
app.AddGlobalConfiguration();

app.Run();

Cấu hình chi tiết

Database & Unit of Work

// DbContext của bạn kế thừa BaseDbContext<T>
public class AppDbContext : BaseDbContext<AppDbContext>
{
    public AppDbContext(DbContextOptions<AppDbContext> options) : base(options) { }
}

builder.Services.AddDatabaseConnection<AppDbContext>(Database.PostgreSQL, null);

Sử dụng Unit of Work:

public class OrderService(IUnitOfWork uow)
{
    public async Task PlaceOrderAsync(Order order)
    {
        await uow.ExecuteInTransactionAsync(async () =>
        {
            var repo = uow.EntityRepository<Order>();
            repo.Add(order);
            // SaveChanges + Commit được thực hiện tự động khi transaction kết thúc
        });
    }
}

Repository

// Cách 1: dùng repository generic mặc định
var repo = uow.EntityRepository<Order>();
var orders = await repo.FindManyAsync(o => o.Status == OrderStatus.Paid);

// Cách 2: đăng ký repository custom
builder.Services.AddRepository<Order, IOrderRepository, OrderRepository>();

BaseRepository<T> bắt buộc có AuthContext.SiteKey — mọi query đều tự lọc theo tenant và bỏ qua bản ghi đã soft-delete.

Xác thực (PASETO & API Key)

Scheme mặc định là SMART: nếu request có header X-API-KEY → dùng API Key, ngược lại → dùng PASETO.

// Phát hành access token
var accessToken = PasetoExtensions.PublishToken(new PasetoClaim
{
    UserId = user.Id,
    Email  = user.Email,
    RoleEnum = PasetoRole.User
});

// Xác thực token
var result = PasetoExtensions.VerificationToken<PasetoClaim>(accessToken);
if (result.IsSuccess) { /* result.Results chứa payload */ }

Event Bus (Kafka)

// 1. Định nghĩa event
public class OrderCreatedEvent : IntergrationEvent { public string OrderId { get; set; } }

// 2. Định nghĩa handler
public class OrderCreatedHandler : IIntegrationEventHandler<OrderCreatedEvent>
{
    public Task HandleAsync(OrderCreatedEvent @event, CancellationToken ct) { /* ... */ }
}

// 3. Đăng ký subscriber
builder.Services.SubcribeConsumer<OrderCreatedEvent, OrderCreatedHandler>();

// 4. Publish
public class OrderService(IEventBus eventBus)
{
    public Task Publish(AuthContext ctx)
        => eventBus.PublishAsync(new OrderCreatedEvent { OrderId = "..." }, ctx);
}

Tên topic tự sinh theo dạng {env}.event.{eventname} (ví dụ: prod.event.ordercreated).

Redis & S3

builder.Services.AddRedisInfrastructure(null);

public class CatalogService(ICacheService cache)
{
    public Task CacheAsync(string key, Product product)
        => cache.SetAsync(key, product, TimeSpan.FromMinutes(10));
}

AddRedisInfrastructure đồng thời đăng ký IS3Service, IS3ClientFactory, IS3ConfigProvider để làm việc với AWS S3.

Pagination nâng cao

var filter = new PaginationAdvanced
{
    PageIndex = 1,
    PageSize  = 20,
    Filters =
    [
        new FilterCriteria { Field = "status", Operator = FilterOperator.Equals, Value = "Paid" },
        new FilterCriteria { Field = "assigns.userId", Operator = FilterOperator.Equals, Value = userId }
    ],
    SortBy =
    [
        new SortCriteria { Field = "updatedAt", Direction = SortDirection.Desc }
    ]
};

var result = await repo.PaginationAdvancedAsync(filter);

Hỗ trợ dot-path cho navigation property và collection (tự sinh .Any(...)), cùng nhiều toán tử: Equals, NotEquals, In, Between, Contains, StartsWith, EndsWith, GreaterThan, LessThan, IsNull, IsNotNull, ...

Biến môi trường

Dưới đây là toàn bộ biến môi trường được thư viện đọc, nhóm theo chức năng. Cột "Bắt buộc" đánh dấu biến sẽ ném exception nếu thiếu (khi tính năng tương ứng được sử dụng).

Database & Cache

¹ Bắt buộc nếu không truyền connection string qua tham số. Ở chế độ EF Migration, DATABASE_CONNECTION có thể bỏ trống.

Tenant & Authentication

PASETO (Token)

² Bắt buộc khi có sử dụng phát hành/xác thực token PASETO. Có thể sinh cặp khóa bằng PasetoExtensions.GenerateKey().

Kafka & Môi trường

S3 (AWS Storage)

³ Bắt buộc khi sử dụng IS3Service. Nếu cấu hình SETTING_SERVICE, cấu hình S3 có thể được nạp động từ service đó.

Logging tập trung (Elasticsearch & Mattermost)

⁴ Bắt buộc khi bật WriteLoggingService() (chạy LoggingConsumerHostedService).

Yêu cầu hệ thống

• .NET 8.0
• PostgreSQL (mặc định), Redis, Kafka (tùy chọn), AWS S3 (tùy chọn)

Author

• Đặng Văn Huy — Tác giả / Maintainer
• Công ty: TGL Solutions
• Sản phẩm: Core Backend (TGL.Backend.Core)

License

Phát hành theo giấy phép MIT.

© TGL Solutions. All rights reserved.