Chuyển tới nội dung chính

Quy tắc đặt tên phương thức cho Controller, Service, và Repository

Việc áp dụng một quy tắc đặt tên nhất quán trên toàn bộ dự án giúp giảm thiểu sự nhầm lẫn, tăng tốc độ phát triển và làm cho mã nguồn trở nên chuyên nghiệp hơn. Dưới đây là các quy tắc được khuyến nghị cho từng lớp trong kiến trúc Spring Boot.

1. Lớp Repository (Lớp truy cập dữ liệu)​

Lớp này chỉ có một nhiệm vụ: tương tác với cơ sở dữ liệu. Tên phương thức phải phản ánh rõ ràng hành động truy vấn dữ liệu.

1.1. Quy tắc​

  • Tuân thủ quy ước của Spring Data JPA: Tận dụng tối đa khả năng tự tạo truy vấn từ tên phương thức.
  • Bắt đầu bằng các tiền tố:
    • find..., read..., query..., get... để truy vấn dữ liệu.
    • count... để đếm số lượng bản ghi.
    • exists... để kiểm tra sự tồn tại.
    • delete... hoặc remove... để xóa dữ liệu.
  • Sử dụng By để ngăn cách các điều kiện truy vấn.

1.2. Ví dụ​

Mục đíchTên phương thức
Tìm một sản phẩm bằng IDOptional<Product> findById(Long id);
Tìm một sản phẩm bằng tênOptional<Product> findByName(String name);
Lấy tất cả sản phẩm theo danh mụcList<Product> findAllByCategory(Category category);
Đếm số sản phẩm trong kholong countByStockGreaterThan(int quantity);
Kiểm tra email đã tồn tại chưaboolean existsByEmail(String email);
Xóa tất cả sản phẩm hết hàngvoid deleteByIsAvailableFalse();

2. Lớp Service (Lớp nghiệp vụ)​

Đây là nơi chứa logic nghiệp vụ. Tên phương thức phải mô tả hành động hoặc quy trình nghiệp vụ mà nó thực hiện, không phải là một hành động CRUD đơn thuần.

2.1. Quy tắc​

  • Sử dụng động từ mạnh mẽ, mang tính nghiệp vụ: Tên phương thức nên trả lời câu hỏi "Phương thức này làm gì cho doanh nghiệp?".
  • Tránh các tên CRUD chung chung: Thay vì saveUser, hãy dùng registerNewUser hoặc updateUserProfile. Thay vì getOrder, hãy dùng getOrderDetail hoặc getPurchaseHistory.
  • Bao gồm cả đối tượng và hành động: (Động từ) + (Đối tượng/Ngữ cảnh).
  • Tên phương thức nên rõ ràng đến mức người không phải lập trình viên cũng có thể hiểu được mục đích của nó.

2.2. Ví dụ​

Mục đíchTên phương thức
Đăng ký một người dùng mớiUserDTO registerNewUser(SignUpRequest request);
Xử lý một đơn hàng mớiOrderDTO processNewOrder(CreateOrderRequest request);
Áp dụng mã giảm giá vào giỏ hàngCartDTO applyVoucherToCart(String voucherCode, Long cartId);
Hủy một đơn hàngvoid cancelOrder(Long orderId);
Lấy lịch sử mua hàng của người dùngList<OrderSummaryDTO> getPurchaseHistory(Long userId);
Tạo báo cáo doanh thu hàng thángMonthlySalesReport generateMonthlySalesReport(YearMonth month);

3. Lớp Controller (Lớp giao tiếp)​

Lớp này xử lý các yêu cầu HTTP. Tên phương thức nên phản ánh hành động của API và tài nguyên mà nó tác động, tuân thủ các nguyên tắc RESTful.

3.1. Quy tắc​

  • Gắn liền với các động từ HTTP:
    • GET: get..., find..., list..., search...
    • POST: create..., add..., register...
    • PUT / PATCH: update..., modify..., change...
    • DELETE: delete..., remove...
  • Bao gồm tên của tài nguyên: (Hành động) + (Tên tài nguyên).
  • Tên phương thức nên đơn giản và trực tiếp, vì ngữ cảnh đã được cung cấp bởi annotation (@GetMapping, @PostMapping...) và URL.

3.2. Ví dụ​

HTTP Method & URLTên phương thức
GET /api/products/{id}public ResponseEntity<ProductDTO> getProductById(@PathVariable Long id)
GET /api/productspublic ResponseEntity<List<ProductDTO>> getAllProducts()
POST /api/productspublic ResponseEntity<ProductDTO> createProduct(@RequestBody CreateProductRequest request)
PUT /api/products/{id}public ResponseEntity<ProductDTO> updateProduct(@PathVariable Long id, @RequestBody UpdateProductRequest request)
DELETE /api/products/{id}public ResponseEntity<Void> deleteProduct(@PathVariable Long id)
POST /api/auth/registerpublic ResponseEntity<?> registerUser(@RequestBody SignUpRequest request)

Bảng tổng hợp: Luồng hoạt động CRUD cho "Product"​

LớpTên phương thức (Ví dụ)Trách nhiệm
ControllercreateProduct(...)Nhận HTTP Request, xác thực DTO, gọi Service.
ServiceaddNewProduct(...)Xử lý logic nghiệp vụ (kiểm tra tên trùng, tạo slug...), gọi Repository.
Repositorysave(Product product)Lưu đối tượng Product vào cơ sở dữ liệu.
ControllergetProductById(...)Nhận HTTP Request, gọi Service.
ServicegetProductDetails(...)Lấy dữ liệu từ Repository, xử lý (nếu cần), map sang DTO.
RepositoryfindById(Long id)Tìm Product trong cơ sở dữ liệu bằng ID.

Việc tuân thủ các quy tắc này sẽ giúp kiến trúc ứng dụng của bạn trở nên rõ ràng, dễ bảo trì và phát triển sau này.