pos-system/services/_template_dot_net

.NET Service Template / Template Dịch Vụ .NET

EN: Template for creating new .NET microservices in the GoodGo platform
VI: Template để tạo microservices .NET mới trong nền tảng GoodGo

Overview / Tổng Quan

EN: This template provides a standardized structure for .NET microservices with:

• ASP.NET Core Web API
• Entity Framework Core
• Clean Architecture principles
• Health checks and observability
• Docker support
• Authentication and authorization

VI: Template này cung cấp cấu trúc chuẩn hóa cho các microservices .NET với:

• ASP.NET Core 10 Web API
• Entity Framework Core 10 (PostgreSQL / Neon)
• Neon Database Integration (Connection Resilience)
• 原 tắc Clean Architecture
• CQRS với MediatR
• Resilience với Polly
• Global Exception Handling (RFC 7807)
• API Versioning
• Audit Logging
• Health checks và observability
• Hỗ trợ Docker
• Xác thực và phân quyền
• Performance improvements của .NET 10

Prerequisites / Yêu Cầu

• .NET 10.0 SDK or later / .NET 10.0 SDK trở lên
• Docker & Docker Compose
• PostgreSQL (via Neon or local)
• Redis (optional, for caching)

Quick Start / Bắt Đầu Nhanh

1. Create New Service / Tạo Service Mới

# EN: Copy template to new service
# VI: Sao chép template sang service mới
cp -r services/_template_dot_net services/your-service-name

# EN: Navigate to service directory
# VI: Di chuyển đến thư mục service
cd services/your-service-name

2. Configure Service / Cấu Hình Service

EN: Update the following files:

• YourServiceName.csproj - Project name and namespace
• appsettings.json - Configuration settings
• Dockerfile - Service-specific settings

VI: Cập nhật các file sau:

• YourServiceName.csproj - Tên project và namespace
• appsettings.json - Cài đặt cấu hình
• Dockerfile - Cài đặt cụ thể cho service

3. Environment Variables / Biến Môi Trường

Create .env file from .env.example:

cp .env.example .env

Required variables / Biến bắt buộc:

Variable	Description / Mô Tả	Example
ASPNETCORE_ENVIRONMENT	Environment (Development/Production) / Môi trường	Development
DATABASE_URL	PostgreSQL connection string / Chuỗi kết nối PostgreSQL	Host=localhost;Database=mydb;Username=user;Password=pass
REDIS_URL	Redis connection string / Chuỗi kết nối Redis	localhost:6379
JWT_SECRET	JWT signing secret / Secret ký JWT	your-secret-key-min-32-chars

Project Structure / Cấu Trúc Dự Án

services/your-service-name/
├── src/
│   ├── YourServiceName.Api/           # Web API layer / Lớp Web API
│   │   ├── Controllers/               # API controllers / Controllers API
│   │   ├── Middleware/                # Custom middleware
│   │   ├── Program.cs                 # Entry point / Điểm khởi đầu
│   │   └── appsettings.json          # Configuration / Cấu hình
│   │
│   ├── YourServiceName.Application/   # Application layer / Lớp ứng dụng
│   │   ├── DTOs/                     # Data Transfer Objects
│   │   ├── Services/                 # Business logic services
│   │   └── Interfaces/               # Service interfaces
│   │
│   ├── YourServiceName.Domain/        # Domain layer / Lớp domain
│   │   ├── Entities/                 # Domain entities / Thực thể domain
│   │   └── Interfaces/               # Repository interfaces
│   │
│   └── YourServiceName.Infrastructure/ # Infrastructure layer / Lớp hạ tầng
│       ├── Data/                     # DbContext and migrations
│       ├── Repositories/             # Repository implementations
│       └── Services/                 # External service clients
│
├── tests/
│   ├── YourServiceName.UnitTests/    # Unit tests
│   └── YourServiceName.IntegrationTests/ # Integration tests
│
├── Dockerfile                         # Docker configuration
├── .dockerignore
└── README.md

Development / Phát Triển

Run Locally / Chạy Local

# EN: Restore dependencies
# VI: Khôi phục dependencies
dotnet restore

# EN: Run migrations
# VI: Chạy migrations
dotnet ef database update --project src/YourServiceName.Infrastructure

# EN: Start service
# VI: Khởi động service
dotnet run --project src/YourServiceName.Api

Run with Docker / Chạy với Docker

# EN: Build Docker image
# VI: Build Docker image
docker build -t your-service-name .

# EN: Run container
# VI: Chạy container
docker run -p 5000:8080 --env-file .env your-service-name

Testing / Kiểm Thử

# EN: Run all tests
# VI: Chạy tất cả tests
dotnet test

# EN: Run with coverage
# VI: Chạy với coverage
dotnet test /p:CollectCoverage=true /p:CoverageReportFormat=opencover

# EN: Run specific test project
# VI: Chạy project test cụ thể
dotnet test tests/YourServiceName.UnitTests

API Documentation / Tài Liệu API

EN: The service automatically generates Swagger/OpenAPI documentation available at:

• Development: http://localhost:5000/swagger
• Production: https://api.goodgo.com/your-service/swagger

VI: Service tự động tạo tài liệu Swagger/OpenAPI tại:

• Development: http://localhost:5000/swagger
• Production: https://api.goodgo.com/your-service/swagger

What's New in .NET 10 / Có Gì Mới Trong .NET 10

EN: This template leverages new .NET 10 features:

• Improved performance and reduced memory allocation
• Enhanced Native AOT support
• Better async/await performance
• Updated C# 13 language features
• Improved JSON serialization performance

VI: Template này tận dụng các tính năng mới của .NET 10:

• Cải thiện hiệu năng và giảm memory allocation
• Hỗ trợ Native AOT tốt hơn
• Hiệu năng async/await được cải thiện
• Tính năng ngôn ngữ C# 13 mới
• Hiệu năng JSON serialization được cải thiện

Health Checks

Endpoint	Description / Mô Tả
/health	Overall health status / Trạng thái tổng thể
/health/live	Liveness probe / Kiểm tra sống
/health/ready	Readiness probe / Kiểm tra sẵn sàng

Architecture Patterns / Mẫu Kiến Trúc

EN: This template follows Clean Architecture principles:

1. API Layer: Controllers, middleware, configuration
2. Application Layer: Business logic, DTOs, services
3. Domain Layer: Entities, interfaces, domain logic
4. Infrastructure Layer: Data access, external services

VI: Template này tuân theo nguyên tắc Clean Architecture:

1. Lớp API: Controllers, middleware, cấu hình
2. Lớp Application: Business logic, DTOs, services
3. Lớp Domain: Entities, interfaces, domain logic
4. Lớp Infrastructure: Truy cập dữ liệu, external services

Best Practices / Thực Hành Tốt

1. Dependency Injection: Use built-in DI container / Sử dụng DI container có sẵn
2. Async/Await: Use async methods for I/O operations / Dùng async cho I/O
3. Logging: Use ILogger for structured logging / Dùng ILogger
4. Validation: Use FluentValidation for input validation / Dùng FluentValidation
5. Error Handling: Implement global exception middleware / Middleware xử lý lỗi toàn cục

Resources / Tài Nguyên

• ASP.NET Core Documentation
• Entity Framework Core
• Clean Architecture
• GoodGo Platform Documentation

License / Giấy Phép

Proprietary - GoodGo Platform