Clean Architecture với Golang on Thanh HV's Blog

Chương 14 — Level 4 Principal: Evolutionary Architecture, Refactor Legacy, Tổ chức & Hiệu năng

Wed, 08 Jul 2026 15:00:00 +0700

Level 4 – Principal · Ở cấp này, kiến trúc không còn là bài toán code — nó là bài toán thời gian (hệ thống tiến hóa), con người (team, ownership) và kinh tế (chi phí, rủi ro, thứ tự đầu tư).

1. Evolutionary Architecture — thiết kế cho sự thay đổi của chính kiến trúc

Sai lầm cấp principal phổ biến nhất: thiết kế “kiến trúc đích” 5 năm rồi ép hệ thống về nó. Thực tế: nghiệp vụ, tổ chức và công nghệ đều thay đổi nhanh hơn kế hoạch 5 năm. Kiến trúc tiến hóa (Ford/Parsons/Kua) đảo cách đặt vấn đề: thay vì đoán đích đúng, tối ưu chi phí đổi hướng.

Chương 13 — So sánh khách quan: Clean vs Layered vs Hexagonal vs Onion vs MVC vs Modular Monolith vs DDD

Wed, 08 Jul 2026 14:00:00 +0700

Level 3–4 · Mục tiêu: thoát khỏi tranh cãi danh pháp, chọn theo bài toán.

1. Khung so sánh

Mỗi “kiến trúc” thực chất trả lời một tập câu hỏi khác nhau — so sánh chỉ công bằng khi đặt đúng tầng câu hỏi:

Tầng tổ chức phụ thuộc trong một đơn vị deploy: Layered, Hexagonal, Onion, Clean.
Tầng tổ chức delivery/UI: MVC.
Tầng topology hệ thống: Modular Monolith (và Microservices).
Tầng mô hình hóa nghiệp vụ: DDD.

Chúng không loại trừ nhau — một hệ thống có thể đồng thời là: modular monolith (topology) × Clean Architecture (phụ thuộc) × DDD (mô hình) × MVC (trong tầng delivery).

Chương 12.3 — E-commerce · Giai đoạn 3: Tách service khi tổ chức đòi hỏi

Wed, 08 Jul 2026 13:00:00 +0700

Năm thứ 4: 40 engineer, 6 team, 500 nghìn đơn/ngày. Đây là chương về lý do đúng và lý do sai để tách, cùng kỹ thuật tách không ngừng hệ thống.

1. Khi nào monolith thật sự hết vai trò

Lý do đúng (xuất hiện ở công ty này):

Deploy coupling thành nút cổ chai tổ chức: 6 team xếp hàng chung một release train; một bug của team Catalog rollback cả deploy chứa hotfix của team Payment. Chi phí phối hợp tăng theo bình phương số team.
Chênh lệch tải & tài nguyên: đường search catalog cần 40 pod CPU cao vào giờ vàng; đường payment cần ổn định tuyệt đối và audit riêng (PCI-DSS) — chung binary nghĩa là scale cả cụm theo nhu cầu của phần nóng nhất, và mọi engineer đều “ở trong phạm vi audit”.
Bán kính sự cố: memory leak trong module notification OOM-kill cả tiến trình chứa payment.

Lý do sai (đã bị bác trong design review): “microservices hiện đại hơn”, “để dùng ngôn ngữ mới”, “CV-driven”. Phép thử: nếu tách xong mà số team, quy trình deploy và yêu cầu scale y nguyên — bạn vừa mua độ trễ mạng và partial failure mà không mua được gì.

Chương 12.2 — E-commerce · Giai đoạn 2: Modular Monolith

Wed, 08 Jul 2026 12:00:00 +0700

18 tháng sau: 12 engineer chia 3 team, 50 nghìn đơn/ngày. Các vết nứt giai đoạn 1 giờ đau thật. Câu trả lời KHÔNG phải microservices — mà là siết ranh giới trong chính monolith.

Bối cảnh và triệu chứng

Team Payment muốn thêm VNPay + trả góp; mỗi lần sửa đụng order.Service.Place — file mà team Order cũng đang sửa hàng ngày. Merge conflict, release phải phối hợp.
Marketing cần: gửi email sau đặt hàng, cộng điểm loyalty, đồng bộ CRM — ba team khác nhau cùng đòi chen code vào Place(). Hàm 40 dòng thành 180 dòng.
Sự cố “charge rồi mất đơn” xảy ra thật 7 lần trong tháng cao điểm — mỗi lần một buổi điều tra + hoàn tiền thủ công.
Query dashboard người bán làm chậm cả đường ghi (chung DB, khóa lẫn nhau).

Chẩn đoán đúng bệnh trước khi kê đơn: vấn đề là ranh giới module chưa đủ chặt và coupling thời gian trong Place() — không phải “vì chưa có microservices”. Tách process bây giờ sẽ nhân các vấn đề trên với độ trễ mạng và partial failure. Modular monolith: giữ một binary, nâng ranh giới lên chuẩn “như thể sắp tách”.

Chương 12.1 — E-commerce từng bước · Giai đoạn 1: Monolith khởi đầu đúng cách

Wed, 08 Jul 2026 11:00:00 +0700

Ví dụ tổng hợp · Ba giai đoạn của cùng một hệ thống: (1) monolith gọn, (2) modular monolith khi nghiệp vụ dày lên, (3) tách service khi tổ chức đòi hỏi. Mỗi giai đoạn là quyết định có bối cảnh — không phải giai đoạn sau “xịn hơn” giai đoạn trước.

Bối cảnh giai đoạn 1

Startup 3 engineer, 3 tháng để ra MVP bán hàng: đăng ký user, danh mục sản phẩm, đặt hàng, thanh toán qua một cổng (giả định “MoPay”). Chưa rõ nghiệp vụ sẽ phát triển hướng nào.

Chương 11 — Production Concerns: Logging, Config, Observability, Shutdown, Retry, Idempotency

Wed, 08 Jul 2026 10:00:00 +0700

Level 3–4 · Kiến trúc đẹp mà không vận hành được là bài tập trên giấy. Chương này trả lời: các concern vận hành nằm ở vòng nào, và viết thế nào để chúng không ăn mòn ranh giới.

Nguyên tắc chung của cả chương: concern vận hành là cross-cutting → sống ở adapter/middleware/decorator/composition root; vòng trong cùng lắm biết khái niệm (context, error), không bao giờ biết công cụ (Prometheus, OTel, Viper).

Chương 10 — Clean Architecture & CQRS: Đường ghi và đường đọc

Wed, 08 Jul 2026 09:00:00 +0700

Level 3 – Senior · CQRS thường bị hiểu là “kiến trúc phức tạp với event sourcing và 2 database”. Bản chất nó khiêm tốn và hữu ích hơn nhiều.

1. Problem Statement

Hai áp lực kéo model về hai hướng ngược nhau:

Đường ghi (command) cần model giàu: aggregate, bất biến, rule — Order.AddLine() phải kiểm tra trạng thái, tính lại tổng (chương 9).
Đường đọc (query) cần dữ liệu phẳng, join sẵn, đúng hình dạng màn hình: “danh sách đơn + tên khách + số item + trạng thái thanh toán, phân trang, lọc theo 5 tiêu chí”.

Ép một model phục vụ cả hai tạo ra hai loại đau: (a) đường đọc qua aggregate: load N aggregate đầy đủ + N query phụ để render một cái bảng — chậm và code repository mọc FindAllWithCustomerNameAndPaymentStatus(...) vô tận; (b) aggregate phình theo nhu cầu đọc: thêm field chỉ để hiển thị, bất biến loãng dần.

Chương 9 — Clean Architecture & DDD: Lấp đầy vòng trong

Wed, 08 Jul 2026 08:00:00 +0700

Level 3 – Senior · Clean Architecture cho bạn cái vỏ (ranh giới, hướng phụ thuộc); DDD cho bạn cái ruột (mô hình hóa nghiệp vụ bên trong vòng domain). Thiếu một trong hai: vỏ đẹp ruột rỗng, hoặc mô hình hay bị hạ tầng ăn mòn.

1. Problem Statement

Clean Architecture nói “đặt business rule vào vòng trong” nhưng không nói business rule trông như thế nào. Hệ quả phổ biến: team dựng đủ 4 tầng, rồi vòng domain chỉ chứa struct trần (anemic model), toàn bộ logic dồn vào “service” — tức Transaction Script khoác áo Clean Architecture, trả phí kiến trúc mà không nhận mô hình.

Chương 8 — Testing Strategy: Unit, Integration, Mock vs Fake, Testcontainers

Wed, 08 Jul 2026 07:00:00 +0700

Level 3 – Senior · Testability không phải phần thưởng phụ của Clean Architecture — nó là bằng chứng kiến trúc đúng. Kiến trúc không test được là kiến trúc sai, bất kể sơ đồ đẹp đến đâu.

1. Problem Statement

Hai thái cực thất bại phổ biến:

Test kim tự tháp ngược: 500 E2E test dựng cả hệ thống, chạy 40 phút, flaky 5% — CI thành xổ số, dev tắt test để merge. Nguyên nhân gốc: nghiệp vụ dính hạ tầng nên chỉ có thể test kiểu E2E.
Mock hóa toàn phần: mock mọi thứ kể cả struct nội bộ, assert từng lời gọi hàm — test khẳng định code viết như thế nào thay vì hệ thống làm gì. Refactor giữ nguyên hành vi vẫn vỡ 200 test → test trở thành lực cản refactor, phản bội chính mục đích của nó.

Chiến lược đúng bám vào cấu trúc các vòng: mỗi vòng một loại test, chi phí thấp nhất có thể cho độ tin cần thiết.

Chương 7 — Integration: Kafka, RabbitMQ, Redis, External API, Event Publishing

Wed, 08 Jul 2026 06:00:00 +0700

Level 3 – Senior · Ranh giới với thế giới bên ngoài — nơi lỗi, độ trễ và bất nhất là chuyện thường ngày.

1. Problem Statement

Hệ thống thực không sống một mình: nó gọi cổng thanh toán, phát event cho hệ thống khác, cache bằng Redis, nhận lệnh từ queue. Ba rủi ro kiến trúc:

Kiến thức về hệ ngoài rò vào nghiệp vụ: use case biết tên topic Kafka, format JSON của đối tác, TTL Redis → đổi đối tác/hạ tầng là mổ nghiệp vụ.
Đặc tính mạng rò vào nghiệp vụ: retry, timeout, circuit breaker viết lẫn trong use case → quy trình nghiệp vụ chìm trong code chống lỗi.
Bất nhất dữ liệu: ghi DB xong, publish event fail — hai hệ thống từ nay lệch nhau vĩnh viễn (bài toán dual-write).

Cấu trúc lời giải cho cả ba giống nhau — cũng là cấu trúc của cả tài liệu này: vòng trong khai báo cổng theo ngôn ngữ nghiệp vụ; adapter vòng ngoài gánh mọi đặc tính của công nghệ cụ thể.

Chương 6 — Delivery Layer: HTTP, gRPC, GraphQL, CLI, Worker

Wed, 08 Jul 2026 05:00:00 +0700

Level 2–3 · Bài kiểm tra thật sự của Clean Architecture: cùng một use case phục vụ N cách vào mà không đổi một dòng nghiệp vụ.

1. Problem Statement

Hệ thống trưởng thành hiếm khi chỉ có một cửa vào. Cùng nghiệp vụ “đổi điểm”: mobile app gọi REST, service nội bộ gọi gRPC, chiến dịch marketing chạy batch qua CLI, và một Kafka consumer đổi điểm tự động khi có event mua hàng. Nếu nghiệp vụ viết trong HTTP handler, ba cửa còn lại chỉ có hai lựa chọn tồi: copy-paste logic, hoặc giả lập HTTP request nội bộ (gọi chính API của mình) — cả hai đều là nợ.

Chương 5 — Data Access: Repository, Transaction, Unit of Work, ORM vs SQL

Wed, 08 Jul 2026 04:00:00 +0700

Level 3 – Senior · Data access là nơi Clean Architecture bị thử thách gay gắt nhất trong thực tế — transaction, N+1, mapping — và là nơi nhiều dự án gãy.

1. Problem Statement

Ba bài toán mà mọi hệ thống phải giải, và giải sai thì Dependency Rule sụp:

Nghiệp vụ cần dữ liệu nhưng không được biết SQL — ai đứng giữa? (Repository)
Một use case ghi nhiều bảng phải atomic — transaction là khái niệm hạ tầng, sao use case điều khiển được nó mà không import database/sql? (bài toán khó nhất chương)
Model của DB và model của domain khác nhau đến đâu thì tách? (ORM vs SQL, mapping)

2. Repository Pattern — bản chất thật

Repository không phải “class bọc mấy câu SQL”. Định nghĩa gốc (Evans/Fowler): ảo giác một collection trong bộ nhớ chứa các domain object — nghiệp vụ “lấy ra, thao tác, đặt lại”, không biết đằng sau là Postgres hay RAM.

Chương 4 — Dependency Injection trong Go: Manual, Wire, Fx và Interface Placement

Wed, 08 Jul 2026 03:00:00 +0700

Level 2–3 · DI là cơ chế thi công của Dependency Rule: mọi mũi tên đã đảo ở thiết kế phải được nối lại ở runtime — chương này bàn nối ở đâu, bằng gì.

1. Problem Statement

Sau khi áp dụng DIP, các component chỉ biết interface. Nhưng lúc chạy, ai đó phải quyết định order.Service dùng postgres.WalletRepo hay mongo.WalletRepo, và tạo chúng theo đúng thứ tự với đúng config. Câu hỏi của chương: việc lắp ráp đó viết thế nào để (a) tường minh, (b) không rò rỉ kiến thức lắp ráp vào nghiệp vụ, (c) không thành 500 dòng spaghetti trong main.go khi hệ thống lớn?

Chương 3.1 — Tổ chức Package trong Go: cmd/, internal/, pkg/ và các trường phái

Wed, 08 Jul 2026 02:00:00 +0700

Level 2–3 · Chương này trả lời câu hỏi thực dụng nhất: “project của tôi nên có cấu trúc thư mục thế nào?” — nhưng bằng nguyên lý, không bằng template.

1. Problem Statement

Go không quy định cấu trúc project (khác Rails/Django). Tự do này tạo ra hai thái cực lỗi:

Thiếu cấu trúc: mọi thứ trong một package main 20.000 dòng, hoặc chia file tùy hứng — không có ranh giới nào để compiler bảo vệ.
Thừa cấu trúc: bê nguyên template “golang-standard-project-layout” hay “clean-architecture-template” trên GitHub về cho một service 3 endpoint — 40 thư mục, mỗi feature chạm 9 file, team ghét kiến trúc từ đó.

Cả hai đều xuất phát từ việc coi cấu trúc thư mục là mục tiêu thay vì hệ quả của các quyết định ranh giới (chương 1.1) và hướng phụ thuộc (chương 2.2).

Chương 2.3 — Bốn vòng trong Go: từ Entity đến Framework

Wed, 08 Jul 2026 01:00:00 +0700

Level 2 – Engineering · Chương này dựng một service hoàn chỉnh, chạy được, minh họa cả bốn vòng.

Bài toán xuyên suốt: service quản lý ví điểm thưởng (loyalty wallet) — nghiệp vụ đủ thật để có rule, đủ nhỏ để đọc hết:

Khách tích điểm khi mua hàng (1 điểm / 10.000 VND, hạng GOLD nhân đôi).
Đổi điểm lấy voucher; không cho âm điểm; mỗi ngày đổi tối đa 3 lần.

1. Vòng 1 — Entities (Enterprise Business Rules)

Bản chất

Entity chứa quy tắc đúng bất kể ứng dụng nào dùng nó — quy tắc sẽ tồn tại kể cả khi công ty vận hành bằng giấy bút: “điểm không âm”, “GOLD nhân đôi”. Nó không biết use case nào gọi nó, không biết dữ liệu từ đâu đến.

Chương 2.2 — Dependency Rule: Luật duy nhất

Wed, 08 Jul 2026 00:00:00 +0700

Level 2 – Engineering · Nếu chỉ được nhớ một điều từ toàn bộ tài liệu, hãy nhớ chương này.

1. Phát biểu

Source code dependencies must point only inward, toward higher-level policies. Phụ thuộc mã nguồn chỉ được trỏ vào trong, về phía chính sách cấp cao hơn.

“Biết” ở đây nghĩa là bất kỳ dạng nào sau: câu lệnh import; dùng kiểu dữ liệu của vòng ngoài trong chữ ký hàm/field; tham chiếu tên hàm, hằng số, biến; và cả những dạng không có import: hiểu ngầm về format JSON của API, về schema bảng, về tên topic Kafka, về mã lỗi HTTP. Dependency Rule cấm tất cả — vòng trong phải có thể compile, test, và đọc hiểu mà không cần vòng ngoài tồn tại.

Chương 2.1 — Vì sao Clean Architecture ra đời

Tue, 07 Jul 2026 23:00:00 +0700

Level 2 – Engineering · Yêu cầu: đã hoàn thành Level 1.

1. Problem Statement: câu chuyện lặp lại của mọi hệ thống

Robert C. Martin công bố bài viết “The Clean Architecture” năm 2012, đúc kết từ hàng thập kỷ quan sát một vòng đời lặp đi lặp lại:

Năm 1: team chọn framework hot nhất (Rails/Spring/Django — ngày nay có thể là một “boilerplate Gin + GORM”). Framework quyết định cấu trúc project. Tốc độ ban đầu tuyệt vời — CRUD sinh ra trong vài giờ.

Chương 1.4 — Separation of Concerns & Composition over Inheritance

Tue, 07 Jul 2026 22:00:00 +0700

Level 1 – Foundation · Hai nguyên lý cuối của phần nền tảng.

Phần A — Separation of Concerns (SoC)

1. Problem Statement

Một hàm handler điển hình trong dự án “chạy được là được”:

func CreateOrder(w http.ResponseWriter, r *http.Request) {
 // 1. Parse JSON (concern: giao thức)
 // 2. Validate input (concern: hợp lệ dữ liệu vào)
 // 3. Check quyền user (concern: bảo mật)
 // 4. Tính giá, áp khuyến mãi (concern: NGHIỆP VỤ)
 // 5. Mở transaction, ghi 3 bảng (concern: lưu trữ, nhất quán)
 // 6. Ghi log, đẩy metric (concern: vận hành)
 // 7. Render JSON response (concern: giao thức)
}

Bảy mối quan tâm (concern), bảy tốc độ thay đổi khác nhau, bảy loại chuyên môn khác nhau — trộn trong một hàm. Muốn sửa một concern phải đọc và hiểu cả bảy; muốn test concern 4 phải dựng đủ 1–7. Đây là dạng tổng quát của mọi vấn đề đã nêu ở các chương trước.

Chương 1.3 — Dependency Inversion: Cỗ máy đảo chiều phụ thuộc

Tue, 07 Jul 2026 21:00:00 +0700

Level 1–2 Bridge · Đây là chương kỹ thuật then chốt. Toàn bộ Clean Architecture đứng trên một cơ chế duy nhất được trình bày ở đây.

1. Problem Statement

Bài toán

Business logic là tài sản quý nhất của hệ thống: nó mã hóa cách doanh nghiệp kiếm tiền, nó sống 10 năm trong khi framework HTTP sống 3 năm và fashion database đổi mỗi 5 năm. Vấn đề: theo cách viết code tự nhiên, thứ quý nhất lại phụ thuộc vào thứ dễ thay đổi nhất.

Chương 1.2 — SOLID trong Go: Năm quy tắc quản trị phụ thuộc

Tue, 07 Jul 2026 20:00:00 +0700

Level 1 – Foundation · Yêu cầu: đã đọc Coupling & Cohesion

1. Problem Statement

Chương trước kết luận: kiến trúc tốt = coupling thấp + cohesion cao. Nhưng đó là đại lượng đo, không phải quy tắc hành động. Khi đứng trước một PR, engineer cần câu trả lời cụ thể: struct này nên tách không? Interface đặt ở đâu? Thêm case vào switch này có ổn không?

SOLID (Robert C. Martin tổng hợp, đầu những năm 2000) là năm quy tắc hành động trả lời chính xác các câu hỏi đó. Không có SOLID, mỗi engineer quyết định theo cảm tính → codebase thành tập hợp các phong cách mâu thuẫn, review kiến trúc thành tranh cãi ý kiến cá nhân.

Chương 1.1 — Coupling & Cohesion: Gốc rễ của mọi vấn đề kiến trúc

Tue, 07 Jul 2026 19:00:00 +0700

Level 1 – Foundation · Đối tượng: Backend Engineer trở lên Đây là chương quan trọng nhất của toàn bộ tài liệu. Nếu bạn hiểu sâu coupling và cohesion, mọi pattern phía sau — SOLID, Dependency Rule, Clean Architecture, DDD — chỉ là hệ quả logic.

1. Problem Statement

Bài toán kinh doanh

Hãy bắt đầu từ một tình huống có thật, không phải từ lý thuyết.

Một công ty e-commerce có hệ thống đặt hàng viết bằng Go, chạy tốt trong 2 năm đầu. Đến năm thứ 3:

Clean Architecture với Golang — Từ First Principles đến Production

Tue, 07 Jul 2026 18:00:00 +0700

Tài liệu chuyên sâu dành cho Backend Engineer → Software Architect. Ngôn ngữ minh họa: Go 1.22+, ưu tiên Standard Library. Triết lý: hiểu bản chất và trade-off, không sao chép template.

Cách đọc

Tài liệu được viết theo chuỗi nhân quả — mỗi chương đứng trên chương trước:

Business Problem → Vì sao code khó bảo trì → Coupling → Dependency → SOLID
→ Clean Architecture ra đời → Dependency Rule → Layer → Production
→ Trade-off → Khi nào KHÔNG nên áp dụng

Người mới nên đọc tuần tự. Người có kinh nghiệm có thể nhảy thẳng vào Level 3–4, nhưng nếu thấy một kết luận thiếu căn cứ — căn cứ nằm ở Level 1.