7.9 KiB
7.9 KiB
Template Microservice .NET 10
Template microservice .NET 10 cấp doanh nghiệp theo các pattern DDD, CQRS và Clean Architecture.
Tổng Quan
Template này cung cấp cấu trúc sẵn sàng production cho microservices .NET dựa trên kiến trúc tham chiếu eShopOnContainers với:
- Domain-Driven Design (DDD) - Aggregates, Entities, Value Objects, Domain Events
- CQRS Pattern - Tách biệt Commands (ghi) và Queries (đọc) với MediatR
- Clean Architecture - Phân tầng Domain, Infrastructure, API
- EF Core 10 - PostgreSQL với connection resilience
- FluentValidation - Validation request
- API Versioning - Versioning theo URL segment
- Health Checks - Probes sẵn sàng cho Kubernetes
- Structured Logging - Serilog với console và Seq
Yêu Cầu
| Yêu cầu | Phiên bản |
|---|---|
| .NET SDK | 10.0.101+ |
| Docker | 24.0+ |
| PostgreSQL | 15+ (hoặc dùng Docker) |
# Kiểm tra phiên bản .NET
dotnet --version
# Kết quả nên là: 10.0.xxx
Bắt Đầu Nhanh
1. Tạo Service Mới
# Sao chép template sang service mới
cp -r services/_template_dot_net services/your-service-name
# Di chuyển đến thư mục service
cd services/your-service-name
# Đổi tên tất cả "MyService" thành "YourService"
find . -type f -name "*.cs" -exec sed -i '' 's/MyService/YourService/g' {} +
find . -type f -name "*.csproj" -exec sed -i '' 's/MyService/YourService/g' {} +
2. Cấu Hình Môi Trường
# Sao chép template môi trường
cp .env.example .env
# Chỉnh sửa với cấu hình của bạn
nano .env
3. Chạy với Docker
# Khởi động tất cả services (API + PostgreSQL + Redis)
docker-compose up -d
# Xem logs
docker-compose logs -f myservice-api
4. Chạy Local
# Khôi phục dependencies
dotnet restore
# Build tất cả projects
dotnet build
# Chạy API
dotnet run --project src/MyService.API
Cấu Trúc Dự Án
_template_dot_net/
├── src/
│ ├── MyService.API/ # Lớp Presentation (Controllers, CQRS)
│ │ ├── Controllers/ # Các API endpoints
│ │ ├── Application/ # Triển khai CQRS
│ │ │ ├── Commands/ # Thao tác ghi (MediatR)
│ │ │ ├── Queries/ # Thao tác đọc
│ │ │ ├── Behaviors/ # MediatR pipeline behaviors
│ │ │ └── Validations/ # FluentValidation validators
│ │ ├── Middleware/ # Custom middleware
│ │ └── Program.cs # Điểm vào ứng dụng
│ │
│ ├── MyService.Domain/ # Lớp Domain (Business logic thuần túy)
│ │ ├── AggregatesModel/ # Aggregate roots và entities
│ │ ├── Events/ # Domain events
│ │ ├── Exceptions/ # Domain exceptions
│ │ └── SeedWork/ # Base classes (Entity, ValueObject, etc.)
│ │
│ └── MyService.Infrastructure/ # Lớp Infrastructure (Truy cập dữ liệu)
│ ├── EntityConfigurations/ # Cấu hình EF Core Fluent API
│ ├── Repositories/ # Triển khai repositories
│ ├── Idempotency/ # Xử lý idempotency request
│ └── MyServiceContext.cs # DbContext với Unit of Work
│
├── tests/
│ ├── MyService.UnitTests/ # Unit tests (Domain, Application)
│ └── MyService.FunctionalTests/ # Integration tests (API endpoints)
│
├── Dockerfile # Multi-stage Docker build
├── docker-compose.yml # Thiết lập phát triển local
├── global.json # Pin phiên bản .NET SDK
└── Directory.Build.props # Thuộc tính MSBuild chung
Các Endpoint API
| Method | Endpoint | Mô Tả |
|---|---|---|
GET |
/api/v1/samples |
Lấy tất cả samples |
GET |
/api/v1/samples/{id} |
Lấy sample theo ID |
POST |
/api/v1/samples |
Tạo sample mới |
PUT |
/api/v1/samples/{id} |
Cập nhật sample |
DELETE |
/api/v1/samples/{id} |
Xóa sample |
PATCH |
/api/v1/samples/{id}/status |
Thay đổi trạng thái |
Health Endpoints
| Endpoint | Mục Đích |
|---|---|
/health |
Trạng thái health đầy đủ |
/health/live |
Kiểm tra sống |
/health/ready |
Kiểm tra sẵn sàng |
Pattern CQRS
Commands (Thao Tác Ghi)
// Định nghĩa command
public record CreateSampleCommand(string Name, string? Description)
: IRequest<CreateSampleCommandResult>;
// Xử lý command
public class CreateSampleCommandHandler : IRequestHandler<CreateSampleCommand, CreateSampleCommandResult>
{
public async Task<CreateSampleCommandResult> Handle(CreateSampleCommand request, CancellationToken ct)
{
var sample = new Sample(request.Name, request.Description);
_repository.Add(sample);
await _repository.UnitOfWork.SaveEntitiesAsync(ct);
return new CreateSampleCommandResult(sample.Id);
}
}
Queries (Thao Tác Đọc)
// Định nghĩa query
public record GetSampleQuery(Guid SampleId) : IRequest<SampleViewModel?>;
Domain Model
Aggregate Root
public class Sample : Entity, IAggregateRoot
{
public string Name => _name;
public SampleStatus Status => _status;
public Sample(string name, string? description) {
// Validation business logic
if (string.IsNullOrWhiteSpace(name))
throw new SampleDomainException("Tên sample không được để trống");
// Domain event
AddDomainEvent(new SampleCreatedDomainEvent(this));
}
public void Activate() {
if (_status != SampleStatus.Draft)
throw new SampleDomainException("Chỉ sample draft mới có thể kích hoạt");
// Chuyển đổi trạng thái
}
}
Kiểm Thử
# Chạy tất cả tests
dotnet test
# Chạy với coverage
dotnet test /p:CollectCoverage=true /p:CoverageReportFormat=cobertura
# Chạy project test cụ thể
dotnet test tests/MyService.UnitTests
Cấu Hình
Biến Môi Trường
| Biến | Mô Tả | Mặc định |
|---|---|---|
ASPNETCORE_ENVIRONMENT |
Tên môi trường | Development |
DATABASE_URL |
Connection string PostgreSQL | - |
REDIS_URL |
Connection string Redis | - |
JWT_SECRET |
Secret ký JWT (tối thiểu 32 ký tự) | - |
appsettings.json
{
"ConnectionStrings": {
"DefaultConnection": "Host=localhost;Database=myservice;Username=postgres;Password=postgres"
},
"Serilog": {
"MinimumLevel": "Information"
}
}
Triển Khai
Docker Build
# Build Docker image
docker build -t myservice:latest .
# Chạy container
docker run -p 5000:8080 --env-file .env myservice:latest
Kubernetes
Xem ARCHITECTURE.md để biết manifests triển khai Kubernetes.
Có Gì Mới Trong .NET 10
- Tính năng ngôn ngữ C# 14
- Hỗ trợ Native AOT được cải thiện
- Hiệu suất async/await tốt hơn
- JSON serialization được nâng cao
- Cải thiện hiệu suất toàn diện
- Hỗ trợ LTS 3 năm (đến tháng 11/2028)
Tài Nguyên
- eShopOnContainers - Kiến trúc tham chiếu
- Tài liệu .NET 10
- DDD với .NET
- MediatR - Thư viện CQRS
- FluentValidation - Thư viện validation
Giấy Phép
Độc quyền - GoodGo Platform