Ranh giới

01 Dùng code bên thứ ba

Có một căng thẳng tự nhiên giữa hai phía của ranh giới. Người cung cấp một interface muốn nó rộng để dùng được ở nhiều nơi; người dùng lại muốn một interface khít với nhu cầu cụ thể của mình. Lực kéo ngược chiều này chính là nguồn rắc rối ở ranh giới.

Ví dụ kinh điển của sách: java.util.Map. Interface của nó rất rộng — bất kỳ ai cầm một Map cũng gọi được clear() để xóa sạch nó; Map lại không ràng buộc kiểu phần tử nên ai cũng nhét được kiểu khác vào. Truyền một Map trần đi khắp hệ thống nghĩa là: nếu interface Map đổi (như khi Java 5 thêm generics), bạn phải sửa rất nhiều nơi.

RAG  Cùng vấn đề khi ta cầm một collection trần (như map từ tên cảm biến → đối tượng Sensor) và truyền nó khắp pipeline. Hãy bọc nó trong một lớp chuyên biệt và giấu interface ranh giới đi:

# map trần đi khắp hệ thống — interface ranh giới phơi ra mọi nơi
sensors: dict = {}
register(sensors)            # nơi nào cũng cầm dict trần
s = sensors["temp-01"]       # phải tự ép kiểu, tự đoán có hay không
sensors.clear()              # AI CŨNG xóa sạch được — interface quá rộng

class Sensors:                       # Map bị GIẤU sau ranh giới
    def __init__(self):
        self._sensors: dict = {}     # interface ranh giới ở yên trong đây
    def get_by_id(self, id: str) -> Sensor:
        return self._sensors[id]     # ép kiểu/quản lý kiểu gói một chỗ
# nơi dùng chỉ thấy đúng phép cần — không clear() bừa, không lộ dict

02 Khám phá & học ranh giới (learning tests)

Học một thư viện bên thứ ba và đồng thời tích hợp nó vào code production là việc rất khó — làm cả hai một lúc dễ sai. Thay vì thử nghiệm ngay trong production code, hãy viết learning tests (Jim Newkirk): những bài test nhỏ gọi API bên thứ ba đúng theo cách ta dự định dùng — như một thí nghiệm có kiểm soát để kiểm chứng hiểu biết của mình.

RAG  Trước khi nhúng SDK của một vector DB hay LLM bên thứ ba vào pipeline, viết learning test thăm dò trước — ép API hành xử đúng cái mình định nhờ nó làm:

def test_learn_vectordb_roundtrip():     # KHÔNG test code của ta — test hiểu biết
    db = ThirdPartyVectorDB(dim=3)        # API "dạy": phải khai số chiều
    db.upsert(id="a", vector=[0.1, 0.2, 0.3])
    hits = db.query(vector=[0.1, 0.2, 0.3], top_k=1)
    assert hits[0].id == "a"              # chốt lại: đây là cách nó hoạt động

03 Learning tests "tốt hơn miễn phí"

Ta phải bỏ công học API dù sao đi nữa, nên viết learning test không tốn thêm gì — mà còn cho lãi. Đó là lý do sách nói chúng "tốt hơn cả miễn phí" (better than free): ROI dương rõ ràng.

RAG  Một ranh giới sạch nên có bộ "outbound tests" tập thể dục cho interface y như cách production dùng nó. Nhờ vậy việc migrate sang phiên bản mới của SDK nhẹ nhàng — ta không bị kẹt ở phiên bản cũ lâu hơn cần thiết chỉ vì sợ nâng cấp sẽ vỡ thứ gì đó không rõ.

04 Dùng code chưa tồn tại

Có một loại ranh giới khác: ranh giới ngăn cái đã biết với cái chưa biết. Đôi khi ta phải viết code dựa vào một API mà chưa ai thiết kế xong. Đừng để bị chặn lại — hãy tự định nghĩa interface mình mong muốn ("the interface you wish you had") ngay tại ranh giới.

RAG  Cùng cách làm khi LLM SDK ta định dùng chưa có (đang chờ vendor, hoặc đội khác chưa làm xong). Định nghĩa interface mình mong muốn trước; khi API thật xuất hiện, viết một Adapter cầu nối:

def answer(q, context):
    # SDK thật chưa có — đoán mò hình dạng, lại chặn việc viết client
    raw = vendor_llm.completions.create(        # ráp cứng vào vendor
        model="???", prompt=build(q, context), max_tok=512)
    return raw["choices"][0]["text"]            # chi tiết vendor lan ra logic

class TextGenerator(Protocol):              # interface MÌNH ƯỚC CÓ
    def generate(self, prompt: str) -> str: ...

def answer(q, context, gen: TextGenerator): # client sạch, viết được ngay
    return gen.generate(build(q, context))

class SdkAdapter:                            # cầu nối khi API thật xuất hiện
    def generate(self, prompt: str) -> str: # MỘT nơi duy nhất chạm vendor
        raw = vendor_llm.completions.create(model="gpt-x", prompt=prompt)
        return raw["choices"][0]["text"]

05 Ranh giới sạch (Clean Boundaries)

Thay đổi xảy ra ở ranh giới. Code tốt thì khi thư viện đổi không cần sửa nhiều. Bí quyết: tránh để quá nhiều phần của hệ thống biết chi tiết bên thứ ba. Tốt hơn là phụ thuộc vào thứ ta kiểm soát hơn là thứ ta không kiểm soát.

RAG  Trong hệ RAG, ranh giới service cũng là một loại ranh giới: khi Laravel gọi sang pipeline Python qua HTTP, hãy giấu chi tiết của lời gọi đó sau một lớp client thay vì rải Http::post với URL & hình dạng payload khắp controller:

// chi tiết service Python phơi ra mọi nơi gọi
$res = Http::post('http://rag-py/answer', [   // URL & shape lặp khắp nơi
    'q' => $request->query,
]);
$text = $res->json()['choices'][0]['text'];   // hình dạng response lan ra

final class RagClient {                    // MỘT điểm tham chiếu tới service
    public function answer(string $q): string {
        $res = Http::post('http://rag-py/answer', ['q' => $q]);
        return $res->json()['choices'][0]['text'];   // chi tiết giấu ở đây
    }
}
// controller: $ragClient->answer($request->query); — không thấy ranh giới

Kết quả: code dễ hiểu, dùng ranh giới một cách nhất quán, và có rất ít điểm phải bảo trì khi thư viện hay service phía sau đổi.

06 Ghi nhớ nhanh