Component & Cohesion

01 Component là gì

Component là đơn vị triển khai (units of deployment) — những thực thể nhỏ nhất có thể được triển khai như một phần của hệ thống. Trong Java là .jar, Ruby là .gem, .Net là .dll. Bất kể ngôn ngữ nào, chúng là hạt của việc triển khai.

50 năm để component plugin thành "mặc định"

Khả năng cắm component như plugin ngày nay là chuyện hiển nhiên — nhưng nó là thành quả của một hành trình dài về tính tái định vị (relocatability):

02 REP — Tái sử dụng = Phát hành

Reuse/Release Equivalence Principle: "Hạt nhân của tái sử dụng là hạt nhân của phát hành" (the granule of reuse is the granule of release). Muốn một thứ được tái sử dụng, nó phải được phát hành (release) đàng hoàng — và được theo dõi bằng số phiên bản.

REP qua lăng kính RAG

RAG  Web PHP (Laravel) gọi sang Python service qua HTTP. Hợp đồng schema giữa hai bên chính là một "release": đổi shape của response = bump số phiên bản, để bên PHP biết khi nào phải nâng cấp.

# rag-service công bố schema KÈM số phiên bản — đây là "release"
RAG_API_VERSION = "2.3.0"          # đổi schema = bump release number

@app.post("/v2/answer")
def answer(req: AskV2) -> AnswerV2:   # AnswerV2: {text, citations[], schema_version}
    return AnswerV2(text=..., citations=..., schema_version=RAG_API_VERSION)

// PHP CHỈ ở ranh giới: gọi service, đối chiếu version đã pin
$res = Http::post(config('rag.url').'/v2/answer', $payload)->json();

abort_unless(
    Semver::satisfies($res['schema_version'], '^2.3'),  // tương thích bản đã phát hành?
    502, 'rag-service trả schema ngoài dải đã phát hành'
);

03 CCP — SRP ở tầm component

Common Closure Principle chính là SRP phát biểu lại cho component: như SRP nói một lớp không nên có nhiều lý do để đổi, CCP nói một component không nên có nhiều lý do để đổi.

CCP qua lăng kính RAG

RAG  Trong pipeline, chunking + embedding luôn đổi cùng nhau vì cùng một lý do (đổi model embedding, đổi chiến lược cắt văn bản). CCP bảo: gom chúng vào một component rag-index, tách khâu truy hồi ra component khác (truy hồi đổi vì lý do riêng: đổi vector store, đổi top-k).

# rag-index/ — chunking & embedding đổi CÙNG lý do ⇒ cùng component (CCP)
rag_index/
    chunking.py      # đổi khi đổi chiến lược cắt văn bản
    embedding.py     # đổi khi đổi model embedding   ⟵ cùng nhịp với chunking

# rag-retrieval/ — đổi vì lý do KHÁC ⇒ tách riêng
rag_retrieval/
    vector_store.py  # đổi khi đổi Qdrant ↔ pgvector
    ranker.py        # đổi khi đổi chiến lược top-k / rerank

04 CRP — ISP ở tầm component

Common Reuse Principle là phiên bản tổng quát của ISP: ISP khuyên đừng phụ thuộc vào lớp có phương thức ta không dùng; CRP khuyên đừng phụ thuộc vào component có lớp ta không dùng. Rút gọn cả hai thành một câu: "Đừng phụ thuộc vào thứ bạn không cần."

CRP qua lăng kính RAG

RAG  Gói rag-core chỉ nên chứa thứ luôn được dùng chung ở runtime (loại tài liệu, cổng embedder/retriever). Đừng nhét cli hay eval vào — bên web PHP gọi service không cần chúng; kéo theo = mỗi lần đổi tool eval lại buộc phát hành lại rag-core.

# rag-core: CHỈ thứ runtime luôn dùng-chung-nhau (CRP)
rag_core/        →  document.py, embedder.py, retriever.py
# rag-cli, rag-eval: tách thành package riêng, KHÔNG nằm trong rag-core
[project.optional-dependencies]
cli  = ["rag-cli"]    # chỉ ai cần dòng lệnh mới kéo
eval = ["rag-eval"]   # chỉ pipeline đo lường mới kéo

05 Tam giác căng thẳng REP/CCP/CRP

Ba nguyên lý trên giằng co lẫn nhau. REP và CCP là nguyên lý bao hàm (inclusive) — kéo component to ra. CRP là nguyên lý loại trừ (exclusive) — đẩy component nhỏ lại. Kiến trúc sư giỏi là người tìm được điểm cân bằng trong sức căng đó.

06 Ghi nhớ nhanh