[Series AI] Hexagonal Architecture và Demo Implementation

Chào anh em! Rất vui vì anh em vẫn đồng hành cùng mình đến Bài 6 của series Cursor AI for Developers.

Hôm nay chúng ta sẽ bước vào một chủ đề "nặng đô" hơn nhưng lại cực kỳ thú vị: Hexagonal Architecture (Kiến trúc Lục giác). Nếu anh em đã từng nghe qua Clean Architecture hay Onion Architecture thì Hexagonal (hay còn gọi là Ports and Adapters) chính là "nguyên bản" giúp tách biệt hoàn toàn Logic nghiệp vụ khỏi sự phụ thuộc vào công nghệ.

Là một Backend Dev, mình cực kỳ thích kiến trúc này vì nó giúp code của mình trở nên "bất tử" trước những thay đổi của database hay third-party. Và hôm nay, mình sẽ chỉ cho anh em cách Cursor AI giúp chúng ta hiện thực hóa cái kiến trúc "cồng kềnh" này một cách cực kỳ nhanh gọn.

1. Hexagonal Architecture là gì? Tại sao lại là "Lục giác"?

Cốt lõi của Hexagonal là: Ứng dụng của bạn nên được bao bọc bởi một lớp vỏ, để Logic nghiệp vụ bên trong không cần quan tâm bên ngoài là cái gì.

• Inside (The Core): Chứa Domain Model và Business Logic. Nó không biết đến sự tồn tại của Database, Web Server hay bất kỳ API bên thứ ba nào.
• Outside (The Infrastructure): Chứa Database (PostgreSQL, MongoDB), UI (REST API, CLI), Message Broker...
• Ports (Cổng): Là các Interface định nghĩa cách Inside giao tiếp với Outside.
• Adapters (Bộ chuyển đổi): Là các lớp hiện thực (implementation) cụ thể cho từng Port.

Ví dụ: Bạn có một cái "Port" để lưu User. "Adapter" có thể là SQL Adapter (lưu vào Postgres) hoặc Memory Adapter (lưu vào RAM để chạy Test).

2. Tại sao Cursor AI lại là "cặp bài trùng" với Hexagonal?

Thú thật, điểm yếu lớn nhất của Hexagonal là Boilerplate code. Bạn phải tạo quá nhiều Interface (Ports), DTO và các lớp chuyển đổi (Adapters). Nếu gõ tay thì cực kỳ nản.

Nhưng với Cursor AI, chúng ta chỉ cần tập trung vào "The Core", phần còn lại để AI lo.

3. Thực chiến: Demo Implementation với Cursor

Giả sử chúng ta build một module Payment Processing.

Bước 1: Định nghĩa Domain & Port (The Core)

Mình mở Cursor và viết vào file payment.port.ts:

"Tạo một Interface IPaymentPort với method processPayment. Định nghĩa một Domain Entity Payment chứa thông tin amount, currency và status."

Bước 2: Dùng Cursor Composer tạo Adapters

Sau khi có Port, mình dùng Cmd + I (Composer) và ra lệnh:

"Dựa trên @IPaymentPort, hãy tạo cho tôi hai Adapters:

1. StripeAdapter: Gọi đến Stripe API để thanh toán.

2. PaypalAdapter: Gọi đến Paypal SDK.

Đảm bảo cả hai đều implements đúng Interface và handle lỗi theo chuẩn của project."*

Chỉ trong vài giây, Cursor sẽ tự động tạo ra cấu trúc thư mục /adapters/stripe và /adapters/paypal với đầy đủ logic xử lý mà anh em không cần nhớ cú pháp SDK của từng bên.

Bước 3: Dependency Injection (Gắn kết các mảnh ghép)

Bây giờ, làm sao để ứng dụng biết dùng Adapter nào? Mình bảo Cursor:

"Tạo một file payment.service.ts thuộc Application layer. Service này sẽ nhận vào IPaymentPort thông qua Constructor (Dependency Injection). Viết logic xử lý thanh toán và ghi log sau khi thành công."

4. Thành quả: Sự linh hoạt tuyệt đối

Anh em thấy đó, nhờ sự trợ giúp của Cursor:

• Nếu sếp bảo: "Thôi không dùng Stripe nữa, chuyển qua VNPay đi". Bạn chỉ cần bảo Cursor: "Dựa vào @IPaymentPort, viết cho tôi VNPayAdapter". Logic nghiệp vụ ở Core không hề thay đổi một dòng code nào.
• Việc viết Unit Test cũng cực kỳ dễ dàng bằng cách tạo một MockPaymentAdapter.

5. Tạm kết bài 6

Hexagonal Architecture không còn là nỗi ác mộng về số lượng file nếu anh em biết tận dụng Cursor AI. Nó giúp chúng ta giữ vững nguyên tắc: "Phụ thuộc vào cái trừu tượng (Port), đừng phụ thuộc vào cái cụ thể (Adapter)".

Teaser Bài Tiếp Theo:

Kiến trúc Lục giác rất hay, nhưng làm sao để mỗi khi bảo AI viết một tính năng mới, nó tự biết file nào nằm ở lớp Domain, file nào nằm ở lớp Infrastructure mà không cần mình nhắc lại? Làm sao để nó tự động "áp" các quy tắc của từng lớp (Layer) vào code?

Ở bài tới, mình sẽ hướng dẫn anh em cách "nâng cấp" file .cursorrules lên một tầm cao mới – Rules theo từng Layer.

👉 [Series Cursor AI - Bài 7] Buổi 7 – Cursor Rules và Demo cho Architecture Layers

Anh em đã bao giờ phải khổ sở khi đổi Database cho dự án chưa? Thử áp dụng Hexagonal và chia sẻ trải nghiệm với mình ở dưới comment nhé!