English for Protocol Buffers (Protobuf) Developers
Словник для розробників, які визначають схеми протокольних буферів — номери полів, формат дротів і зворотну сумісність — для команд, які обговорюють контракти серіалізації англійською мовою.
Більшість розбіжностей Protobuf в огляді насправді стосуються еволюції схеми - чи є зміна безпечною для служб, які ще не були перерозгорнуті. Маючи точний словник для сумісності дозволяє рецензенту сказати точно, чому зміна є ризикованою, замість нечіткого «що може щось пошкодити»
Базові схеми
** файл .proto** — файл визначення схеми, у якому описано повідомлення і їх поля, з якого Protobuf генерує типовий код для кожної мови, яку використовує проект.
“Не редагуйте вручну сформовані структури Go — змініть файл .proto і відтворіть, або ваш виправлення зникне при наступному запуску codegen.”
** Повідомлення ** — структурований тип даних, визначений у файлі .proto, приблизно аналогічний класу або структурі, складається з типованих, пронумерованих полів.
- “Додайте нове повідомлення замість перевантаження цього повідомлення непов’ язаними додатковими полями — стає все складніше визначити, як виглядає чинний екземпляр.” *
** Номер поля ** — це невелике ціле число, яке буде призначено для кожного поля у повідомленні, це число буде використано у двійковому форматі дротяного повідомлення замість назви поля; саме це число, а не назва, ідентифікує поле у дротяному повідомленні.
- “Ви можете вільно перейменовувати це поле — просто ніколи не змінюйте або не використовуйте номер поля, оскільки саме він ідентифікує його у кодованих байтах.” *
Формат і кодування проводів
** Wire format ** — компактне двійкове кодування, яке використовується Protobuf для послідовного запису повідомлень, побудоване навколо номерів і типів полів, а не навколо назв полів, що робить його меншим і швидшим за JSON.
“У дійсних байтах на дроті немає назви поля — саме тому номер поля є постійним, а назва поля є лише для зручності генерації коду.”
Varint — ціле число змінної довжини, яке використовується Protobuf для більшості числових типів, де малі значення займають менше байтів, що є частиною причини, чому корисні навантаження Protobuf зазвичай менші, ніж еквівалентні JSON.
“Маленькі лічильники, як цей, майже нічого не коштують на проводі — кодування varint означає, що значення менше 128 займає один байт.”
Compatibility
** Обратна сумісність ** — зміна схеми, яка не порушує старі клієнти або сервери, які все ще працюють з попередньою версією схеми, що є типовим припущенням, для якого оптимізується дизайн Protobuf.
“Додання нового додаткового поля є зворотньо сумісним — старі двійкові файли просто ігнорують поле, про яке вони не знають.”
** Розрив зміни (у Protobuf) ** — повторне використання номера поля для іншого поля, зміна типу поля несумісним чином, або перенумерація існуючого поля, будь- яке з яких порушує декодування для служб на іншій версії схеми.
- “Повторне використання поля номер 4 для іншого типу є найнебезпечнішим, що ви можете зробити — стара служба неправильно інтерпретуватиме байти, а не просто не зможе їх прочитати.” *
** Зарезервовані поля/ номери ** — явне позначення номера вилученого поля (і часто його назви) як зарезервованого, щоб воно ніколи не могло бути випадково використано знову майбутнім полем, захищаючи саме від цього класу зміни.
“Позначте поле 7 як зарезервоване після його вилучення — таким чином ніхто не додасть нове поле з цим номером через шість місяців і не розірве всі послуги, які все ще працюють за старою схемою.”
Поширені помилки
- Перейменування поля і припущення, що це поле є безпечним, без перевірки, чи не було змінено також і номер поля.
- Повторне використання номера вилученого поля для нового, не пов’ язаного поля замість позначення його як зарезервованого.
- Правила сумісності Protobuf розглядаються як додатковий параметр стилю, а не як механізм, який запобігає тимчасовому пошкодженню даних службами змішаних версій.
Практичні вправи
- Поясніть у двох реченнях, чому номер поля має більше значення, ніж назва поля у форматі Protobuf.
- Напишіть короткий коментар PR, у якому поясните, чому повторне використання номера вилученого поля небезпечно, і замініть його на інший.
- Створити повідомлення, яке відрізняє зміну схеми, сумісну з попередніми версіями, від зміни, яка порушує ці правила, для співробітника команди, який пропонує змінити тип поля.
Зв’язані ресурси
- Англійська для веб-розробників gRPC
- Англійська для розробників OpenAPI і Swagger
- Англійська для розробників Kafka Streaming
Розробка прикладних програм: технічні засоби
Будьмо чесними - навіть рідні носії англійської іноді борються, щоб точно сформулювати те, що їм потрібно, коли працюють зі складними форматами даних, такими як протокол буферів. Для не-рідних носіїв, тонкі відмінності у фразування і очікування можуть створити значні перешкоди. Це не просто про те, щоб знати слова для field_number або wire_format ; це про те, щоб передати ваш намір чітко і впевнено в професійному контексті. Неправильно вставлене слово може призвести до непорозумінь, затримок і, врешті-решт, переробки.
Одна з поширених областей плутанини виникає під час перегляду коду. Уявіть, що ви отримали такий коментар щодо запитів на завантаження: « Розгляньте збільшення номера поля для user_id — зараз воно зіштовхується з полем, яке раніше не використовувалося ». Негайною реакцією може бути розчарування, якщо ви не розумієте, * чому * це зіткнення є проблемним. Рідний мовець інстинктивно розпізнає це як занепокоєння щодо зворотної сумісності і потенційної пошкодженості даних вниз по лінії. Однак, хтось, хто менш комфортно почувається з технічною англійською, може просто зосередитися на самій інструкції, не повністю розуміючи її логіку. Важливо відповідати обдумано, можливо, кажучи щось на зразок: «Гаразд, я розумію занепокоєння щодо зіткнень номерів полів і зворотної сумісності. Я підлаштую її, щоб уникнути конфліктів і переконатися, що наша схема залишається надійною. ” Це демонструє не тільки розуміння * що *, але також * чому *.
Інший сценарій передбачає опис змін у описі запиту на завантаження. Замість простого зауваження «Оновлені дані профілю користувача», яке є неясним, спробуйте щось на зразок: «Вреалізовано нове повідомлення Protobuf для UserProfile, вирівнюючи з узгодженою схемою версії 2.0. Це включає в себе додавання полів для phone_number і date_of_birth, забезпечуючи зворотну сумісність з існуючими версіями через ретельне присвоєння номерів полів, як це описано в контракті серіалізації. ” Цей рівень деталізації, хоча і потенційно довший, значно зменшує неоднозначність і надає контекст для перегляду, щоб зрозуміти ваш вибір дизайну. Это показывает, что вы рассмотрели более широкие последствия, чем просто модифицирование самих данных.
Нарешті, розмови Slack часто вимагають короткого, але точного спілкування. Розробник може ввести: « Привіт, команда, чи може хтось перевірити визначення Protobuf для служби обробки замовлень? Я бачу потенційні проблеми з тим, як ми обробляємо декілька адрес - потрібно підтвердити, що формат проводу правильно оптимізований для мінімальної пропускної здатності. ” Ключовим тут є впевнене використання специфічного для промисловості словника і переконання, що ви чітко сформулювали конкретну область занепокоєння (оптимізація формату проводу в цьому випадку).
syntax = "proto3";
message UserProfile {
string user_id = 1;
string name = 2;
int32 age = 3;
repeated string email_addresses = 4;
}