Đối tượng & Cấu trúc dữ liệu

01 Trừu tượng hóa dữ liệu

Trừu tượng hóa (data abstraction) = phơi một giao diện trừu tượng để người dùng thao tác trên bản chất dữ liệu mà không cần biết nó được hiện thực ra sao. Phơi biến qua getter/setter một cách mù quáng không phải là trừu tượng — nó chỉ là đẩy cấu trúc nội bộ ra ngoài.

RAG  Ví dụ Vehicle của sách: getGallonsOfGasoline() lộ đơn vị đo, còn getPercentFuelRemaining() là trừu tượng. Trong hệ RAG, đừng phơi cách lưu ngữ cảnh — hãy phơi câu hỏi nghiệp vụ trên nó:

class RetrievedContext:
    def __init__(self):
        self.chunks = []          # public: lộ là 1 list
        self.scores = []          # public: lộ điểm thô từng cái
# nơi dùng phải tự ghép: biết cấu trúc bên trong
ctx.chunks; ctx.scores          # phơi hiện thực ra ngoài

class RetrievedContext:
    def top_passages(self, k: int) -> list[str]: ...   # phơi BẢN CHẤT
    def is_confident(self) -> bool: ...                 # không lộ cách lưu
# nơi dùng nói bằng ngôn ngữ nghiệp vụ:
ctx.top_passages(5); ctx.is_confident()

02 Bất đối xứng Data/Object

Hai khái niệm này đối nghịch nhau như âm với dương — đó là lý do gọi là "bất đối xứng" (anti-symmetry):

Sách minh họa bằng bài toán hình học (Shape) viết theo hai lối. Cùng một bài toán, hai cách tổ chức ngược nhau:

03 Hệ quả của đánh đổi

Vì hai lối đối nghịch, ưu/nhược của chúng cũng đối nghịch. Cái khó của OO lại là cái dễ của thủ tục, và ngược lại. Đây là so sánh trung tính — không bên nào sai:

RAG  Soi vào hệ RAG: nếu bạn đoán sẽ liên tục thêm kiểu retriever mới (vector, BM25, hybrid…) thì lối OO (mỗi retriever một lớp đa hình) êm hơn. Nếu tập kiểu cố định nhưng bạn hay thêm phép xử lý trên một bản ghi (rerank, dedup, highlight…), thì để bản ghi là cấu trúc dữ liệu phẳng rồi viết các thủ tục lại tiện hơn. Cùng một hệ, hai quyết định khác nhau — tùy trục thay đổi nào năng động hơn.

04 Luật Demeter & Train Wreck

Luật Demeter (Law of Demeter): một module không nên biết nội thất của object mà nó thao tác. Cụ thể, method f của lớp C chỉ nên gọi method của:

Train Wreck — "đoàn tàu trật bánh"

Chuỗi gọi nối đuôi như đoàn toa tàu vừa khó đọc vừa ràng buộc chặt code gọi vào cấu trúc nội bộ nhiều tầng:

# a.getB().getC().doD() — toa nối toa, lộ 3 tầng nội thất
out_dir = ctxt.get_options().get_scratch_dir().get_absolute_path()
path = out_dir + "/" + class_file_name
stream = open(path, "wb")     # code gọi phụ thuộc vào cả Options & ScratchDir

# tối thiểu: tách chuỗi, không gọi trên giá trị trả về của giá trị trả về
opts = ctxt.get_options()
scratch_dir = opts.get_scratch_dir()
path = scratch_dir.get_absolute_path() + "/" + class_file_name
# (vẫn còn lộ cấu trúc — bản vá triệt để ở mục 06: bảo ctxt làm hộ)

05 Hybrid — tệ nhất cả hai

Tệ nhất là cấu trúc nửa đối tượng nửa cấu trúc dữ liệu: vừa có hàm làm việc quan trọng, vừa phơi biến private qua getter/setter công khai như thể đó là biến public.

class SearchSession:
    def run_query(self, q): ...        # hành vi quan trọng (giống object)
    def get_raw_index(self):           # NHƯNG lại phơi nội thất ra (giống data)
        return self._index
    def set_raw_index(self, idx):
        self._index = idx              # nửa nạc nửa mỡ → tệ cả hai

class SearchSession:                   # rõ ràng là OBJECT
    def run_query(self, q): ...        # chỉ phơi hành vi
    def reindex(self, docs): ...       # không phơi _index ra ngoài
    # _index hoàn toàn private — không getter/setter mù quáng

06 Che giấu cấu trúc · Tell, Don't Ask

Quay lại train wreck mục 04: nếu ctxt là object có hành vi thật, đừng điều hướng xuyên qua nó. Hãy tự hỏi vì sao ta cần đường dẫn tuyệt đối của scratch dir? Câu trả lời: để tạo một scratch file tên cho trước. Vậy thì hãy bảo object làm điều đó, thay vì hỏi nó về nội thất rồi tự làm.

# HỎI nội thất rồi tự ghép — lộ cấu trúc, vi phạm Demeter
abs_path = ctxt.get_options().get_scratch_dir().get_absolute_path()
file_path = abs_path + "/" + class_file_name
stream = open(file_path, "wb")

# BẢO ctxt làm hộ — nó tự giấu Options/ScratchDir bên trong
stream = ctxt.create_scratch_file_stream(class_file_name)
# tương đương Java: BufferedOutputStream bos =
#   ctxt.createScratchFileStream(classFileName);

07 DTO & Active Record

RAG  Sai lầm phổ biến: nhét luật nghiệp vụ vào Active Record — biến nó thành Hybrid (mục 05). Trong hệ RAG, một dòng bảng documents nên ở yên là dữ liệu; logic "tài liệu này có đủ điều kiện đưa vào index không" thuộc về một object nghiệp vụ riêng:

class DocumentRecord:        # Active Record (dịch từ bảng)
    text: str                # biến public
    lang: str
    def save(self): ...      # method điều hướng — OK
    def is_indexable(self):  # NHÉT luật nghiệp vụ vào → thành hybrid
        return self.lang == "vi" and len(self.text) > 50

class DocumentRecord:        # AR thuần = cấu trúc dữ liệu
    text: str; lang: str
    def save(self): ...

class IndexPolicy:           # object nghiệp vụ, GIẤU 1 instance AR
    def __init__(self, rec): self._rec = rec
    def is_indexable(self) -> bool:
        return self._rec.lang == "vi" and len(self._rec.text) > 50

// DTO thuần: chỉ chở dữ liệu sang Python, KHÔNG chứa luật nghiệp vụ
final class IngestPayload {
    public function __construct(
        public string $docId,
        public string $text,
        public string $lang,
    ) {}
}
Http::post('http://rag-py/ingest', (array) $payload);

08 Ghi nhớ nhanh