Поскольку услуги развертываются независимо, вы никогда не можете предположить, что вызывающие элементы обновляются синхронно. Версионирование API плюс обратная совместимость позволяет производителям эволюционировать без нарушения существующих потребителей.
| Стратегия | Пример |
|---|
| Путь URI | GET /v2/orders/42 |
| Заголовок | Accept: application/vnd.api.v2+json |
| Эволюция схемы | добавляйте поля, никогда не удаляйте/переименовывайте |
NON-BREAKING (safe):
✓ add a new optional field
✓ add a new endpoint
✓ add a new enum value (if clients tolerate unknowns)
BREAKING (needs a new version):
✗ remove or rename a field
✗ change a type or make a field required
✗ change semantics of an existing field
message Order {
string id = 1;
double total = 2;
string currency = 3; // NEW field 3 — old clients ignore it safely
}
Номера полей, а не их названия, определяют формат провода, поэтому добавление полей обратно совместимо.
Release v2 ─▶ run v1 + v2 together ─▶ migrate consumers ─▶ deprecate v1 ─▶ remove v1
Никогда не удаляйте версию, пока её по-прежнему использует реальный трафик. Отслеживайте использование перед выводом из эксплуатации.
Независимое развертывание работает только в том случае, если производитель может доставить изменение без координации выпуска каждого потребителя.
Проектирование с учетом дополнительных изменений и поддержка старых версий во время миграции — это то, что сохраняет эту независимость вместо того, чтобы требовать хрупких обновлений типа big-bang.