Google Protocol Buffers: From Schema to Bytes

Protobuf nằm ở đâu trong đường truyền#

Một cấu trúc trong RAM phụ thuộc ngôn ngữ, layout, padding và cách quản lý bộ nhớ. Khi trao đổi dữ liệu giữa hai chương trình, cần một biểu diễn mà cả hai bên cùng hiểu, thay vì gửi nguyên vùng nhớ của một struct.

1
                        sample.proto
2
                             │
3
                   compiler / generator
4
                       ┌─────┴─────┐
5
                       ↓           ↓
6
                 code phía gửi  code phía nhận
7
                       │           ↑
8
  dữ liệu → object → serialize → bytes → parse → object

Protobuf phụ trách biểu diễn dữ liệu. Phần vận chuyển vẫn cần giao thức hoặc kênh riêng. Với gRPC, .proto có thể mô tả thêm service để sinh client/server RPC; ví dụ trong bài chỉ dùng message và compiler đi kèm grpcio-tools, không mở kết nối gRPC. gRPC: Python basics.

Bắt đầu bằng một schema nhỏ#

Tạo sample.proto:

1
syntax = "proto3";
2
package lab;
3

4
message Record {
5
  uint32 record_id = 1;
6
  sint32 delta = 2;
7
  repeated float values = 3 [packed = true];
8
  string label = 4;
9
  optional bool enabled = 5;
10
}

Trong ví dụ này, record_id là mã bản ghi, delta là một giá trị thay đổi có dấu, values là danh sách số thực và label là nhãn. enabled biểu diễn một tuỳ chọn mà bên gửi có thể cung cấp hoặc bỏ trống.

Số sau dấu = là field number, không phải giá trị mặc định hay vị trí byte. package lab tạo namespace; tên message đầy đủ là lab.Record. Field number phải duy nhất trong message và trở thành định danh trên binary wire. Google: Proto3 language guide.

repeated float cho phép danh sách có nhiều phần tử, bao gồm danh sách rỗng. Ví dụ chọn ba giá trị để dễ tính kích thước; schema không buộc mọi bản ghi đều có đúng ba phần tử.

Sinh code và chạy encode/decode#

Trong một thư mục thử nghiệm, tạo môi trường Python riêng:

1
python3 -m venv .venv
2
source .venv/bin/activate
3
python -m pip install grpcio-tools
4
python -m grpc_tools.protoc -I. --python_out=. sample.proto

Lệnh cuối sinh sample_pb2.py. Compiler dùng schema để tạo kiểu message và thông tin mô tả field; runtime dùng thông tin đó khi serialize/parse. Không sửa tay file được sinh ra: sửa .proto rồi generate lại. Google: Python generated code.

Tạo demo.py cạnh file đó:

1
from pathlib import Path
2
from sample_pb2 import Record
3

4
sample = Record(
5
    record_id=300,
6
    delta=-2,
7
    values=[0.0, 1.0, -1.0],
8
    label="job",
9
    enabled=False,
10
)
11
wire = sample.SerializeToString()
12
Path("sample.bin").write_bytes(wire)
13
print(wire.hex(" "))
14
print("size:", len(wire))
15

16
restored = Record()
17
restored.ParseFromString(wire)
18
assert restored == sample
19
print("round-trip: OK")
20

21
absent = Record()
22
explicit_false = Record(enabled=False)
23
print("absent:", absent.enabled, absent.HasField("enabled"))
24
print("explicit false:", explicit_false.enabled,
25
      explicit_false.HasField("enabled"))
26
print("explicit false bytes:", explicit_false.SerializeToString().hex(" "))

Chạy python demo.py, kết quả đã kiểm tra với grpcio-tools 1.84.0 và Python runtime protobuf 7.36.2:

1
08 ac 02 10 03 1a 0c 00 00 00 00 00 00 80 3f 00 00 80 bf 22 03 6a 6f 62 28 00
2
size: 26
3
round-trip: OK
4
absent: False False
5
explicit false: False True
6
explicit false bytes: 28 00

Các phiên bản trên ghi lại môi trường đã kiểm chứng ví dụ. Với dự án thực tế, cần quản lý compiler và runtime theo chính sách tương thích ở cuối bài.

Đọc 26 byte vừa sinh ra#

Một record Protobuf bắt đầu bằng tag, được tính như sau:

1
tag = (field_number << 3) | wire_type
2
field_number = tag >> 3
3
wire_type = tag & 7

Tag được encode thành varint. Wire type chỉ cách đọc phần dữ liệu tiếp theo; schema mới cho biết kiểu và ý nghĩa cụ thể. Các loại thường gặp là varint (0), dữ liệu 8 byte (1), dữ liệu có độ dài đi trước (2) và dữ liệu 4 byte (5). Google: Encoding.

Tách output của ví dụ theo từng field:

1
ac = 1010 1100 → còn byte tiếp theo; phần dữ liệu = 010 1100 = 44
2
02 = 0000 0010 → byte cuối;         phần dữ liệu = 000 0010 = 2
3

4
300 = 44 + (2 × 128)

1
assert (0xAC & 0x7F) | ((0x02 & 0x7F) << 7) == 300
2
assert (1 << 3) | 0 == 0x08

1
1a 0c
2
   └─ 12 byte dữ liệu
3

4
00 00 00 00 →  0.0
5
00 00 80 3f →  1.0
6
00 00 80 bf → -1.0

1
import struct
2

3
payload = bytes.fromhex("00 00 00 00 00 00 80 3f 00 00 80 bf")
4
assert struct.unpack("<3f", payload) == (0.0, 1.0, -1.0)
5
assert len(payload) == 12

Presence: chưa gửi khác với gửi giá trị mặc định#

Ở output Python, cả absent.enabled và explicit_false.enabled đều là False, nhưng HasField() khác nhau. optional giữ thêm thông tin field đã được đặt hay chưa. Với scalar proto3 không có optional, API dùng implicit presence: giá trị mặc định không phân biệt được với chưa đặt và thường không được serialize. Message field có presence; repeated và map không phân biệt vắng mặt với rỗng. Google: Field presence.

Điều này ảnh hưởng trực tiếp tới thiết kế config. Ví dụ mình muốn “không gửi threshold nghĩa là giữ cấu hình hiện tại”, còn “gửi threshold = 0 nghĩa là tắt ngưỡng”. Schema cần biểu diễn được hai ý đó, và code cập nhật phải kiểm tra presence:

1
Nếu field có mặt: kiểm tra giá trị, rồi áp dụng.
2
Nếu field vắng mặt: giữ giá trị hiện tại theo giao ước của API.

Đây là chính sách cập nhật do ứng dụng quyết định. Thêm optional chỉ cung cấp khả năng nhận biết, không tự biến message thành thao tác patch.

Proto2, proto3 và Editions#

Trong các schema dùng proto2 có thể gặp syntax = "proto2" cùng required và optional. Proto2 theo dõi presence của singular field; required còn tạo ràng buộc về sự có mặt khi xử lý message. Việc thay đổi field required qua các đời schema khó triển khai an toàn. Google: Proto2 language guide.

Proto3 bỏ required; các ví dụ đầu bài dùng optional cho field cần phân biệt giá trị mặc định với chưa gửi. Editions cho phép chọn tập hành vi bằng khai báo như edition = "2023" và các feature; singular field mặc định có explicit presence. Google: Editions overview.

Với dự án đang vận hành, cần kiểm tra cú pháp mà compiler và runtime đang hỗ trợ trước khi thay đổi. Chuyển từ proto2 sang proto3 hoặc Editions cần rà lại presence, enum, code được sinh và runtime, không chỉ thay dòng đầu file.

Message lồng nhau, oneof và map#

Một schema lớn hơn có thể mô tả rõ từng loại kết quả:

1
syntax = "proto3";
2
package lab;
3
import "sample.proto";
4

5
message RecordError {
6
  uint32 code = 1;
7
  string detail = 2;
8
}
9

10
message Result {
11
  oneof body {
12
    Record sample = 1;
13
    RecordError error = 2;
14
  }
15
  map<string, string> labels = 3;
16
}

Lưu ví dụ này thành result.proto nếu muốn generate cùng sample.proto. oneof cho biết nhánh nào đang được đặt; đặt nhánh mới sẽ xoá nhánh cũ trong API. Nó vẫn có thể chưa có nhánh nào. map phục vụ tra cứu key/value và không bảo đảm thứ tự lặp. Google: Proto3, oneof và maps.

Với kết quả có cấu trúc đã biết, nên ưu tiên field có tên và kiểu cụ thể. Ví dụ sample và error dễ kiểm tra hơn một bytes payload mà từng nơi tự đoán nội dung. bytes vẫn hữu ích khi có một lớp bên ngoài quản lý loại payload, như cách một framework đóng gói nhiều loại message.

Thay đổi schema mà hai phía vẫn hiểu nhau#

Bên gửi và bên nhận có thể được cập nhật khác thời điểm. Khi bỏ field, cần reserve number và nên reserve cả tên; không tái sử dụng number cũ cho một ý nghĩa mới. Đổi kiểu cũng cần đánh giá tương thích, kể cả khi wire type giống nhau. Google: Proto best practices.

Ví dụ một phiên bản sau bỏ label = 4 và thêm timestamp:

1
syntax = "proto3";
2
package lab.v2;
3

4
message Record {
5
  reserved 4;
6
  reserved "label";
7

8
  uint32 record_id = 1;
9
  sint32 delta = 2;
10
  repeated float values = 3 [packed = true];
11
  optional bool enabled = 5;
12
  optional uint64 timestamp_us = 6;
13
}

lab.v2 ở đây giúp chạy thử hai schema cùng lúc; trong binary message mẫu không có chuỗi package này để tự chọn decoder. Phía nhận phải được cấp đúng loại message từ giao thức của ứng dụng.

Mình sẽ kiểm tra cả hai chiều:

• Bên nhận mới đọc dữ liệu cũ: field 6 chưa có; xử lý trường hợp thiếu timestamp.
• Bên nhận cũ đọc dữ liệu mới: field 6 là unknown; client vẫn cần đọc được các field nó biết.

Google runtime hỗ trợ giữ unknown fields trong binary message, nhưng thao tác chuyển qua JSON hoặc tự dựng object mới có thể làm mất chúng. Nếu một dịch vụ trung gian decode rồi encode để chuyển tiếp, cần kiểm tra hành vi giữ field chưa biết trong toàn bộ đường xử lý. Google: Unknown fields.

Một tình huống khác do mình đặt ra: hai phía đều khai báo float timeout = 7, nhưng bên gửi đổi đơn vị từ giây sang mili giây. Message vẫn parse được, nhưng thời gian chờ sẽ sai. Vì vậy test tương thích phải kiểm tra cả ý nghĩa và đơn vị, ngoài khả năng decode.

Ba ranh giới dễ nhầm#

Đọc và kiểm tra dữ liệu bằng compiler#

Với sample.bin đã tạo, decode bằng schema:

1
python -m grpc_tools.protoc -I. \
2
    --decode=lab.Record sample.proto < sample.bin

Kết quả thử nghiệm:

1
record_id: 300
2
delta: -2
3
values: 0
4
values: 1
5
values: -1
6
label: "job"
7
enabled: false

Thử bỏ schema:

1
python -m grpc_tools.protoc --decode_raw < sample.bin

Lúc này field 2 hiện thành 3, không phải -2; field 3 là một dãy byte. Thí nghiệm này cho thấy raw decoder nhận ra cấu trúc record nhưng chưa biết cách diễn giải theo schema. Khi có header bên ngoài payload, cũng cần tách đúng phần Protobuf trước khi dùng công cụ này.

Cuối cùng, tách hai bài toán tương thích: schema ở hai phía và generated code với runtime tại từng phía. Google không hỗ trợ ghép code được sinh mới với runtime cũ hơn; C++ còn yêu cầu phiên bản generated code và runtime khớp chính xác. Google: Cross-version runtime guarantee.

Trước khi đưa một schema mới vào sử dụng, nên kiểm tra message hợp lệ, thiếu field optional, giá trị mặc định được gửi rõ, mảng rỗng/quá dài, payload bị cắt và trao đổi giữa schema cũ–mới. Decode thành công mới xác nhận được cấu trúc; độ dài danh sách, khoảng giá trị, đơn vị và điều kiện sử dụng vẫn cần kiểm tra trong ứng dụng.

Nguồn chính thức#

• Protocol Buffers Documentation: điểm bắt đầu và các hướng dẫn theo ngôn ngữ.
• Language Guide (proto3) và Encoding: schema và định dạng binary.
• Field Presence và Proto Best Practices: ngữ nghĩa field và thay đổi schema.
• Python Generated Code và Cross-Version Runtime Guarantee: API Python và tương thích công cụ.