Trừu tượng hóa dữ liệu theo Barbara Liskov: Xây dựng API đáng tin cậy

Tại sao Barbara Liskov vẫn quan trọng với thiết kế API

Barbara Liskov là một nhà khoa học máy tính có công trình đã âm thầm định hình cách các đội phần mềm hiện đại xây dựng những thứ không dễ sụp đổ. Nghiên cứu của bà về trừu tượng hóa dữ liệu, che giấu thông tin, và sau này là Nguyên tắc Thay thế của Liskov (LSP) đã ảnh hưởng từ ngôn ngữ lập trình đến cách chúng ta nghĩ về API hàng ngày: định nghĩa hành vi rõ ràng, bảo vệ phần nội bộ, và làm cho người khác yên tâm phụ thuộc vào giao diện của bạn.

“Giao diện đáng tin cậy” theo ngôn ngữ sản phẩm

Một API đáng tin cậy không chỉ là “đúng” về mặt lý thuyết. Đó là một giao diện giúp sản phẩm vận hành nhanh hơn:

• Tính năng mới được phát hành mà không làm hỏng khách hàng hiện tại.
• Tích hợp vẫn hoạt động qua các phiên bản.
• Sự cố khi trực canh giảm vì các thất bại có thể dự đoán được.
• Các đội có thể thay đổi nội bộ mà không cần chạy maratôn đồng bộ.

Độ tin cậy là một trải nghiệm: cho nhà phát triển gọi API của bạn, cho đội duy trì, và cho người dùng gián tiếp phụ thuộc vào nó.

Trừu tượng hóa dữ liệu giảm lỗi (và họp hành)

Trừu tượng hóa dữ liệu là ý tưởng rằng người gọi nên tương tác với một khái niệm (một tài khoản, hàng đợi, đăng ký) qua một tập các thao tác nhỏ—không phải qua các chi tiết lộn xộn về cách nó được lưu hoặc tính toán.

Khi bạn che giấu chi tiết biểu diễn, bạn loại bỏ cả các loại sai sót: không ai có thể “vô tình” phụ thuộc vào một trường cơ sở dữ liệu không dành cho công khai, hoặc làm thay đổi trạng thái chia sẻ theo cách hệ thống không xử lý được. Cũng quan trọng không kém, trừu tượng hóa giảm chi phí phối hợp: các đội không cần xin phép để refactor nội bộ miễn là hành vi công khai vẫn nhất quán.

Bạn sẽ áp dụng được gì sau bài này

Cuối bài, bạn sẽ có những cách thực tiễn để:

• Viết hành vi API như những lời hứa rõ ràng (bao gồm các trường hợp biên).
• Giữ giao diện nhỏ và ổn định khi hệ thống tiến hoá.
• Thiết kế chế độ thất bại có thể dự đoán để người gọi xử lý được.

Nếu bạn muốn tóm tắt nhanh sau này, hãy xem phần nói về checklist thực tế.

Trừu tượng hóa dữ liệu, giải thích không dùng biệt ngữ

Trừu tượng hóa dữ liệu là ý tưởng đơn giản: bạn tương tác với một thứ theo những gì nó làm, không phải theo cách nó được xây dựng.

Hãy nghĩ về máy bán hàng tự động. Bạn không cần biết động cơ quay thế nào hay tiền xu được đếm ra sao. Bạn chỉ cần các điều khiển (“chọn hàng”, “thanh toán”, “nhận hàng”) và các quy tắc (“nếu trả đủ tiền, bạn nhận hàng; nếu hết, bạn được hoàn tiền”). Đó là trừu tượng hóa.

“Những gì nó làm” vs. “Nó hoạt động thế nào”

Trong phần mềm, giao diện là “những gì nó làm”: tên các thao tác, đầu vào chấp nhận, đầu ra trả về, và lỗi có thể gặp. Phần triển khai là “nó hoạt động thế nào”: bảng cơ sở dữ liệu, chiến lược cache, lớp nội bộ, và các mẹo tối ưu hóa.

Giữ hai phần tách biệt là cách bạn có được API ổn định ngay cả khi hệ thống thay đổi. Bạn có thể viết lại phần nội bộ, đổi thư viện, hoặc tối ưu lưu trữ—trong khi giao diện vẫn như cũ cho người dùng.

Kiểu dữ liệu trừu tượng (ADT) trong một phút

Một kiểu dữ liệu trừu tượng là “vật chứa + các thao tác được phép + quy tắc,” được mô tả mà không cam kết cấu trúc nội bộ cụ thể.

Ví dụ: một Stack (vào sau ra trước).

• push(item): thêm một phần tử
• pop(): loại bỏ và trả phần tử được thêm gần đây nhất
• peek(): xem phần tử trên cùng mà không loại bỏ

Điều quan trọng là lời hứa: pop() trả phần tử được push() gần nhất. Dùng mảng, danh sách liên kết hay thứ khác là bí mật nội bộ.

Ánh xạ với API thực tế

Cùng một tách biệt áp dụng ở mọi nơi:

• REST endpoints: POST /payments là giao diện; kiểm tra gian lận, retry và ghi DB là phần triển khai.
• Phương thức SDK: client.upload(file) là giao diện; chia khối, nén và gửi song song là phần triển khai.
• Component UI: một “DatePicker” hiển thị props/sự kiện; cấu trúc DOM và plumbing hỗ trợ truy cập là phần triển khai.

Khi thiết kế theo trừu tượng, bạn tập trung vào hợp đồng mà người dùng dựa vào—và tự cho phép thay đổi mọi thứ phía sau mà không phá vỡ họ.

Các bất biến: Quy tắc ẩn giữ hệ thống đúng

Một bất biến là quy tắc luôn phải đúng bên trong một trừu tượng. Nếu bạn thiết kế API, bất biến là lan can giúp dữ liệu không trôi về trạng thái không thể xảy ra—ví dụ tài khoản ngân hàng với hai loại tiền cùng lúc, hoặc đơn hàng “hoàn thành” mà không có mục nào.

Bất biến trông thế nào (không cần toán học)

Hãy nghĩ bất biến như “hình dạng thực tại” cho kiểu của bạn:

• Một Cart không thể chứa số lượng âm.
• Một UserEmail luôn là địa chỉ email hợp lệ (không là “xác thực sau”).
• Một Reservation có start < end, và cả hai ở cùng múi giờ.

Nếu những điều đó không còn đúng, hệ thống trở nên khó đoán, vì mọi tính năng giờ phải đoán ý nghĩa của dữ liệu “hỏng”.

Bất biến hướng dẫn xác thực và xử lý lỗi thế nào

API tốt áp dụng bất biến ở ranh giới:

• Khi tạo: từ chối đầu vào không hợp lệ sớm (trả lỗi rõ ràng).
• Khi cập nhật: chỉ cho phép thay đổi giữ bất biến đúng.
• Khi phân tích/IO: coi dữ liệu bên ngoài là không tin cậy; xác thực trước khi lưu.

Điều này tự nhiên cải thiện xử lý lỗi: thay vì thất bại mơ hồ sau này (“có lỗi xảy ra”), API có thể giải thích quy tắc nào bị vi phạm (“end phải sau start”).

Đừng để bất biến rò rỉ qua giao diện

Người gọi không nên phải thuộc lòng quy tắc nội bộ như “phương thức này chỉ hoạt động sau khi gọi normalize().” Nếu một bất biến phụ thuộc vào một nghi lễ đặc biệt, thì đó không phải là bất biến—mà là một bẫy.

Thiết kế giao diện sao cho:

• trạng thái không hợp lệ không thể hoặc rất khó biểu diễn
• các phương thức giữ bất biến tự động

Checklist tài liệu thực tế

Khi mô tả một kiểu API, hãy ghi:

1. Câu tuyên bố bất biến (tiếng Anh đơn giản, có thể kiểm thử)
2. Nơi thực thi (constructor, setters, endpoints)
3. Điều gì xảy ra khi vi phạm (kiểu lỗi/thông điệp, mã trạng thái)
4. Phương thức nào bảo toàn chúng (và ngoại lệ nếu có)
5. Ví dụ đầu vào hợp lệ vs không hợp lệ (ngắn, cụ thể)

Hợp đồng: Làm rõ hành vi cho người gọi và người bảo trì

Một API tốt không chỉ là tập các hàm—mà là một lời hứa. Hợp đồng làm lời hứa đó rõ ràng, để người gọi có thể tin tưởng hành vi và người bảo trì có thể thay đổi nội bộ mà không làm ai ngạc nhiên.

Những gì cần ghi rõ trong hợp đồng

Ít nhất, hãy tài liệu:

• Tiền điều kiện: điều gì phải đúng trước khi gọi (phạm vi hợp lệ, quyền, kỳ vọng thread-safety).
• Hậu điều kiện: điều gì sẽ đúng sau khi gọi thành công (ý nghĩa giá trị trả về, thay đổi trạng thái).
• Tác dụng phụ: những gì khác bị thay đổi (ghi đĩa, gửi yêu cầu mạng, cập nhật cache, sửa đối tượng truyền vào).

Sự rõ ràng này làm hành vi dự đoán được: người gọi biết đầu vào an toàn và kết quả cần xử lý, và tests có thể kiểm tra lời hứa thay vì đoán ý định.

Hợp đồng giảm “tri thức bộ lạc”

Không có hợp đồng, các đội dựa vào trí nhớ và quy ước không chính thức: “Đừng truyền null ở đó,” “Cuộc gọi kia đôi khi retry,” “Nó trả rỗng khi lỗi.” Những quy tắc đó dễ mất khi onboarding, refactor, hoặc sự cố.

Hợp đồng viết ra biến những quy tắc ẩn đó thành kiến thức chung. Nó cũng cung cấp mốc ổn định cho review mã: thảo luận trở thành “Thay đổi này vẫn thỏa hợp đồng chứ?” thay vì “Nó chạy trên máy tui.”

Wording tốt vs mơ hồ (ví dụ)

Mơ hồ: “Tạo user.”

Tốt hơn: “Tạo user với email duy nhất.

• Tiền điều kiện: email phải là địa chỉ hợp lệ; caller phải có quyền users:create.
• Hậu điều kiện: trả về userId mới; user được persist và có thể truy vấn ngay.
• Chế độ thất bại: trả 409 nếu email đã tồn tại; trả 400 cho trường không hợp lệ; không tạo user từng phần.”

Mơ hồ: “Lấy items nhanh.”

Tốt hơn: “Trả tối đa limit items, sắp theo createdAt giảm dần.

• Tác dụng phụ: không có.
• Tính nhất quán: có thể stale tới 60 giây.
• Phân trang: dùng nextCursor cho trang tiếp; cursor hết hạn sau 15 phút.”

Che giấu thông tin: Giữ nội bộ riêng tư, giữ API ổn định

Che giấu thông tin là phần thực tiễn của trừu tượng hóa dữ liệu: người gọi nên phụ thuộc vào những gì API làm, không phải cách nó làm. Nếu người dùng không thấy nội bộ, bạn có thể thay đổi mà không biến mỗi phát hành thành breaking change.

Công bố thao tác, không công bố biểu diễn

Một giao diện tốt công bố một tập thao tác nhỏ (create, fetch, update, list, validate) và giữ biểu diễn—bảng, cache, hàng đợi, layout file, ranh giới service—là bí mật.

Ví dụ, “thêm mục vào giỏ” là thao tác. “CartRowId” từ DB của bạn là chi tiết triển khai. Khi bạn tiết lộ chi tiết, bạn khuyến khích người dùng xây dựng logic dựa trên nó, điều đó làm đóng băng khả năng thay đổi của bạn.

Tại sao che giấu nội bộ khiến refactor an toàn

Khi client chỉ phụ thuộc vào hành vi ổn định, bạn có thể:

• chuyển database hoặc định dạng lưu trữ
• tách monolith thành nhiều service
• thêm cache hoặc đổi indexing
• tổ chức lại mô hình nội bộ

…và API vẫn tương thích vì hợp đồng không đổi. Đó là lợi tức thật sự: ổn định cho người dùng, tự do cho người bảo trì.

Những kiểu rò rỉ phổ biến cần chú ý

Một vài cách nội bộ vô tình lộ ra:

• Trả về ID nội bộ chỉ có ý nghĩa trong lớp lưu trữ của bạn (số tự tăng, shard key).
• Lộ cấu trúc có thể thay đổi (ví dụ trả đối tượng thô để client có thể sửa rồi gửi lại), điều này ràng buộc client vào các trường cụ thể.
• Cho phép client dựng trạng thái nội bộ, như chấp nhận status=3 thay vì tên rõ ràng hay thao tác chuyên biệt.

Thiết kế dạng phản hồi giữ ổn định

Ưu tiên phản hồi mô tả ý nghĩa, không phải cơ chế:

• Dùng ID công khai ổn định và mơ hồ (ví dụ: ""userId": "usr_…"") thay vì số hàng DB.
• Trả bản sao hoặc view chỉ đọc của các collection thay vì cấu trúc mà client vô tình phụ thuộc thứ tự hay trường nội bộ.
• Thêm trường tương thích ngược; tránh đổi nghĩa trường hiện có.

Nếu một chi tiết có thể thay đổi, đừng công bố nó. Nếu người dùng cần, hãy nâng cấp nó thành một phần có chủ đích và được ghi chép của giao diện.

Nguyên tắc Thay thế của Liskov như một lời hứa giao diện

Nguyên tắc Thay thế của Liskov (LSP) trong một câu: nếu mã làm việc với một giao diện, nó phải tiếp tục làm việc khi bạn thay bằng bất kỳ triển khai hợp lệ nào của giao diện đó—mà không cần các trường hợp đặc biệt.

LSP ít liên quan tới kế thừa và hơn nữa về niềm tin. Khi bạn công bố một giao diện, bạn đưa ra một lời hứa về hành vi. LSP nói rằng mọi triển khai phải giữ lời hứa đó, ngay cả khi sử dụng cách tiếp cận nội bộ rất khác.

LSP là “đừng làm người gọi ngạc nhiên”

Người gọi tin vào những gì API tuyên bố—không phải những gì API tình cờ làm hôm nay. Nếu giao diện nói “bạn có thể gọi save() với bất kỳ bản ghi hợp lệ nào,” thì mọi triển khai phải chấp nhận các bản ghi hợp lệ đó. Nếu giao diện nói “get() trả giá trị hoặc một kết quả 'không tìm thấy' rõ ràng,” thì triển khai không thể ném lỗi mới hoặc trả dữ liệu từng phần.

Mở rộng an toàn có nghĩa bạn có thể thêm triển khai mới (hoặc đổi nhà cung cấp) mà không bắt người dùng phải sửa code. Đó là lợi ích thiết thực của LSP: giữ giao diện có thể thay thế được.

Vi phạm LSP thường gặp trong API

Hai cách phổ biến làm phá vỡ lời hứa:

• Đầu vào hẹp hơn (tiền điều kiện khắt khe hơn): triển khai mới từ chối các đầu vào giao diện cho phép. Ví dụ: giao diện chấp nhận mọi chuỗi UTF‑8 làm ID, nhưng một triển khai chỉ chấp nhận ID số.

• Đầu ra yếu hơn (hậu điều kiện lỏng hơn): triển khai mới trả ít hơn lời hứa. Ví dụ: giao diện nói kết quả được sắp xếp, duy nhất hoặc đầy đủ—nhưng một triển khai trả dữ liệu không sắp xếp, trùng lặp hoặc lặng lẽ bỏ mục.

Một vi phạm tinh tế khác là thay đổi hành vi lỗi: nếu một triển khai trả “không tìm thấy” trong khi triển khai khác ném ngoại lệ cho cùng tình huống, người gọi không thể thay thế an toàn.

Thiết kế hành vi plugin mà không làm ngạc nhiên

Để hỗ trợ “plugin”, hãy viết giao diện như một hợp đồng:

• Xác định đầu vào hợp lệ và giữ tập đó nhất quán giữa các triển khai.
• Xác định ý nghĩa đầu ra (bao gồm thứ tự, mặc định và các trường hợp biên).
• Chuẩn hóa chế độ thất bại: lỗi nào có thể xảy ra và đại diện cho điều gì.

Nếu một triển khai thực sự cần quy tắc khắt khe hơn, đừng giấu điều đó sau cùng một giao diện. Hoặc (1) định nghĩa giao diện riêng, hoặc (2) làm rõ ràng như một capability (ví dụ supportsNumericIds() hoặc cấu hình bắt buộc). Như vậy, client chủ động đăng ký—thay vì bị bất ngờ bởi một “thay thế” không thực sự có thể thay thế.