Đến nội dung chính
notes.vinhnq.com

Tìm kiếm

System DesignSenior18 phút đọc

Tài liệu kiến trúc phần 2: ADR, quality requirement, sổ rủi ro và ví dụ address component

Ôn 11 thẻ
Trong bài này

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

Phần 1 đã dựng khung tài liệu (arc42), sơ đồ C4, runtime và deployment view. Phần này lo ba thứ code không tự nói: vì sao chọn thiết kế (ADR), thiết kế phải đạt bao nhiêu (quality requirement), và team chấp nhận rủi ro gì (sổ rủi ro, nợ kỹ thuật). Cuối bài là solution design mẫu cho address component, schema chạy thử trên PostgreSQL 16.

Sơ đồ tóm tắt:

flowchart LR
  D[Quyết định] --> ADR["ADR (Accepted)"]
  ADR --- C["Context, Decision, Alternatives, Consequences"]
  ADR -->|đổi ý| N["ADR mới: Supersedes"]
  Q[Quality requirement] --> M["Đo được: tải, p99, lỗi"]
  M --> A[Cột Actual]
  A -->|trượt mục tiêu| R[Sổ rủi ro]
  R --> O["Owner + ngày xem lại"]

1. ADR: ghi lại quyết định và lý do

Ý chính: ADR (Architecture Decision Record) ghi một quyết định kiến trúc cùng lý do, các phương án bị loại và cái giá phải trả, để người sau hiểu “vì sao hệ thống như vậy”.

  • Format gốc của Michael Nygard: Title, Status, Context, Decision, Consequences.
  • Template khoá học gom ADR vào một bảng: thứ tự, tiêu đề, quyết định kèm trade-off, hệ quả tích cực và tiêu cực, trạng thái, link chi tiết.
  • Ví dụ ADR-004 chọn cột cấp hành chính chung thay cột riêng từng nước; không thêm cấp 4 vì YAGNI (“chưa cần thì chưa làm”).
ADR mẫu đầy đủ: ADR-004 lưu địa chỉ theo cấp hành chính chung
# ADR-004: Lưu địa chỉ theo cột cấp hành chính chung, không theo trường riêng từng nước

Status: Accepted (2026-11-10)

## Context
Địa chỉ được nhập ở nhiều nước; mỗi nước có hệ cấp hành chính khác nhau
(tỉnh/huyện/xã, state/city, province/city/barangay). Bản cũ có cột riêng cho từng
nước, mỗi lần mở thị trường mới phải đổi schema và code ở 4 service.

## Decision
Dùng các cột admin_level1..3 (cấp 1 là lớn nhất) cộng country_code; ý nghĩa từng cấp
theo nước nằm ở master data. Không thêm admin_level4: chưa thị trường nào cần (YAGNI),
khi cần sẽ thêm cột nullable, là thay đổi tương thích.

## Alternatives
- Cột riêng từng nước: rõ nghĩa nhưng mỗi nước mới là một migration.
- Một cột JSONB tự do: linh hoạt nhất nhưng mất ràng buộc, khó index, khó validate.

## Consequences
+ Mở nước mới chỉ cần thêm master data, không đổi schema.
+ Một API, một bộ validate cho mọi nước.
- Tên cột không tự giải thích; người đọc phải tra bảng ánh xạ theo nước.
- Nước có hơn 3 cấp cần migration (đã chấp nhận, xem rủi ro R-03).
Đặt ADR ở đâu: trong repo hay trên wiki

Một ADR mẫu ngắn khác, viết sau tranh luận trong code review: bài tập 2 của Code review: giải quyết bất đồng và hai buổi review mẫu ghi quyết định timeout 2 giây cho bước kiểm tra gian lận trên luồng thanh toán đồng bộ, với bối cảnh bằng số (p99 2 s, 200 worker thread), phương án bị loại kèm lý do, và điều kiện xem lại.

2. Quality requirement: đo được, hoặc coi như không có

Ý chính: “nhanh và ổn định” không kiểm tra được nên không dùng để quyết định gì. Mỗi yêu cầu chất lượng phải có con số, điều kiện đo và cách đo.

Template khoá học dùng bảng context, source, metric, expected, actual. Dòng gốc “Payment | end users | TPS | 1500” còn thiếu nhiều; bản đo được:

Context Source Metric Expected Actual Cách đo
Tạo thanh toán, giờ cao điểm End users qua mobile Throughput duy trì 15 phút ≥ 1.500 TPS 1.720 TPS Load test k6 trên staging cấu hình bằng prod
Tạo thanh toán, giờ cao điểm End users Latency p99 ≤ 300 ms ở 1.500 TPS p99 = 410 ms Cùng test; histogram ở API gateway
Tạo thanh toán End users Tỉ lệ lỗi 5xx ≤ 0,1% 0,02% Cùng test
Payment Service Ops Khả dụng hàng tháng ≥ 99,95% (≈ 22 phút downtime/tháng) 99,97% SLO từ synthetic probe
Primary DB hỏng Ops RPO / RTO RPO = 0, RTO ≤ 5 phút Chưa diễn tập Diễn tập failover hằng quý

Cột Actual biến bảng “mong muốn” thành bảng “kiểm tra”. Dòng latency đang trượt mục tiêu, dòng failover chưa được chứng minh: cả hai chuyển thành rủi ro ở mục tiếp theo. (RPO: lượng dữ liệu tối đa được phép mất; RTO: thời gian tối đa để chạy lại.)

Quality requirement là một trong bốn nhóm architectural driver; mỗi “số 9” khả dụng thêm vào kéo theo bao nhiêu hạ tầng có bảng ở Kiến trúc phần mềm thực dụng: architectural driver. Cột Expected nên có số từ ước lượng back-of-the-envelope (QPS trung bình, peak, dung lượng), không phải số đoán. Dòng khả dụng muốn vận hành được thì biến thành SLI, SLO và error budget như trong Nguyên tắc thiết kế: scalability, performance, availability.

arc42 khuyên viết mỗi yêu cầu thành quality scenario: ai gây ra chuyện gì, trong điều kiện nào, hệ thống phản hồi ra sao, đo bằng gì.

Quality scenario sáu phần của arc42 và ví dụ

Sáu phần: source (ai), stimulus (chuyện gì xảy ra), environment (điều kiện nào), artifact (phần nào bị tác động), response (hệ thống làm gì), response measure (đo thế nào).

Ví dụ: “Khi một broker Kafka (artifact) chết (stimulus) trong giờ cao điểm (environment), việc tạo thanh toán (response) vẫn tiếp tục và không mất event nào đã được ack (measure: 0 event mất, p99 tăng không quá 2 lần trong 1 phút).”

3. Sổ rủi ro và nợ kỹ thuật

Ý chính: sổ rủi ro ghi những gì team biết là chưa ổn, để “ai cũng biết nhưng không ai làm” thành việc có chủ, có hạn.

Template: mô tả, priority, stakeholder bị ảnh hưởng, giải pháp, trạng thái. Nợ kỹ thuật là đường tắt đã đi, sau phải trả.

ID Rủi ro / nợ Priority Ảnh hưởng Giải pháp Trạng thái
R-01 p99 tạo thanh toán 410 ms, vượt mục tiêu 300 ms Cao End users, Payment team Bỏ một lời gọi đồng bộ sang fraud check, chuyển sang async Đang làm
R-02 Chưa diễn tập failover DB, RTO chưa được chứng minh Cao Ops, toàn bộ khách hàng Diễn tập trên staging, rồi trên prod giờ thấp điểm Đã lên lịch
R-03 Nước có hơn 3 cấp hành chính cần migration Thấp Team mở thị trường Thêm admin_level4 nullable khi có nhu cầu Chấp nhận
TD-01 Gửi email trong transaction đặt chỗ Trung bình End users (email sai) Chuyển sang transactional outbox Backlog

Bảng chỉ có ích khi mỗi dòng có người chịu trách nhiệm và ngày xem lại. “Chấp nhận” là trạng thái hợp lệ, nhưng phải ghi ai chấp nhận và vì sao.

4. Ví dụ: solution design cho một address component

Ý chính: solution design đi từ vấn đề, mục tiêu, scope tới schema và contract; mỗi cột đặc biệt trong schema trả lời một rủi ro cụ thể.

Dựng lại từ một tài liệu thực tế, đã bỏ thông tin định danh.

  • Vấn đề: mỗi nước, mỗi kênh nhập địa chỉ một kiểu; dữ liệu không nhất quán, khó xác minh, lại cần ở nhiều luồng.
  • Mục tiêu: một component địa chỉ chuẩn hoá, bản địa hoá được, là nguồn sự thật duy nhất, xác minh với master data địa giới.
  • Scope: mobile và web, luồng onboarding và cập nhật hồ sơ (cả hai đều cần địa chỉ). Ngoài scope: geocoding, địa chỉ giao hàng.
  • Giả định: master data địa giới có sẵn và đúng; không cần thêm thành phần hạ tầng mới.

Những điểm đáng học (lỗi kiểu dữ liệu của bản gốc ở khối gấp cuối mục):

  • Cột cấp hành chính chung (admin_level1..3) thay vì tên riêng từng nước (ADR-004 ở mục 1); quyết định không thêm cấp 4 được ghi kèm lý do.
  • request_id UNIQUE để luồng thu thập an toàn khi client retry (xem Idempotency phần 1).
  • verify_status và capture_method là state rõ ràng, không phải cờ boolean; xem cách lưu enum ở bài Enum trong database và API.
  • version cho optimistic locking (khoá lạc quan: chỉ ghi nếu version chưa đổi) khi người dùng và job xác minh cùng sửa một địa chỉ.
  • verify_attempts và failure_reason để vận hành trả lời được “vì sao địa chỉ này mãi chưa xác minh”.
Schema PostgreSQL 16 đã chạy thử, kết quả và API/event contract

Tài liệu gốc có đủ các phần đã nói: context và container view (hiện tại và mục tiêu), sequence diagram cho hai cách thu thập (nhập tay, và trích từ giấy tờ chứng minh nơi cư trú), lấy địa chỉ, thiết kế DB, API contract và event contract.

Schema, viết lại cho PostgreSQL và đã chạy thử trên PostgreSQL 16:

CREATE TABLE address (
  id               bigint GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  request_id       uuid         NOT NULL UNIQUE,         -- idempotency: retry không tạo bản thứ hai
  owner_type       text         NOT NULL,                -- CUSTOMER, MERCHANT...
  owner_id         bigint       NOT NULL,
  capture_method   text         NOT NULL CHECK (capture_method IN ('MANUAL', 'PROOF_OF_RESIDENCE')),
  verify_status    text         NOT NULL DEFAULT 'UNVERIFIED'
                                CHECK (verify_status IN ('UNVERIFIED', 'VERIFIED', 'FAILED')),
  channel          text         NOT NULL,                -- MOBILE, WEB, BACK_OFFICE
  country_code     char(2)      NOT NULL CHECK (country_code ~ '^[A-Z]{2}$'),   -- ISO 3166-1 alpha-2
  admin_level1     text,                                 -- tỉnh / state / province
  admin_level2     text,                                 -- quận, huyện / city
  admin_level3     text,                                 -- phường, xã / barangay
  address_line1    text         NOT NULL,                -- số nhà, toà nhà
  address_line2    text,                                 -- đường, thôn
  postal_code      text,
  latitude         numeric(9,6) CHECK (latitude BETWEEN -90 AND 90),
  longitude        numeric(9,6) CHECK (longitude BETWEEN -180 AND 180),
  verify_attempts  smallint     NOT NULL DEFAULT 0,
  failure_reason   text,
  version          int          NOT NULL DEFAULT 0,      -- optimistic locking
  created_at       timestamptz  NOT NULL DEFAULT now(),
  updated_at       timestamptz  NOT NULL DEFAULT now()
);
CREATE INDEX address_owner ON address (owner_type, owner_id);

-- Optimistic lock: chỉ cập nhật nếu chưa ai sửa trước
UPDATE address SET verify_status = 'VERIFIED', version = version + 1, updated_at = now()
WHERE id = 1 AND version = 0;   -- lần chạy thử: 1 dòng; câu thứ hai cùng version = 0: 0 dòng

Kết quả chạy thử:

  • Insert lại cùng request_id bị chặn bởi address_request_id_key.
  • country_code = 'vn' bị check constraint từ chối.
  • Hai update cùng version = 0: chỉ một câu thành công.

API và event contract:

  • POST /address-service/v1/addresses (header Idempotency-Key hoặc request_id trong body) trả địa chỉ cùng verify_status.
  • GET /address-service/v1/addresses?owner_type=&owner_id=.
  • Event AddressVerified / AddressVerificationFailed trên Kafka, key = owner_id để giữ thứ tự theo chủ sở hữu; payload chứa address_id, version để consumer bỏ qua event cũ.
Review schema gốc: tọa độ, country_code, múi giờ

Bài tập

Bài 1: Viết ADR cho một quyết định trong pet project

Đề (diễn giải): chọn một quyết định đã làm trong project của bạn (ví dụ dùng UUID hay bigint làm khoá chính) và viết ADR đủ Context, Decision, Alternatives, Consequences.

Lời giải mẫu bài 1: ADR-002 bigint và UUIDv7

Lời giải mẫu (rút gọn):

# ADR-002: Khoá chính bigint identity nội bộ, UUIDv7 làm id công khai
Status: Accepted
## Context
Id lộ ra URL; id tăng dần cho phép đoán số lượng đơn và dò id của người khác.
UUIDv4 làm khoá chính gây ghi ngẫu nhiên vào B-tree, index phình.
## Decision
id bigint identity cho khoá chính và foreign key; cột public_id uuid (v7, sinh ở app) UNIQUE
dùng trong API.
## Alternatives
- Chỉ bigint: đơn giản nhất, nhưng lộ thông tin qua URL.
- Chỉ UUIDv4: không lộ, nhưng index lớn và insert phân mảnh.
- Chỉ UUIDv7: gần tuần tự nên insert tốt; vẫn 16 byte ở mọi foreign key.
## Consequences
+ API không lộ số lượng; join nội bộ trên khoá 8 byte.
- Hai định danh cho một bản ghi; mọi API phải tra theo public_id.

Bài 2: Biến yêu cầu mơ hồ thành quality scenario

Đề: product nói “trang tìm homestay phải nhanh và chịu được lượng truy cập dịp Tết”. Viết lại thành quality requirement đo được.

Lời giải bài 2: quality requirement cho trang tìm homestay

“Với 2.000 request tìm kiếm mỗi giây duy trì 30 phút (gấp 4 lần đỉnh năm ngoái), dữ liệu 200.000 homestay và 50 triệu dòng lịch trống, API GET /homestays có p95 ≤ 400 ms, p99 ≤ 800 ms, tỉ lệ 5xx ≤ 0,1%, đo bằng load test trên staging cấu hình như prod; khi DB đọc chậm, hệ thống trả kết quả cache không cũ quá 5 phút thay vì lỗi.”

Rồi hỏi lại product để chốt từng con số.

Ghi nhớ

  • Kể được các phần của ADR; giải thích vì sao thiếu Alternatives thì không phải ADR.
  • Biết làm gì khi đổi ý về một ADR đã Accepted.
  • Viết lại được “phải nhanh” thành yêu cầu có percentile, mức tải, thời gian, môi trường đo.
  • Giải thích được cột Actual và cách dòng trượt mục tiêu vào sổ rủi ro.
  • Nêu được vì sao schema địa chỉ có request_id UNIQUE, version, cột cấp hành chính chung.

Câu hỏi phỏng vấn

Junior

ADR là gì và gồm những phần nào?

Ghi chép ngắn cho một quyết định kiến trúc, để người sau hiểu vì sao hệ thống như vậy.

Gồm: tiêu đề, trạng thái, bối cảnh (vấn đề và ràng buộc), quyết định, các phương án đã cân nhắc, hệ quả tích cực lẫn tiêu cực.

Sổ rủi ro và nợ kỹ thuật dùng để làm gì?

Ghi những gì team biết là chưa ổn, để chúng thành việc có chủ thay vì “ai cũng biết nhưng không ai làm”.

Gồm rủi ro (chưa diễn tập failover, latency vượt mục tiêu) và nợ kỹ thuật (đường tắt đã đi), kèm ưu tiên, ai bị ảnh hưởng, cách xử lý, trạng thái, người chịu trách nhiệm, ngày xem lại. “Chấp nhận rủi ro” trở thành quyết định có người ký.

Mid

Vì sao “hệ thống phải chịu 1.500 TPS” chưa phải yêu cầu tốt?

Vì thiếu điều kiện đo nên không kiểm tra được.

Thiếu: loại request, payload, thời gian duy trì, ngưỡng latency theo percentile, tỉ lệ lỗi, kích thước dữ liệu, môi trường đo. Hệ thống đạt 1.500 TPS trong 10 giây với p99 vài giây vẫn “đạt”. Viết thành quality scenario có response measure cụ thể.

Đổi ý về một quyết định đã có ADR thì làm gì?

Viết ADR mới ghi Supersedes ADR cũ, đổi ADR cũ thành Superseded, không sửa nội dung ADR cũ.

Như vậy lịch sử lập luận được giữ: ai đọc cũng biết hồi đó quyết định gì, vì sao, và vì sao sau đó đổi.

Senior

Bạn trình bày một solution design cho reviewer theo thứ tự nào?

Từ vấn đề và yêu cầu tới quyết định, rồi rủi ro và câu hỏi mở; reviewer nên dành thời gian cho yêu cầu và quyết định, không phải tên class.

  1. Vấn đề, mục tiêu, scope và ngoài scope, ràng buộc.
  2. Quality requirement đo được, vì chúng quyết định kiến trúc.
  3. Context, container, runtime view cho use case chính kèm nhánh lỗi, deployment.
  4. ADR với phương án bị loại và trade-off.
  5. Rủi ro, nợ kỹ thuật, câu hỏi còn mở cần reviewer quyết định.
Cho ví dụ một quality requirement làm thay đổi kiến trúc.

“p99 tạo thanh toán ≤ 300 ms ở 1.500 TPS” khi riêng fraud check đồng bộ đã mất 200 ms ở p99.

Yêu cầu đó buộc chuyển fraud check sang bất đồng bộ (cho qua, kiểm tra sau, đảo giao dịch nếu cần) hoặc đặt ngân sách latency cho từng chặng. Tương tự, “RPO = 0” buộc dùng replica đồng bộ, đổi lại latency ghi tăng. Quality requirement là thứ chọn giữa các phương án, nên phải chốt trước khi thiết kế.

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
architecture decision record /ˈɑːr.kɪ.tek.tʃər dɪˈsɪʒ.ən ˈrek.ərd/ bản ghi quyết định kiến trúc “Every hard-to-reverse choice gets an architecture decision record.”
supersede /ˌsuː.pərˈsiːd/ thay thế (bản cũ) “ADR-011 supersedes ADR-004, which we keep for history.”
quality scenario /ˈkwɑː.lə.ti səˈner.i.oʊ/ kịch bản chất lượng “We wrote the requirement as a quality scenario with a measurable response.”
response measure /rɪˈspɑːns ˈmeʒ.ər/ thước đo phản hồi “The response measure is p99 under 300 milliseconds at 1,500 TPS.”
technical debt /ˈtek.nɪ.kəl det/ nợ kỹ thuật “We log technical debt with an owner and a review date.”
YAGNI /ˈjæɡ.ni/ chưa cần thì chưa làm “We dropped the fourth admin level on YAGNI grounds and recorded why.”
percentile /pərˈsen.taɪl/ phân vị “We state latency as a percentile, because averages hide the slow tail.”
optimistic locking /ˌɑːp.təˈmɪs.tɪk ˈlɑː.kɪŋ/ khoá lạc quan bằng version “The version column gives us optimistic locking when the user and the verifier edit the same address.”

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.