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

9.Coding convention

9.1. Mục tiêu chương


Chương này quy định chuẩn coding và nguyên tắc thiết kế nhằm:

  • Đảm bảo code thống nhất giữa các module và các đơn vị phát triển

  • Giúp code dễ đọc, dễ hiểu và dễ bảo trì

  • Giảm lỗi phát sinh do cách đặt tên hoặc coding không đồng nhất

  • Tăng hiệu quả review và kiểm soát chất lượng code

  • Đảm bảo code tuân thủ nguyên lý thiết kế SOLID

  • Đảm bảo kiến trúc backend Spring Boot nhất quán toàn hệ thống

9.2. Khái niệm / phạm vi áp dụng


Quy định này áp dụng cho:

  • Toàn bộ source code của hệ thống

  • Core Team và Partner Team

  • Tất cả các module trong modules/**

  • Các thành phần trong common/** và config/** do Core Team quản lý

  • Tất cả service, controller, repository, DTO, entity

9.3. Quy định chính

9.3.1. Quy tắc đặt tên

Các thành phần phải đặt tên theo quy ước thống nhất:

Ví dụ

UserResponse

Thành phần

Quy tắc đặt tên

 Ví dụ
Controller <Name>Controller UserController

Controller

Service

<Name>Controller

Service

UserController

UserService

Service

Repository

<Name>Service

Repository

UserService

UserRepository

Repository

Entity

<Name>Repository

Entity

UserRepository

UserEntity
DTO

Entity

Request

<Name>Entity

CreateRequest, <Name>UpdateRequest

UserEntity

UserCreateRequest

DTO Request

Response

<Name>CreateRequest, <Name>UpdateRequest

Response

UserCreateRequest

UserResponse

DTO Response

Mapper

<Name>Response

Mapper		 UserMapper
Enum<Name>EnumUserStatusEnum

9.3.2. Quy tắc chung Java

ÁpDùng dụngcamelCase cho toàn bộ code Java:cho:

  • Dùng camelCase cho:

    • Biến

    • Method

  • Dùng PascalCase cho:

    • Class

    • Interface

    • Enum

Ví dụ:


private String fullName;     // đúng

private String FullName;     // sai


public

publicclass class UserService { }  // đúng

public class userService { }  // sai

9.3.3.

Quy định về logging

Không được dùng:


System.out.println("Error");


Phải dùng logging chuẩn:


private static final Logger log = LoggerFactory.getLogger(UserService.class);


log.info("User created");

log.error("Create user failed", ex);

9.3.3.4. Validation dữ liệu đầu vào

Tất cả dữ liệu đầu vào phải được validate bằng annotation.

Các annotationAnnotation chuẩn:

  • @NotNull

  • @NotBlank

  • @Size

  • @Email

  • @Pattern

Ví dụ:


public class UserCreateRequest {

@NotBlank @NotBlank

    @Size(max = 100)

    private String username;

@NotBlank @NotBlank

    private String password;

}

9.4. Nguyên lý thiết kế SOLID áp dụng trong dự án

9.4.1. S — Single Responsibility

Một class chỉ có một trách nhiệm.

Quy định dự án:

  • Controller → chỉ xử lý HTTP

  • Service → xử lý nghiệp vụ

  • Repository → truy cập DB

  • Mapper → convert DTO ↔ Entity

Sai:


public class UserController { @Autowired UserRepository repo; // sai tầng }

Đúng:


public class UserController { @Autowired UserService userService; }

9.4.2. O — Open/Closed

Code phải mở rộng được nhưng không sửa code cũ.

Áp dụng:

  • Dùng interface Service

  • Không sửa class gốc khi thêm logic

Ví dụ:


public interface NotificationService { void send(Message msg); }

Triển khai:


public class EmailNotificationService implements NotificationService { } public class SmsNotificationService implements NotificationService { }

9.4.3. L — Liskov Substitution

Class con có thể thay thế class cha.

Quy định:

  • ServiceImpl phải tuân interface

  • Không throw exception mới trái contract

Sai:


public class UserServiceImpl implements UserService { public User get(String id) { throw new UnsupportedOperationException(); } }

9.4.4. I — Interface Segregation

Không tạo interface quá lớn.

Sai:


public interface UserService { create(); update(); delete(); exportExcel(); sendEmail(); }

Đúng:


public interface UserService { } public interface UserExportService { } public interface UserNotificationService { }

9.4.5. D — Dependency Inversion

Phụ thuộc abstraction, không phụ thuộc implementation.

Quy định:

  • Inject interface

  • Không new service

Sai:


UserService service = new UserServiceImpl();

Đúng:


@Autowired UserService userService;

9.5. Quy tắc kiến trúc Spring Boot trong dự án

9.5.1. Luồng chuẩn tầng


Controller → Service → Repository → Database

Không được:


Controller → Repository Controller → EntityManager

9.5.2. Controller không chứa nghiệp vụ

Sai:


@PostMapping public User create(...) { user.setCreatedDate(LocalDateTime.now()); // sai }

Đúng:


@PostMapping public UserResponse create(...) { return userService.create(request); }

9.5.3. Service không chứa logic HTTP

Sai:


throw new ResponseStatusException(HttpStatus.BAD_REQUEST);

Đúng:


throw new BusinessException("USER_EXISTS");

9.5.4. Repository chỉ truy vấn dữ liệu

Không chứa:

  • validation

  • business logic

  • mapping

9.6. Design pattern sử dụng trong hệ thống

9.6.1. Service pattern

Service là tầng nghiệp vụ trung tâm.


Controller → Service → Repository

9.6.2. DTO pattern

Tách DTO khỏi Entity.

Không trả Entity ra API.

Sai:


public UserEntity create(...) { }

Đúng:


public UserResponse create(...) { }

9.6.3. Mapper pattern

Convert DTO ↔ Entity.


UserEntity entity = mapper.toEntity(request);

9.6.4. Exception pattern

Dùng BusinessException thống nhất.


throw new BusinessException(ErrorCode.USER_NOT_FOUND);

9.7. Cách thực hiện / quy trình

Quy trình tạo DTO đúng chuẩn

Bước 1: Tạo class DTO theo quy tắc đặt tên

Ví dụ:

  • UserCreateRequest

  • UserUpdateRequest

  • UserResponse


Bước 2: Thêm validation annotation

Bước 3: Dùng DTO trong controller


@PostMapping

public ApiResponse<UserResponse> create(

create(

@Valid @Valid @RequestBody UserCreateRequest request) {

    return ApiResponse.ok(userService.create(request));

}


Quy trình logging chuẩn

Bước 1: Khai báo logger trong class


private static final Logger log =

LoggerFactory.getLogger(UserService.class);


Bước 2: Dùng logger thay cho System.out.println

9.5.8. Ví dụ minh họa

Trường hợp sai


public class usercontroller {

public publicvoid void CreateUser(CreateUser() {

System.out.println("Create user");

}

}


Sai vì:

  • Tên class không đúng chuẩn

  • Tên method không camelCase

  • Dùng System.out.println

  • Không theo kiến trúc tầng

Trường hợp đúng


@RestController public class UserController {

private privatestatic staticfinal finalLogger Loggerlog log =

LoggerFactory.getLogger(UserController.class);

private final UserService userService; public voidUserController(UserService createUser()userService) {

this.userService = userService; } @PostMapping public ApiResponse<UserResponse> create( @Valid @RequestBody UserCreateRequest request) { log.info("Create user"user {}", request.getUsername());

return ApiResponse.ok(userService.create(request)); }

}


Ví dụ DTO sai


public class userDTO {

    public String name;

}

Sai vì:

  • Tên class không chuẩn

  • Không có validation

  • Field public

  • Không theo DTO pattern

Ví dụ DTO đúng


public class UserCreateRequest {

@NotBlank @NotBlank

    @Size(max = 255)

    private String name;

    public String getName(getName() { return name; }

public publicvoid void setName(setName(String name) { this.this.name = name; }

}

9.6.9. Checklist áp dụng


Trước khi commit hoặc tạo PR:

  • Tên class đúng chuẩn:

    • Naming

    •  Controller → *Controller

    •  Service → *Service

    •  Repository → *Repository

    •  Entity → *Entity

    •  DTO → *Request / *Response

    Coding

    •  Biến và method dùng camelCase

    •  Class dùng PascalCase

    •  Không dùng System.out.println

    •  Dùng logging chuẩn slf4j

    Validation

    •  DTO có validation annotation

  •  Không có field public trong DTO

SOLID

  •  Controller không chứa nghiệp vụ

  •  Service không chứa HTTP logic

  •  Repository chỉ truy vấn DB

  •  Inject interface, không new

  •  Class có 1 trách nhiệm

Architecture

  •  Không Controller → Repository

  •  Không trả Entity ra API

  •  Có DTO mapping

  •  Exception dùng chuẩn hệ thống

Lên đầu trang