Java for Beginner

Бинарное кодирование: wire format

Protobuf использует собственный бинарный формат передачи — wire format. Он основан на принципе TLV (Tag-Length-Value) для сложных типов и TV (Tag-Value) для скаляров переменной длины. Каждое поле сообщения кодируется независимо, и порядок полей в бинарном потоке не обязан совпадать с порядком объявления в .proto файле.

Wire format — это конкретное бинарное представление сообщения Protobuf при передаче по сети или записи на диск. Оно определяет, как типы данных, номера полей и значения упаковываются в последовательность байтов.

Структура поля в wire format

Каждое поле кодируется как:

[tag][value]

Тег состоит из двух компонентов, упакованных в varint:
field number (номер поля, 3 бита wire type + оставшиеся биты на номер)
wire type (тип кодирования значения, 3 бита)
Wire types определены спецификацией:
0 — Varint (целые числа, булевы, enum)
1 — 64-bit (fixed64, sfixed64, double)
2 — Length-delimited (string, bytes, вложенные сообщения, packed repeated)
3 — Start group (устаревший, не используется в proto3)
4 — End group (устаревший)
5 — 32-bit (fixed32, sfixed32, float)

Varint: переменная длина целых чисел

Varint (variable-length integer) — это способ кодирования целых чисел в виде последовательности байтов переменной длины. Каждый байт varint содержит 7 бит данных и 1 бит-флаг продолжения (most significant bit). Если флаг установлен, следует ещё один байт.

Значение 1:
  Бинарное: 00000001
  Varint:   00000001 (1 байт)

Значение 150:
  Бинарное: 10010110
  Varint:   10010110 00000001 (2 байта)
  Разбор:   младшие 7 бит первого байта = 1001010 (22), старший бит = 1 (продолжение)
            второй байт = 0000001 (1), итого: 1 * 128 + 22 = 150

Varint позволяет кодировать малые числа компактно: числа от 0 до 127 занимают 1 байт. Это главная причина, по которой рекомендуется использовать теги 1–15 для частых полей — теговый байт тоже кодируется как varint, и малые номера полей занимают 1 байт.

ZigZag: кодирование отрицательных чисел
Стандартный varint плохо подходит для отрицательных чисел в знаковых типах (sint32, sint64), так как в дополнительном коде (two's complement) отрицательные числа имеют установленные старшие биты и кодируются максимальной длиной (5 байт для sint32, 10 байт для sint64). Для решения этой проблемы Protobuf использует ZigZag encoding.

ZigZag encoding — это схема отображения целых чисел со знаком на целые без знака, при которой малые по модулю числа (положительные и отрицательные) отображаются на малые положительные числа. Формула: (n << 1) ^ (n >> 31) для 32-битных чисел.

Исходное значение -> Закодированное
0  -> 0
-1 -> 1
1  -> 2
-2 -> 3
2  -> 4

Таким образом, -1 кодируется как 1 и занимает 1 байт вместо 5. Для полей, которые могут содержать отрицательные значения, в .proto следует использовать sint32 или sint64 вместо int32/int64.

Length-delimited: строки и вложенные сообщения
Для типов с переменной длиной (string, bytes, вложенные message) используется wire type 2.

Формат:

[tag][length][data]

Где length — varint, указывающий количество байт в data. Это позволяет парсеру пропустить неизвестные поля (unknown fields) или поля с неправильным типом, не читая их содержимое байт за байтом.

Packed repeated fields
В proto3 скалярные числовые repeated-поля кодируются как packed по умолчанию. Это означает, что вместо отдельного тега для каждого элемента массива весь массив кодируется как один length-delimited блок:

[tag][total_length][value1][value2][value3]...

Это значительно экономит пространство по сравнению с unpacked-форматом, где каждый элемент имел бы свой тег.

Компиляция: от .proto к Java

Компилятор protoc (Protocol Buffers Compiler) трансформирует .proto файлы в исходный код на целевом языке.

Для Java процесс выглядит так:

# Установка компилятора (например, через Maven plugin или скачивание бинарника)
protoc --java_out=./src/main/java library.proto

Флаг --java_out указывает директорию для сгенерированных Java-файлов. Результат компиляции сообщения Book из примера выше:

// Сгенерированный класс Book.java
package com.example.library.proto;

public final class Book extends GeneratedMessageV3 implements BookOrBuilder {
    
    // Приватные поля — immutable объект
    private volatile Object title_;
    private volatile Object author_;
    private int year_;
    private double price_;
    private boolean available_;
    // Repeated поле — хранится как ProtocolStringList (оптимизированная реализация List<String>)
    private LazyStringList tags_;
    private Publisher publisher_;
    
    // Приватный конструктор — объекты создаются через Builder
    private Book() {
        title_ = "";
        author_ = "";
        tags_ = LazyStringArrayList.EMPTY;
    }
    
    // Геттеры
    public String getTitle() { ... }
    public String getAuthor() { ... }
    public int getYear() { ... }
    public List<String> getTagsList() { ... }
    public Publisher getPublisher() { ... }
    
    // Сериализация в OutputStream
    public void writeTo(CodedOutputStream output) throws IOException {
        // Кодирование каждого поля в wire format
        if (!getTitleBytes().isEmpty()) {
            GeneratedMessageV3.writeString(output, 1, title_);
        }
        if (!getAuthorBytes().isEmpty()) {
            GeneratedMessageV3.writeString(output, 2, author_);
        }
        if (year_ != 0) {
            output.writeInt32(3, year_);
        }
        // ... и так далее для каждого поля
    }
    
    // Десериализация из InputStream
    public static Book parseFrom(InputStream input) throws IOException {
        return parseFrom(input, DEFAULT_INSTANCE);
    }
    
    // Вложенный класс Builder — реализация паттерна Builder
    public static final class Builder extends GeneratedMessageV3.Builder<Builder> {
        // Мутабельная копия полей для построения объекта
        public Builder setTitle(String value) { ... }
        public Builder setAuthor(String value) { ... }
        public Builder setYear(int value) { ... }
        public Builder addTags(String value) { ... }
        public Book build() { ... }  // создаёт immutable Book
    }
    
    // Singleton-экземпляр DEFAULT_INSTANCE для пустого сообщения
    private static final Book DEFAULT_INSTANCE;
    static {
        DEFAULT_INSTANCE = new Book();
    }
}

Ключевые особенности сгенерированного кода:
Immutability (неизменяемость): после создания через build() объект Book не может быть изменен. Все поля private final (или private volatile для строк), сеттеров нет. Изменение требует создания нового объекта через toBuilder().
Builder pattern: создание объекта идёт через вложенный класс Builder, что позволяет конструировать объект пошагово и гарантирует валидность на момент build().
LazyStringList: оптимизированная реализация List<String> для repeated string-полей. Хранит строки как ByteString или byte[] до первого обращения как String, что экономит перекодирование UTF-8.
CodedOutputStream / CodedInputStream: низкоуровневые потоки для записи и чтения wire format. Работают напрямую с byte[], минуя промежуточные текстовые представления.

Immutability (неизменяемость) — это свойство объекта, при котором его состояние не может быть изменено после создания. Неизменяемые объекты потокобезопасны по определению, так как их нельзя изменить из любого потока. В Protobuf immutability гарантирует, что сериализованное сообщение не изменится во время передачи.

Builder pattern (паттерн строитель) — это порождающий паттерн проектирования, который позволяет создавать сложные объекты пошагово. В Protobuf Builder изолирует мутабельное состояние на этапе конструирования, а финальный объект остаётся immutable.

#Java #для_новичков #beginner #IO #NIO #Serialize #Protobuf

👍4

46 views08:59