Блог

Существуют ли какие-либо рекомендации по внедрению управления версиями API? Меня интересуют следующие моменты:

1. Контроллер, служба — например, используем ли мы другой класс контроллера для каждой версии API? Наследует ли более новый класс контроллера более старый контроллер?
2. Модель — если версии API содержат разные версии одной и той же модели — как мы обрабатываем преобразования? Например, если v1 API использует v1 модели, а v2 API использует v2 модели, и мы хотим поддерживать оба (для обратной совместимости)-как мы выполняем преобразования?
3. Существуют ли существующие фреймворки/библиотеки, которые я могу использовать для этих целей на Java и JavaScript?

Спасибо!

1. Я всегда рекомендую отдельный класс контроллера для каждой версии API. Это делает вещи чистыми и понятными для сопровождающих. Следующую версию обычно можно запустить, скопировав и вставив последнюю версию. Вы должны определить четкую политику управления версиями; например, версии N-2. Поступая таким образом, вы получаете 3 параллельные реализации, а не взрыв, который, по мнению некоторых людей, у вас будет. Рефакторинг бизнес-логики и других компонентов, не относящихся к версии HTTP API, из контроллеров может помочь уменьшить дублирование кода.
2. По моему глубокому убеждению, контроллер абсолютно не должен наследовать от другого контроллера, за исключением базового контроллера с функциональностью, не зависящей от версии (но не API). HTTP-это API. HTTP имеет методы, а не глаголы. Думайте об этом так Http.get() . Использование другого языка, такого как Java, C# и т. Д., Является фасадом, Который является несоответствием импеданса HTTP. HTTP не поддерживает наследование, поэтому попытка использовать наследование в реализации может только усугубить проблему несоответствия. Существуют и другие практические проблемы. Например, вы можетеунаследованный метод, который усложняет проблему настройки API в унаследованных контроллерах (не все версии являются аддитивными). Отладка также может привести к путанице, поскольку для установки точки останова необходимо найти правильную реализацию. Если я немного подумаю над политикой управления версиями и распределением обязанностей по другим компонентам, это все, но, по моему опыту, сведет на нет необходимость наследования.
3. Преобразование модели-это деталь реализации. Это зависит исключительно от сервера. Поддержка конверсий очень ситуативна. Преобразования могут быть двунаправленными ( v1<->v2 ) или однонаправленными ( v2->v1 ). Картограф-довольно распространенный способ преобразования одной формы в другую. Сценарии аддитивных атрибутов часто просто требуют значения по умолчанию для новых атрибутов в хранилище для более старых версий API. В конечном счете, для всех сценариев нет единого ответа на эту проблему.
4. Следует отметить, что обратная совместимость-неправильное название в HTTP. На самом деле такого не существует. Версия API-это контракт, который включает в себя модель. Удобство или легкость, с помощью которых новая версия модели может быть преобразована в/из старой версии модели, следует рассматривать именно как удобство. Легко думать, что аддитивное изменение способно к обратному, но сервер не может гарантировать, что оно будет с клиентами. Поразительное понятие обратной способности в контексте HTTP поможет вам попасть в яму успеха.
5. Использование открытого API (ранее известного как Swagger), вероятно, является лучшим вариантом для интеграции клиентов с любым языком. Существуют инструменты, которые могут использовать документ для создания клиентов на предпочитаемом вами языке программирования. У меня нет конкретной рекомендации для библиотеки/платформы Java на стороне сервера, но есть несколько вариантов.