# Chọn định dạng dữ liệu cho khách là chọn hợp đồng bạn phải giữ

> Định dạng sai hiếm khi vỡ ngày đầu, mà vỡ khi dữ liệu thật hoặc schema lệch khỏi điều hai bên ngầm hiểu.

Bản gốc: https://fdetimes.net/vi/bach-khoa/dinh-dang-du-lieu-json-csv-parquet-avro-protobuf-chon-khi-nao/

RFC 4180, tài liệu nhiều đội vẫn gọi là "chuẩn CSV", tự xếp mình vào loại informational, tức là chỉ để tham khảo chứ không phải một chuẩn chính thức. Mỗi lần gật đầu với câu "cứ gửi CSV cho bọn tôi", bạn đang ký một hợp đồng mà chưa ai viết điều khoản ra.

Với một FDE, đây là một trong những quyết định kỹ thuật có hệ quả lâu nhất của cả đợt triển khai. Code tích hợp có thể viết lại, nhưng định dạng dữ liệu đã chạy ở phía khách thì vẫn phải được giữ sau khi bạn rời dự án.

Vì thế, câu hỏi đáng đặt ra khi chọn định dạng là bạn đang cam kết với khách điều gì, và cam kết đó sống sót ra sao khi dữ liệu và schema thay đổi.

## Định dạng là hợp đồng, đuôi file chỉ là cái nhãn

Mỗi định dạng trả lời ba câu hỏi theo cách riêng. Byte được mã hoá thế nào? Tên và kiểu của từng field nằm ở đâu, trong dữ liệu hay ở một tài liệu bên ngoài? Và khi bạn thêm hoặc bỏ một field, phía khách có còn đọc được không?

CSV trả lời cả ba câu một cách mơ hồ. RFC 4180 yêu cầu field chứa dấu phẩy, dấu nháy kép hay ký tự xuống dòng phải được bọc trong dấu nháy kép. Nó cũng ghi nhận cách dùng phổ biến của CSV là US-ASCII, còn bảng mã khác phải được khai báo qua một tham số riêng.

Lấy một ví dụ giả định: tuần đầu ở một khách logistics, trưởng nhóm dữ liệu chỉ yêu cầu xuất CSV hằng ngày.

Ba tuần sau, một địa chỉ giao hàng có dấu phẩy không được quote, một tên khách hàng có ký tự ngoài ASCII mà không ai thống nhất encoding, và báo cáo phía khách lệch cột mà không có dòng lỗi nào.

Cả hai chỗ vỡ đều nằm đúng ở những điều RFC 4180 đã cảnh báo.

## Protobuf để tên field ở phía người đọc

Protobuf chặt hơn CSV nhiều, nhưng nó đặt hợp đồng ở một chỗ khác. Tài liệu encoding của Protobuf ghi rõ trên đường truyền mỗi field chỉ được nhận diện bằng số hiệu, còn tên và kiểu chỉ xác định được ở phía giải mã, bằng định nghĩa message.

Hệ quả đầu tiên là gửi message Protobuf cho khách mà không gửi file `.proto` thì cũng như gửi một tập tin đã khoá mà giữ lại chìa.

Hệ quả thứ hai dễ chịu hơn: Martin Kleppmann giải thích rằng khi gặp một số hiệu lạ, parser không biết tên field nhưng vẫn tính được cần bỏ qua bao nhiêu byte dựa vào mã kiểu.

Tài liệu Protobuf xác nhận parser cũ bỏ qua những field mới mà nó không hiểu, và đó là lý do thêm field thường an toàn.

Enum cũng được đối xử mềm dẻo. Trong proto3, giá trị enum lạ được giữ lại trong message khi giải mã thay vì làm hỏng cả lần đọc, nên hệ thống cũ của khách có thể mang theo một giá trị nó chưa biết. Code phía khách vì thế nên có nhánh xử lý cho giá trị không nhận ra.

**Điểm mấu chốt:** Định dạng tốt nhất là định dạng mà khách vẫn đọc được sau khi bạn rời dự án.

## Ví dụ: luồng đơn hàng khi schema thay đổi

Quay lại khách logistics. Giả sử sau hai tháng, bộ phận vận hành muốn thêm field `delivery_window` cho mỗi đơn, và bỏ field `legacy_zone` không còn dùng.

Với CSV, bạn thêm một cột. Nếu script phía khách đọc theo vị trí cột thay vì theo tên, mọi cột phía sau dịch sang một ô mà không báo lỗi. Nếu file không có header, khách còn không có cách nào nhận ra.

Với Protobuf, thêm `delivery_window` bằng một số hiệu mới là xong. Xoá field mới là chỗ có bẫy. Số hiệu là danh tính vĩnh viễn của field, và cả tài liệu Protobuf lẫn Kleppmann đều nhấn mạnh không bao giờ được dùng lại một số đã gán. Khi bỏ `legacy_zone`, bạn đưa số của nó vào danh sách reserved:

```proto
message Order {
  reserved 3;
  reserved "legacy_zone";
  string order_id = 1;
  string address = 2;
  string delivery_window = 4;
}
```

Thử nghĩ chuyện gì xảy ra nếu sáu tháng sau một kỹ sư khác gán số 3 cho field mới `priority`. Hệ thống cũ của khách vẫn giải mã số 3 theo định nghĩa `legacy_zone`, và tài liệu Protobuf thừa nhận wire format không có cách phát hiện một field được mã hoá bằng định nghĩa này rồi giải mã bằng định nghĩa khác.

Kết quả có thể là lỗi parse, trường hợp tốt nhất theo chính tài liệu Protobuf. Nhưng danh sách hệ quả còn có dữ liệu hỏng và rò rỉ dữ liệu cá nhân, những thứ không ai hay cho tới khi khách phát hiện.

Một dòng `reserved` chặn được cả loại sự cố đó: trình biên dịch protoc sẽ báo lỗi ngay khi có người định dùng lại số đã giữ chỗ.

## Khi schema đổi, bên nào nâng cấp trước?

Đây là câu hỏi nên đặt ngay buổi đầu. Confluent Schema Registry, công cụ quản lý schema trong hệ sinh thái Kafka, định nghĩa BACKWARD là consumer dùng schema mới đọc được dữ liệu sinh ra bằng schema ngay trước đó. Với Protobuf, tài liệu của Confluent khuyên dùng chế độ BACKWARD_TRANSITIVE.

Suy từ định nghĩa đó, thứ tự nâng cấp là phía đọc lên schema mới trước, rồi phía ghi mới đổi. Nếu bạn kiểm soát bên đọc, hoặc khách nâng cấp nhanh, thứ tự này dễ giữ.

Nhưng nếu khách là một doanh nghiệp lớn, mỗi lần đổi code phải qua ủy ban phê duyệt, thì phía bạn sẽ muốn đổi schema trước họ rất lâu. Khi đó bạn phải tự hỏi hệ thống cũ của khách có đọc được dữ liệu mới không, và với Protobuf, câu trả lời phụ thuộc vào việc bạn chỉ thêm field hay đã đổi kiểu hoặc dùng lại số hiệu.

## Cách làm từ buổi discovery đầu tiên

Bắt đầu bằng việc hỏi ai đọc dữ liệu và đọc bằng công cụ gì. Một nhà phân tích mở file bằng bảng tính và một service gọi API của bạn liên tục cần hai hợp đồng rất khác nhau.

Tiếp theo, hỏi tần suất thay đổi schema và chu kỳ nâng cấp phía khách. Schema còn đổi nhiều trong khi khách nâng cấp chậm là tín hiệu nên chọn định dạng có schema tường minh và quy tắc tiến hoá rõ ràng, rồi chốt hướng tương thích bạn cam kết.

Sau đó, viết spec ra một trang và gửi khách xác nhận, kể cả khi họ chỉ nói "cứ gửi CSV". Với CSV, trang đó ghi dấu phân cách, ký tự quote, encoding, có header không và kiểu từng cột.

Với Protobuf, đó là file `.proto` đặt ở một repo khách truy cập được, kèm quy tắc reserved. Cuối cùng, dựng một bài test đọc dữ liệu cũ bằng schema mới và cho nó chạy ở mỗi lần release.

## Những lỗi hay gặp

Lỗi phổ biến nhất là coi CSV như một chuẩn ai cũng hiểu giống nhau, trong khi chính tài liệu mô tả nó chỉ để tham khảo. Lỗi thứ hai là gửi message Protobuf mà không có quy trình giao file `.proto`, khiến khách phải đoán số 4 nghĩa là gì.

Lỗi thứ ba là xoá field Protobuf mà không đưa vào reserved. Lỗi thứ tư khó thấy hơn: đổi kiểu của một field. Tài liệu best practices của Protobuf cảnh báo việc này làm hỏng deserialization, dù một phần dữ liệu cũ vẫn parse được dưới kiểu mới, nên test thử vài bản ghi có thể cho bạn cảm giác an toàn giả.

Lỗi cuối cùng là chọn định dạng theo sở thích của đội mình thay vì theo công cụ phía khách. Định dạng hiệu quả đến đâu cũng vô ích nếu người nhận không mở được nó.

## Một câu chuyện schema đáng giá hơn dòng kỹ năng

Trong CV, đừng chỉ liệt kê "CSV, Protobuf, Schema Registry". Hãy kể lại một lần schema thay đổi mà hệ thống phía khách vẫn chạy bình thường.

Khi người phỏng vấn hỏi về tích hợp dữ liệu, một câu trả lời tốt chỉ cần ba ý, như ví dụ đơn hàng ở trên: đã chốt với khách bên nào nâng cấp trước, khi bỏ `legacy_zone` thì đưa số 3 vào `reserved`, và mỗi lần release đều chạy bài test đọc dữ liệu cũ bằng schema mới. Ba ý đó cho thấy bạn đã thật sự làm.

Lần tới khách nói "cứ gửi CSV là được", hãy coi đó là lúc mở cuộc thương lượng chứ không phải lúc đóng lại.

**Thử ngay tuần này:**

- Lấy một file CSV bạn đang gửi cho khách và viết ra một trang spec: dấu phân cách, cách quote, encoding, có header hay không, kiểu của từng cột.
- Mở file .proto gần nhất bạn đụng tới, tìm field đã bị xoá mà chưa nằm trong reserved và sửa lại.
- Viết một bài test đọc dữ liệu sinh ra từ phiên bản schema cũ bằng schema hiện tại, rồi đưa nó vào pipeline release.

## Nguồn

- [Language Guide (proto 3) | Protocol Buffers Documentation](https://protobuf.dev/programming-guides/proto3/)

- [Encoding | Protocol Buffers Documentation](https://protobuf.dev/programming-guides/encoding/)

- [Proto Best Practices | Protocol Buffers Documentation](https://protobuf.dev/best-practices/dos-donts/)

- [Schema evolution in Avro, Protocol Buffers and Thrift](https://martin.kleppmann.com/2012/12/05/schema-evolution-in-avro-protocol-buffers-thrift.html)

- [RFC 4180: Common Format and MIME Type for Comma-Separated Values (CSV) Files](https://www.rfc-editor.org/rfc/rfc4180)

- [Schema Evolution and Compatibility for Schema Registry on Confluent Platform](https://docs.confluent.io/platform/current/schema-registry/fundamentals/schema-evolution.html)
