coding convention và chuẩn mực java

# CẤU TRÚC PHÂN TẦNG CỔ ĐIỂN (ANTI-PATTERN CHO MICROSERVICES HIỆN ĐẠI)
com.company.project/
├── controller/
│   ├── UserController.java
│   └── OrderController.java
├── service/
│   ├── UserService.java
│   ├── OrderService.java
│   └── impl/
│       ├── UserServiceImpl.java   <-- Chỉ có đúng 1 implementation duy nhất!
│       └── OrderServiceImpl.java  <-- Tạo interface thừa thãi, phá vỡ YAGNI!
├── repository/
└── model/

com.company.order/
├── domain/             # Thuần POJO: Business Logic, Domain Exceptions
│   ├── Order.java
│   └── Money.java
├── application/        # UseCases / Application Services
│   ├── PlaceOrderUseCase.java
│   └── OrderResponseDto.java
└── infrastructure/     # Spring Controllers, JPA Repositories, Kafka Adapters
    ├── OrderRestController.java
    └── JpaOrderRepository.java

package com.tungdadev.payment;
 
import org.jspecify.annotations.NullMarked;
import org.jspecify.annotations.Nullable;
 
@NullMarked // Mọi kiểu trong class mặc định là non-null
public class PaymentProcessor {
 
    // Tham số bắt buộc không được null, kết quả có thể null
    public @Nullable TransactionResult process(
            PaymentRequest request,
            @Nullable DiscountCode discount) {
 
        // NullAway sẽ báo lỗi biên dịch ngay tại đây nếu bạn gọi discount.apply()
        // mà chưa kiểm tra null!
        if (discount != null) {
            request.applyDiscount(discount.percentage());
        }
        return execute(request);
    }
}

public record UserGroup(String groupId, List<String> memberIds) {
    // Compact constructor thực hiện Defensive Copying
    public UserGroup {
        memberIds = List.copyOf(memberIds); // Tạo bản sao bất biến, chống side-effect từ bên ngoài!
    }
}

@RestControllerAdvice
public class GlobalExceptionHandler {
 
    @ExceptionHandler(InsufficientFundsException.class)
    public ProblemDetail handleInsufficientFunds(InsufficientFundsException ex, HttpServletRequest req) {
        ProblemDetail problem = ProblemDetail.forStatusAndDetail(
                HttpStatus.UNPROCESSABLE_ENTITY, ex.getMessage());
        problem.setTitle("Tài Khoản Không Đủ Số Dư");
        problem.setType(URI.create("https://api.tungdadev.com/errors/insufficient-funds"));
        problem.setProperty("currentBalance", ex.getBalance());
        problem.setProperty("requiredAmount", ex.getRequired());
        problem.setProperty("traceId", MDC.get("traceId"));
        problem.setProperty("timestamp", Instant.now());
        return problem;
    }
}

{
  "type": "https://api.tungdadev.com/errors/insufficient-funds",
  "title": "Tài Khoản Không Đủ Số Dư",
  "status": 422,
  "detail": "Giao dịch 500,000 VND bị từ chối do số dư hiện tại chỉ còn 120,000 VND",
  "instance": "/api/v1/wallets/transfer",
  "currentBalance": 120000,
  "requiredAmount": 500000,
  "traceId": "c8a1b2c3-4d5e-6f7a",
  "timestamp": "2026-03-26T21:40:00Z"
}

package com.tungdadev.architecture;
 
import com.tngtech.archunit.core.importer.ImportOption;
import com.tngtech.archunit.junit.AnalyzeClasses;
import com.tngtech.archunit.junit.ArchTest;
import com.tngtech.archunit.lang.ArchRule;
import org.springframework.stereotype.Service;
import org.springframework.web.bind.annotation.RestController;
 
import static com.tngtech.archunit.lang.syntax.ArchRuleDefinition.*;
import static com.tngtech.archunit.library.Architectures.layeredArchitecture;
import static com.tngtech.archunit.library.dependencies.SlicesRuleDefinition.slices;
 
@AnalyzeClasses(packages = "com.tungdadev", importOptions = ImportOption.DoNotIncludeTests.class)
public class ArchitectureFitnessTest {
 
    // QUY TẮC 1: CẤM Field Injection (@Autowired) - Bắt buộc dùng Constructor Injection
    @ArchTest
    public static final ArchRule no_field_injection = noFields()
            .should().beAnnotatedWith("org.springframework.beans.factory.annotation.Autowired")
            .because("Field injection phá vỡ tính bao đóng và gây khó khăn khi viết Unit Test. Bắt buộc dùng Constructor Injection!");
 
    // QUY TẮC 2: Tầng Controller KHÔNG ĐƯỢC PHÉP truy cập trực tiếp tầng Repository
    @ArchTest
    public static final ArchRule controllers_must_not_access_repositories = noClasses()
            .that().resideInAPackage("..controller..")
            .should().dependOnClassesThat().resideInAPackage("..repository..")
            .because("Controller chỉ được phép giao tiếp qua UseCase/Service, không được truy cập trực tiếp hạ tầng lưu trữ!");
 
    // QUY TẮC 3: Tầng Domain phải thuần khiết (Hexagonal Core Isolation)
    @ArchTest
    public static final ArchRule domain_model_must_be_pure_java = classes()
            .that().resideInAPackage("..domain..")
            .should().onlyDependOnClassesThat().resideInAnyPackage(
                    "java..",
                    "org.jspecify..",
                    "..domain.."
            )
            .because("Tầng Domain là tài sản cốt lõi của doanh nghiệp, không được phụ thuộc vào Spring, Hibernate hay bên thứ ba!");
 
    // QUY TẮC 4: Cấm chu trình phụ thuộc vòng (Cyclic Dependencies) giữa các package
    @ArchTest
    public static final ArchRule no_cyclic_dependencies = slices()
            .matching("com.tungdadev.(*)..")
            .should().beFreeOfCycles()
            .because("Cyclic dependencies biến codebase thành Spaghetti Code và làm vỡ cấu trúc module!");
}

// build.gradle.kts - Tự động định dạng code với Spotless theo chuẩn Google Java Style
// (version ở thời điểm viết bài, nên kiểm tra bản mới nhất)
plugins {
    id("com.diffplug.spotless") version "6.25.0"
}
 
spotless {
    java {
        googleJavaFormat("1.22.0").aosp() // Chuẩn Google với thụt lề 4 spaces
        removeUnusedImports()
        trimTrailingWhitespace()
        endWithNewline()
    }
}