Сведите правила операции в общий прикладной сервис, а различия gRPC и HTTP/JSON опишите на границе интерфейсов. Два входа не должны независимо решать, кто вправе изменить объект и какие значения допустимы. Начните с одной операции и таблицы одинаковых входных смыслов, включая отсутствие поля и явное обнуление.
gRPC-Gateway умеет генерировать reverse proxy из описания gRPC и предоставлять JSON API. Это полезный транспортный механизм, но генерация не определяет ваш продуктовый контракт. Названия ресурсов, поведение повторов, совместимость старых клиентов и публичность полей требуют отдельных решений команды.
Внешняя схема не обязана повторять внутреннее сообщение целиком
| Смысл входа | Контроль |
|---|---|
| Поле отсутствует | Правило сохранения значения |
| Явное пустое значение | Правило очистки |
| Чужой объект | Отказ без изменения |
| Повтор операции | Один подтверждённый эффект |
Официальная документация gRPC-Gateway и ProtoJSON проверена 4 ноября 2026 года. Перед публикацией выберите поля, которые действительно предназначены внешнему клиенту. Внутренние диагностические признаки, служебные состояния и идентификаторы инфраструктуры могут не подходить для публичной схемы.
Не считайте бинарный Protobuf и JSON взаимозаменяемыми при изменениях контракта. Документация ProtoJSON описывает собственное представление типов и правила совместимости. Изменение, безопасное для бинарного обмена, нужно отдельно оценить для JSON-клиента и его сохранённых запросов.
Составьте примеры отсутствующего значения, нуля, пустой строки и неизвестного enum. Для поля изменения профиля это могут быть разные намерения. Если операция должна различать «не менять» и «очистить», выберите явную модель присутствия или изменения полей и подтвердите её на обоих входах.
Одна авторизация проверяется через два транспорта
На входах может различаться способ передачи credentials, но прикладной субъект и его права должны быть определены однозначно. Проверьте запрос к своей и чужой записи через gRPC и через HTTP. Успех gateway в преобразовании JSON не разрешает операции, запрещённой владельцу credentials.
Условная контрактная матрица:
операция: изменить контакт
transport: gRPC / HTTP JSON
subject + object owner
поле отсутствует / очищено / задано
request key + ожидаемый эффектНе доверяйте tenant или user ID из тела только потому, что их проверяет внутренний клиент. Внешний потребитель способен отправить другие значения. Общая проверка должна связывать объект с авторизованным контекстом и отклонять чужое действие до изменения данных.
Условный дефект: gRPC-обработчик применяет правило доступности поля, а REST-контроллер пишет напрямую в ту же таблицу. После добавления нового ограничения интерфейсы расходятся. Перенос правила в общий слой устраняет причину; тесты должны подтверждать не только ответ, но и отсутствие записи после отказа.
Повторная отправка не должна создавать вторую операцию
Для изменяющей операции согласуйте ключ идемпотентности, область его уникальности и срок сохранения результата. HTTP-клиент и RPC-клиент могут по-разному повторять запросы после разрыва. Решение о том, что два обращения означают одно действие, должно принадлежать бизнес-операции.
Проверьте повтор с тем же ключом и другим содержимым. Молчаливое принятие неоднозначного запроса скрывает ошибку интегратора. Определите явный отказ или иной документированный результат и подтвердите одинаковое состояние данных за обоими транспортами.
Не превращайте streaming RPC в обещание обычного JSON-массива без проверки потребителя. У потокового HTTP-представления свои границы сообщений и обработка ошибки после начала ответа. Если внешнему API нужны пагинация или задача с последующим получением результата, опишите эту модель отдельно вместо механического копирования внутреннего stream.
- Выбрать одну операцию и внешний набор полей.
- Сопоставить значения и присутствие полей.
- Проверить права и повторы на двух входах.
- Зафиксировать различия JSON и бинарного контракта.
Для приёмки подготовьте таблицу эквивалентных запросов, безопасные примеры JSON, версии схемы и ожидаемые эффекты. Прогон идёт через настоящий gateway и настоящий gRPC-вход на тестовых данных. Контракт считается общим, когда совпадают права и результат операции, а различия транспорта явно описаны и стабильны для клиентов.