Hexagonal Architecture (Ports and Adapters)

Kiến trúc tách lõi nghiệp vụ (Domain Core) khỏi thế giới bên ngoài (DB, HTTP, payment gateway, email). Một kiến trúc cũ bỗng cực hợp thời AI.

   Adapters (driving)   ← HTTP, CLI, gRPC
          │ ports (input)
   Domain Core          ← business logic (Use Case + Entity)
          │              không biết về DB/HTTP
          │ ports (output)
   Adapters (driven)    ← DB, payment gateway, email

• Domain Core chứa rule nghiệp vụ (Order, PlaceOrder, rule “QR hết hạn sau 15 phút”). Không cần biết Postgres, REST, Stripe hay Sendgrid.
• Port là interface cho nhu cầu của domain (lưu Order, gửi email, verify payment).
• Adapter là hiện thực cụ thể (PostgresOrderRepository, StripePaymentAdapter).

Vì sao hợp với AI

Bạn có thể để AI viết lại adapter mà không động vào lõi nghiệp vụ. Ví dụ đổi Stripe → Adyen: nếu code theo hexagonal, chỉ viết adapter mới + đổi config, domain gần như không đổi. Spec vẫn nói “thanh toán bằng QR”, domain test vẫn giữ nguyên. Đó là vùng AI rất giỏi: ranh giới rõ, input/output rõ, ít quyết định nghiệp vụ.

SDD và Hexagonal khớp nhau tự nhiên

Khi viết spec theo SDD, bạn gián tiếp vẽ ra cấu trúc hexagonal:

• Mỗi Use Case (UC) ≈ một use case trong domain core.
• Mỗi Entity ≈ một aggregate root hoặc value object.
• Mỗi tích hợp ra ngoài ≈ một port với adapter đổi được theo môi trường.

Khi nào CHƯA cần

Script một lần dùng, CRUD admin thuần, prototype - đừng thiết kế quá tay. Quy tắc: nếu hệ thống có rule nghiệp vụ không tầm thường, sống quá 6 tháng, hoặc hơn 2 dev cùng làm → đầu tư DDD nhẹ kèm Hexagonal.

Liên quan

• Port và Adapter - hai thành phần chính
• Bounded Context - DDD chia nghĩa, Hexagonal đặt code đúng chỗ
• Spec-Driven Development - spec map tự nhiên sang cấu trúc này
• Test-Protected - domain test bảo vệ lõi khi AI viết lại adapter