Clean Architecture vừa đủ cho một dự án thực tế

Bắt đầu từ vấn đề, không phải thư mục#

Một codebase dễ thay đổi không được quyết định bởi số lượng thư mục. Nó được quyết định bởi việc mỗi thay đổi có thể dừng lại ở một ranh giới rõ ràng hay không. Hãy bắt đầu bằng một use case cụ thể: độc giả gửi một bình luận và quản trị viên duyệt nó.

Bài mẫu này minh họa cách tổ chức một ứng dụng nhỏ. Các quyết định cần được đánh giá lại theo đội ngũ, sản phẩm và môi trường vận hành; không có cấu trúc duy nhất phù hợp với mọi dự án.

Ba ranh giới cần giữ#

• Domain: quy tắc và dữ liệu, không biết HTTP hay cơ sở dữ liệu nào đang được dùng.

• Application: điều phối một hành động như gửi bình luận hoặc xuất bản bài viết.

• Infrastructure: thực hiện truy cập dữ liệu, gửi email và giao tiếp dịch vụ bên ngoài.

type CommentStatus = "pending" | "approved" | "rejected";

export async function submitComment(input: CommentInput) {
  const comment = validateComment(input);
  return repository.insert({
    ...comment,
    status: "pending", // Server quyết định trạng thái.
  });
}

Luồng dữ liệu đi qua đâu?#

Giao diện gửi dữ liệu đến API. API kiểm tra danh tính, quyền và giới hạn tần suất trước khi gọi nghiệp vụ. Repository lưu trạng thái chờ duyệt. Chỉ nội dung được duyệt mới được truy vấn công khai. Việc ẩn nút trong giao diện không thay thế kiểm tra quyền ở server.

Một abstraction hữu ích giúp thay đổi có phạm vi nhỏ hơn. Nếu nó chỉ làm bạn phải mở thêm ba file, hãy cân nhắc bỏ nó.

Khi nào nên tách thêm?#

Tách thêm khi có một lý do thay đổi độc lập: thêm provider email, thay cơ sở dữ liệu hoặc cần kiểm soát policy riêng. Khi chưa có bằng chứng, một service nhỏ và một adapter rõ ràng thường dễ hiểu hơn một framework tự viết.

Checklist trước khi mở pull request#

• Tên hàm diễn đạt hành động và dữ liệu đầu vào được kiểm tra.

• Không để secret hoặc quy tắc quyền truy cập trong browser.

• Lỗi có thông báo hữu ích nhưng không làm lộ thông tin nội bộ.

• Document giải thích quyết định và cách chạy, không lặp lại từng dòng code.

Nguồn tham khảo và bước tiếp theo#

Đọc thêm: The Clean Architecture — Robert C. Martin. Thử vẽ luồng một use case trong dự án của bạn trước khi đổi cấu trúc thư mục.