Nhảy đến nội dung chính

Nội dung chi tiết

1. Tổng quan kiến trúc hệ thống

1.1. Mục tiêu kiến trúc

Kiến trúc backend được thiết kế nhằm:

  • Đảm bảo khả năng mở rộng và bảo trì lâu dài

  • Tách biệt rõ trách nhiệm giữa các layer

  • Chuẩn hóa cách tổ chức code giữa các module

  • Hỗ trợ phát triển song song nhiều developer

  • Dễ dàng tích hợp các hệ thống ngoài (SSO, Cache, MQ…)

Tất cả các service backend phải tuân thủ kiến trúc chuẩn được định nghĩa trong tài liệu này.

1.2. Mô hình kiến trúc

Hệ thống backend sử dụng mô hình:

Modular Monolith – Layered Architecture

Đặc điểm:

  • Một service Spring Boot deploy độc lập

  • Bên trong chia module theo domain

  • Mỗi module có đầy đủ layer Controller → Service → Repository

  • Có thể tách thành microservice khi cần

Sơ đồ tổng thể:


Client (Web / Mobile / External System) ↓ Controller (API Layer) ↓ Service (Business Layer) ↓ Repository (Persistence Layer) ↓ DB

Tích hợp ngoài:


Client → API → Service → ↘ DB ↘ Redis Cache ↘ Message Queue ↘ SSO / Identity Server ↘ External API

1.3. Quy tắc phân lớp (Layered Architecture)

Mỗi module phải tuân thủ cấu trúc phân lớp sau:

controller service repository entity dto mapper exception

1.3.1. Controller Layer (API Layer)

Chức năng:

  • Nhận request HTTP

  • Validate input DTO

  • Gọi service xử lý

  • Trả response chuẩn

Quy định:

  • Không chứa business logic

  • Không truy cập DB trực tiếp

  • Không xử lý transaction

  • Không map entity

Ví dụ:


@RestController @RequestMapping("/api/users") public class UserController { private final UserService userService; @PostMapping public ApiResponse<UserResponse> create(@Valid @RequestBody UserRequest req) { return ApiResponse.success(userService.create(req)); } }

1.3.2. Service Layer (Business Layer)

Chức năng:

  • Chứa toàn bộ business logic

  • Điều phối repository

  • Xử lý transaction

  • Mapping entity ↔ DTO

Quy định:

  • Không nhận HttpServletRequest

  • Không trả Entity ra ngoài

  • Phải qua DTO/Response

  • Transaction đặt tại Service

Ví dụ:


@Service public class UserService { @Transactional public UserResponse create(UserRequest req) { User entity = mapper.toEntity(req); repository.save(entity); return mapper.toResponse(entity); } }

1.3.3. Repository Layer (Persistence Layer)

Chức năng:

  • Truy cập DB

  • Query dữ liệu

  • Mapping ORM

Quy định:

  • Không chứa business logic

  • Không gọi service

  • Chỉ thao tác entity

Ví dụ:


public interface UserRepository extends JpaRepository<User, Long> { }

1.3.4. Entity Layer

Chức năng:

  • Mapping bảng DB

  • Quan hệ ORM

Quy định:

  • Không chứa logic nghiệp vụ

  • Không trả trực tiếp ra API

  • Không dùng cho request/response

1.3.5. DTO Layer

Gồm:

  • Request DTO

  • Response DTO

Chức năng:

  • Trao đổi dữ liệu với client

  • Tách biệt entity và API

Quy định:

  • Controller chỉ nhận/trả DTO

  • Không expose entity

1.3.6. Mapper Layer

Chức năng:

  • Chuyển đổi DTO ↔ Entity

Có thể dùng:

  • MapStruct

  • Manual mapping

Quy định:

  • Không đặt trong controller

  • Không đặt trong repository

1.4. Quy tắc phụ thuộc (Dependency Direction)

Dependency chỉ được phép đi theo một chiều:


Controller → Service → Repository → DB

Không được phép:

  • Repository gọi Service

  • Service gọi Controller

  • Controller gọi Repository trực tiếp

  • DTO gọi Repository

Nguyên tắc:

Layer trên được gọi layer dưới
Layer dưới không được gọi layer trên

1.5. Tổ chức module theo domain

Project được tổ chức theo domain thay vì technical layer toàn cục.

Cấu trúc chuẩn:


com.company.project ├── common │ ├── config │ ├── exception │ ├── util │ ├── user │ ├── controller │ ├── service │ ├── repository │ ├── entity │ ├── dto │ ├── mapper │ ├── document │ ├── controller │ ├── service │ ├── repository │ ├── entity │ ├── dto │ ├── mapper

Ưu điểm:

  • Dễ quản lý domain

  • Dễ tách microservice

  • Giảm phụ thuộc chéo

1.6. Tích hợp hệ thống ngoài

Backend có thể tích hợp các thành phần sau:

  • SSO / Identity Server

  • Cache (Redis)

  • Message Queue

  • File Storage

  • External API

Quy tắc tích hợp:

  • Gọi qua Service

  • Không gọi trực tiếp từ Controller

  • Tách client class riêng

Ví dụ:


integration ├── sso │ ├── SsoClient │ ├── redis │ ├── RedisService │ ├── external │ ├── ExternalApiClient

1.7. Nguyên tắc kiến trúc bắt buộc

Tất cả backend service phải tuân thủ:

  • Không expose entity ra API

  • Không viết business logic trong controller

  • Không truy cập DB ngoài repository

  • Không phụ thuộc ngược layer

  • Transaction đặt tại service

  • Mapping qua DTO

Vi phạm kiến trúc được xem là lỗi nghiêm trọng trong review code.

1.8. Khả năng mở rộng Microservice

Kiến trúc hiện tại cho phép tách module thành microservice khi cần:

Ví dụ:


user module → user-service document module → document-service auth module → auth-service

Do đã tách domain và layer rõ ràng nên việc tách service không ảnh hưởng code business

Lên đầu trang