Cụm bài Tài liệu kiến trúc: 1. arc42, C4 và docs-as-code · 2. ADR, quality requirement và ví dụ address component
Code cho biết hệ thống làm gì, nhưng không cho biết nó phải đạt gì (1.500 TPS? p99 dưới 300 ms?), vì sao chọn PostgreSQL chứ không phải MongoDB, hay rủi ro nào team đang chấp nhận. Sáu tháng sau, người mới hoặc không dám đổi, hoặc đổi mà phá đúng ràng buộc đã tạo ra thiết kế. Đọc xong, bạn biết khi nào đáng viết, dựng khung bằng arc42, vẽ sơ đồ C4 và giữ tài liệu sống bằng docs-as-code.
Phần 2 nói về ADR (ghi quyết định), quality requirement (biến “nhanh”, “ổn định” thành con số), sổ rủi ro và một solution design mẫu cho address component. Tài liệu API cho từng endpoint ở bài Async job, Idempotency-Key và tài liệu API.
1. Vì sao (và khi nào) viết tài liệu kiến trúc
Ý chính: viết khi chi phí tiết kiệm được lớn hơn chi phí viết và duy trì: (Cx − Cy) > Cmd. Và chỉ viết thứ code không tự nói được.
Bốn mục tiêu: chia sẻ kiến thức (onboard vài ngày thay vì vài tuần), làm việc nhóm (nhiều team cùng hiểu một ranh giới service), phân tích (đối chiếu kiến trúc với yêu cầu trước khi xây), giao tiếp (product, security, ops, đối tác cần mức chi tiết khác nhau).
Trong quy tắc của khoá học, Cx là chi phí khi không có tài liệu, Cy khi có, Cmd là chi phí viết và duy trì. Ví dụ: người mới mất 3 ngày hỏi về luồng thanh toán (Cx), có tài liệu còn 1 ngày (Cy). Team nhận 6 người mỗi năm, tiết kiệm 12 ngày công; viết mất 3 ngày, cập nhật 2 ngày mỗi năm (Cmd = 5), vậy là đáng. Một script nội bộ hai người dùng thì không.
2. arc42: khung 12 mục
Ý chính: arc42 là template mã nguồn mở gồm 12 mục, chia thành bốn nhóm dưới đây.
- Bối cảnh (1–3): Introduction and Goals, Constraints, Context and Scope.
- Giải pháp (4–7): Solution Strategy, Building Block View, Runtime View, Deployment View.
- Xuyên suốt và quyết định (8–9): Crosscutting Concepts, Architecture Decisions (các ADR).
- Chất lượng và rủi ro (10–12): Quality Requirements, Risks and Technical Debts, Glossary.
Bảng 12 mục của arc42: mỗi mục trả lời câu hỏi gì
| # | Mục | Trả lời câu hỏi |
|---|---|---|
| 1 | Introduction and Goals | Hệ thống để làm gì, 3–5 quality goal quan trọng nhất, stakeholder (bên liên quan) là ai |
| 2 | Constraints | Ràng buộc không được tự chọn: công nghệ bắt buộc, luật, ngân sách, deadline |
| 3 | Context and Scope | Ranh giới hệ thống, ai và hệ thống nào nói chuyện với nó (nghiệp vụ và kỹ thuật) |
| 4 | Solution Strategy | Vài quyết định nền tảng định hình mọi thứ còn lại |
| 5 | Building Block View | Phân rã tĩnh: container, component (C4 mức 2, 3) |
| 6 | Runtime View | Các khối phối hợp thế nào trong từng kịch bản quan trọng |
| 7 | Deployment View | Chạy trên hạ tầng nào, môi trường nào |
| 8 | Crosscutting Concepts | Quy ước xuyên suốt: logging, bảo mật, xử lý lỗi, idempotency, i18n |
| 9 | Architecture Decisions | Các ADR |
| 10 | Quality Requirements | Cây chất lượng và các quality scenario đo được |
| 11 | Risks and Technical Debts | Rủi ro đã biết, nợ kỹ thuật, kế hoạch xử lý |
| 12 | Glossary | Thuật ngữ nghiệp vụ và kỹ thuật |
3. Một template rút gọn dùng hằng ngày
Ý chính: template của khoá học gom arc42 thành 7 phần cho một solution design. Hai điểm đáng nhớ: ghi cả phần ngoài phạm vi, và tech stack phải kèm version.
- General ≈ arc42 mục 1–3. Solution design ≈ mục 4. System architecture ≈ mục 5–7. ADR, quality requirement, rủi ro, glossary ≈ mục 9–12.
- Mục 8 (crosscutting) không có trong template; mình hay thêm một phần ngắn cho format lỗi, idempotency, logging/tracing.
Bảy phần của template, từng phần chứa gì
- General: giới thiệu; yêu cầu (chức năng và phi chức năng); mục tiêu; ràng buộc; context (sơ đồ context cộng bảng các component/hệ thống liên quan: tên, vai trò, team sở hữu); scope (trong phạm vi và ngoài phạm vi, phần sau quan trọng không kém).
- Solution design: mô tả giải pháp; bảng tech stack kèm version (Java 21, Spring Boot 3.3, PostgreSQL 16…), vì “dùng Kafka” và “dùng Kafka 2.8 có ZooKeeper” là hai câu chuyện vận hành khác nhau.
- System architecture: logical view theo C4 (container, component); runtime view (một sequence diagram mỗi use case); deployment view (dev, staging, prod).
- ADR table.
- Quality requirements table.
- Risks & technical debt.
- Glossary và change history (ai sửa gì, khi nào, vì sao).
Bảng ADR nên ghi cả trọng số tiêu chí và điều kiện xem lại, không chỉ phương án đã chọn.
ADR tốt ghi gì ngoài phương án đã chọn
Một ADR (Architecture Decision Record — bản ghi ngắn một quyết định kiến trúc và lý do) tốt không chỉ ghi phương án đã chọn. Nếu quyết định đến từ chấm điểm nhiều phương án, ghi luôn trọng số từng tiêu chí (độ trễ, chi phí, thời gian ra mắt) và điều kiện xem lại (“khi tải vượt X”, “khi team có người vận hành Kafka”). Khi bối cảnh đổi, người sau biết quyết định cũ hợp lý vì đâu và lúc nào nên đổi. Cách chốt trọng số trước khi chấm và công thức ideality ở bài Phân tích trade-off như senior.
4. C4 model: bốn mức zoom
Ý chính: C4 (Simon Brown) vẽ kiến trúc ở bốn mức, mỗi mức phóng to một phần của mức trên. Mỗi sơ đồ chỉ ở một mức.
| Mức | Tên | Cho thấy | Người đọc |
|---|---|---|---|
| 1 | System Context | Hệ thống của bạn là một hộp, quanh nó là người dùng và hệ thống ngoài | Mọi người, kể cả không kỹ thuật |
| 2 | Container | Đơn vị chạy/triển khai được: app, service, DB, queue, và giao thức giữa chúng | Dev, ops, architect |
| 3 | Component | Bên trong một container: module chính và trách nhiệm | Dev của container đó |
| 4 | Code | Class, bảng (UML, ERD) | Hiếm khi đáng vẽ tay, để IDE sinh |
Ví dụ hệ thống onboarding có address component (mức 1 và 2 gộp một hình):
flowchart LR
customer["Khách hàng<br/>(mobile app, web)"]
ops["Nhân viên vận hành<br/>(back-office)"]
subgraph platform["Hệ thống onboarding"]
gw["API Gateway<br/>route, auth"]
onboarding["Onboarding Service<br/>Java 21, Spring Boot"]
address["Address Service<br/>chuẩn hoá, xác minh địa chỉ"]
db[("PostgreSQL<br/>address, profile")]
bus[["Kafka<br/>address-events"]]
end
master["Master data địa giới<br/>(hệ thống ngoài)"]
ocr["Dịch vụ đọc giấy tờ cư trú<br/>(hệ thống ngoài)"]
customer -->|HTTPS/JSON| gw
ops -->|HTTPS/JSON| gw
gw --> onboarding
onboarding -->|REST: tạo, lấy địa chỉ| address
address -->|JDBC| db
address -->|REST: tra cứu tỉnh/huyện/xã| master
address -->|REST: trích địa chỉ từ ảnh| ocr
address -->|publish AddressVerified| bus
Sơ đồ đọc được khi không có người vẽ đứng cạnh:
- Mỗi hộp có tên, công nghệ, trách nhiệm.
- Mỗi mũi tên có nhãn: làm gì, qua giao thức nào.
- Có legend (chú thích ký hiệu) cho hình dạng và màu.
- Một sơ đồ chỉ ở một mức zoom.
Cùng quy ước này áp vào sơ đồ vẽ trên bảng trong phỏng vấn, ví dụ ở cuối Thiết kế URL shortener.
5. Runtime view: một sequence diagram mỗi use case
Ý chính: building block view cho thấy có gì, runtime view cho thấy chúng phối hợp thế nào. Vẽ cả nhánh lỗi, vì đó là chỗ reviewer tìm ra vấn đề.
sequenceDiagram
participant App as Mobile app
participant On as Onboarding Service
participant Ad as Address Service
participant MD as Master data
participant DB as PostgreSQL
App->>On: Gửi địa chỉ nhập tay (request_id)
On->>Ad: POST /v1/addresses
Ad->>DB: INSERT ... ON CONFLICT (request_id) DO NOTHING
alt request_id đã có
Ad-->>On: 200, địa chỉ đã lưu
else lần đầu
Ad->>MD: Kiểm tra tỉnh/huyện/xã có tồn tại và đúng cấp
alt hợp lệ
Ad->>DB: verify_status = VERIFIED, version + 1
Ad-->>On: 201, VERIFIED
else không hợp lệ hoặc master data timeout
Ad->>DB: verify_status = FAILED hoặc UNVERIFIED, lưu reason, attempts + 1
Ad-->>On: 201, cần người dùng sửa hoặc xác minh lại sau
end
end
Nhánh “master data timeout” buộc bạn trả lời câu hỏi happy path che mất: lưu UNVERIFIED và cho đi tiếp (fail-open — lỗi thì vẫn cho qua) hay chặn onboarding (fail-closed — lỗi thì chặn)? Đó là quyết định nghiệp vụ, nên đáng một ADR (xem phần 2).
6. Deployment view
Ý chính: ghi mỗi môi trường chạy gì, bao nhiêu bản, và khác nhau ở đâu, để biết test ở staging chứng minh được gì cho prod.
Bảng deployment view mẫu: dev, staging, production của Address Service
| Dev | Staging | Production | |
|---|---|---|---|
| Address Service | 1 pod | 2 pod | 3–10 pod, HPA theo CPU, 2 zone |
| PostgreSQL | Container dùng chung | Managed, 1 instance | Managed, primary + 1 standby đồng bộ + 1 read replica |
| Kafka | 1 broker | 3 broker | 3 broker, RF 3, min.insync.replicas=2 |
| Master data | Mock (WireMock) | Sandbox của nhà cung cấp | Production endpoint, timeout 800 ms |
| Dữ liệu | Seed giả | Bản sao đã ẩn danh | Thật |
7. Docs-as-code
Ý chính: đối xử với tài liệu như code: Markdown/AsciiDoc trong repo, sơ đồ bằng text (Mermaid, PlantUML, Structurizr DSL), review qua pull request, CI build site tĩnh và kiểm tra link chết.
Sơ đồ bằng text hay kéo thả: so sánh chi tiết
Cách giữ tài liệu không lỗi thời:
- Đặt
docs/cạnh code; thêm mục “cập nhật tài liệu nếu cần” vào PR template. - Bắt buộc ADR cho thay đổi kiến trúc trong checklist review.
- Sinh phần cơ học (API spec, ERD) từ code.
- Kiểm tra quy tắc kiến trúc bằng test tự động (ArchUnit cho Java), để sơ đồ component không chỉ là mong muốn.
Bài tập
Bài 1: Sơ đồ container cho pet project
Đề: vẽ sơ đồ C4 mức Container cho project đặt homestay (app, API, DB, cache, cổng thanh toán).
Lời giải bài 1
Các hộp Web app (React), Booking API (Spring Boot), PostgreSQL + PostGIS, Redis (cache tìm kiếm), hệ thống ngoài Cổng thanh toán, Email provider. Mũi tên có nhãn: “HTTPS/JSON: tìm, đặt phòng”, “JDBC”, “RESP: đọc/ghi cache”, “HTTPS redirect + IPN”, “SMTP/API: gửi xác nhận”.
Kiểm tra: mỗi hộp có công nghệ và trách nhiệm, không có class hay bảng (đó là mức khác).
Ghi nhớ
- Giải thích được quy tắc (Cx − Cy) > Cmd bằng một ví dụ có số.
- Kể được những thứ nên ghi (bền, không suy ra từ code) và những thứ để code tự nói.
- Nêu được bốn mức C4, ai đọc mức nào, và vì sao “C4” không phải “mức 4”.
- Biết vì sao runtime view phải có nhánh lỗi, và deployment view phải ghi chỗ staging khác prod.
- Kể được ít nhất ba cách docs-as-code giữ tài liệu không lỗi thời.
Câu hỏi phỏng vấn
Junior
arc42 là gì và dùng để làm gì?
Một template mã nguồn mở cho tài liệu kiến trúc gồm 12 mục, giúp mọi tài liệu có cùng cấu trúc.
12 mục: mục tiêu, ràng buộc, context, chiến lược giải pháp, building block, runtime, deployment, khái niệm xuyên suốt, quyết định, quality requirement, rủi ro, thuật ngữ. Không bắt buộc điền đủ; giá trị chính là người đọc biết tìm gì ở đâu.
C4 model gồm những mức nào?
System Context, Container, Component, Code; mỗi mức phóng to một phần của mức trên.
Context: hệ thống là một hộp cùng người dùng và hệ thống ngoài. Container: đơn vị triển khai được như app, service, DB, queue. Component: module bên trong một container. Code: class, bảng; hiếm khi đáng vẽ tay.
Mid
Runtime view khác building block view thế nào?
Building block view là cấu trúc tĩnh (có gì, phụ thuộc ra sao); runtime view là cách chúng phối hợp trong từng kịch bản.
Runtime view thường là sequence diagram, kể cả nhánh lỗi và timeout. Nhiều vấn đề (gọi đồng bộ dây chuyền, thiếu idempotency, fail-open hay fail-closed) chỉ lộ ra ở runtime view.
Một sơ đồ kiến trúc tốt cần những gì?
Người đọc hiểu được mà không cần người vẽ giải thích.
Chỉ ở một mức zoom; mỗi hộp có tên, công nghệ, trách nhiệm; mỗi mũi tên có nhãn nói làm gì và qua giao thức nào; có legend cho hình dạng, màu; phân biệt rõ hệ thống của mình với hệ thống ngoài.
Senior
Làm sao giữ tài liệu kiến trúc không lỗi thời?
Docs-as-code: tài liệu và sơ đồ dạng text trong repo, review cùng PR với code, chỉ viết tay thứ bền.
- CI build và kiểm tra link.
- Viết tay mục tiêu, ràng buộc, quyết định, quality requirement; sinh phần cơ học (API spec, ERD) từ code.
- Đưa ADR và cập nhật tài liệu vào checklist review.
- Kiểm tra quy tắc kiến trúc bằng test (ArchUnit) để sơ đồ component được thực thi chứ không chỉ là mong muốn.
- Tài liệu có người sở hữu và ngày xem lại.
Khi nào không nên viết tài liệu kiến trúc?
Khi chi phí viết và duy trì lớn hơn chi phí tiết kiệm được.
Ví dụ: script nội bộ ít người dùng, prototype sẽ bỏ, hay phần đổi theo từng commit mà code đã nói đủ. Nhưng ngay cả hệ thống nhỏ, một ADR vài dòng cho quyết định khó đảo ngược (chọn DB, ranh giới service, mô hình dữ liệu tiền) hầu như luôn đáng.
Từ vựng tiếng Anh
| Term | Phát âm | Nghĩa | Ví dụ câu tiếng Anh dùng trong phỏng vấn |
|---|---|---|---|
| stakeholder | /ˈsteɪk.hoʊl.dər/ | bên liên quan | “We listed the stakeholders and what each of them needs from the document.” |
| constraint | /kənˈstreɪnt/ | ràng buộc | “Running on the existing PostgreSQL cluster was a hard constraint.” |
| scope / out of scope | /skoʊp/ | phạm vi / ngoài phạm vi | “Geocoding is explicitly out of scope for this release.” |
| runtime view | /ˈrʌn.taɪm vjuː/ | góc nhìn khi chạy | “The runtime view includes the timeout path, not just the happy path.” |
| deployment view | /dɪˈplɔɪ.mənt vjuː/ | góc nhìn triển khai | “The deployment view shows where staging differs from production.” |
| docs-as-code | /dɑːks æz koʊd/ | tài liệu như code | “Docs-as-code means the diagrams are reviewed in the same pull request.” |
| legend | /ˈledʒ.ənd/ | chú thích ký hiệu của sơ đồ | “Every diagram has a legend, so nobody has to guess what a dashed line means.” |
| zoom level | /zuːm ˈlev.əl/ | mức phóng to | “Keep each diagram at a single zoom level: context, container or component.” |
Ghi chép dựa trên khoá Advanced Backend (Ronin Engineer), viết lại theo cách hiểu của mình.