Upgrade to Pro — share decks privately, control downloads, hide ads and more …

Кирилл Лихтарович «Версионирование и кодогенерация в REST API»

Ceecdee9ee77b63d81100be62b7e1090?s=47 DotNetRu
November 18, 2020

Кирилл Лихтарович «Версионирование и кодогенерация в REST API»

Кирилл расскажет о проблемах версионирования REST API на примерах, покажет какие способы версионирования он применяет и в чём их отличие друг от друга. Познакомимся с разницей между code first и contract first подходов и о том, почему он выбрал contract first как основной для проектирования новых API. Расскажет о кодогенерации и сделает акцент на связке кодогенерации с версионированием. Покажет приниципиальную схему кодогенератора, позволяющего прозрачно и понятно поддерживать разные версии вашего API.

Ceecdee9ee77b63d81100be62b7e1090?s=128

DotNetRu

November 18, 2020
Tweet

Transcript

  1. © 2020 Veeam Software. Confidential information. All rights reserved. All

    trademarks are the property of their respective owners. Кирилл Лихтарович Experienced developer Telegram: @likhtarovich Версионирование и кодогенерация в REST API
  2. © 2020 Veeam Software. Confidential information. All rights reserved. All

    trademarks are the property of their respective owners. Veeam в числах 400,000+ Клиентов в мире, 82% Клиентов из Fortune 500 Санкт-Петербург Прага Офисы R&D: 35+ Стран присутствия 4400+ Сотрудников В 3.5 раза Выше удовлетворенность клиентов, чем в среднем по индустрии 13 28 66 145 298 515 833 986 1259 2020 2600 3000 3500 4,3K+ 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 Veeam ONE Veeam Agent for Windows Veeam Agent for Linux VB for Microsoft Office 365 VA Console Orchestrator VA for Nutanix Veeam Agent for Unix Veeam FastSCP Veeam Monitor for VMware Veeam Reporter Veeam Management Pack Veeam Backup & Replication Сотрудники Продукты $1+ млрд. Выручка в 2019
  3. 3 REST API в Veeam Veeam Backup & Replication Veeam

    Service Provider Console Veeam Availability Orchestrator Veeam Backup for Microsoft Office 365 Veeam ONE Veeam Backup Enterprise Manager
  4. 4 Структура доклада 1. Версионирование 1. Обратная совместимость 2. Методы

    версионирования для REST API 3. Два способа проектирования REST API 2. Кодогенерация 1. Схема кодогенератора 2. С чего начать собственную реализацию
  5. 5 Версия ПО ProductVersion Major.Minor.Build MyService 3.1.0-rev-8 Windows 10.0.18362.476

  6. 6 Обратная совместимость REST API Client library v1.0 REST API

    Service v1.0 REST API Service v1.1 REST API specification v1.0 REST API Client library v1.1 REST API specification v1.1
  7. 7 Обратная совместимость

  8. 8 Виды изменений Ломающие: нарушающие предыдущий контракт Неломающие: дополняющие предыдущий

    контракт
  9. 9

  10. 10 Неломающие изменения в REST • добавление новых путей, ресурсов

    и действий над ними • расширение существующих моделей • добавление/изменение/удаление ссылок (если HATEOS)
  11. 11 Методы версионирования https://api/v2/Tasks/{TaskId} https://api/Tasks/{TaskId}?v=2 application/App.v2.param.json HTTP x-api-version: 2

  12. 12 Версия в URI HTTP POST https://storage.googleapis.com/storage/v1/b DELETE /2015-03-31/functions/FunctionName?Qualifier=Qualifier HTTP/1.1

  13. 13 Версия в Query Path HTTP GET https://status.dev.azure.com/_apis/status/health?services={services}&api-version=6.0-preview.1 HTTP GET

    https://autoscaling.amazonaws.com/?Action=SetInstanceHealth&InstanceId=i-12345678 &HealthStatus=Unhealthy&Version=2011-01-01
  14. 14 Версия в Media Type

  15. 15 Версия в X-Header

  16. 16 Комбинирование версий

  17. 17 Реализации версионирования Инкапсуляция предыдущей версии Расширение предыдущего контракта Отдельные

    модели и контроллеры для нового контракта Расширение предыдущей версии Трансформация моделей между версиями
  18. 18 НА ЭТАПЕ ПРОЕКТИРОВАНИЯ Неверный метод версионирования Отсутствие фиксации «контрактов»

    Проектирование доменной области без учета новых версий Инкапсуляция предыдущей версии read-only read-only read-only read-only
  19. 19 Расширение предыдущей версии

  20. 20 Проектирование REST API Code-First Contract-First

  21. 21 Code-First подход Code-First

  22. 22 Contract-First подход Contract-First

  23. 23 Почему Contract-first  разработка клиента и сервера одновременно 

    документация прямо в спецификации  новые фичи – прямо в спецификации  гарантированность контракта
  24. 24

  25. © 2020 Veeam Software. Confidential information. All rights reserved. All

    trademarks are the property of their respective owners. Кодогенерация
  26. 26

  27. 27

  28. 28  Быстро добавлять новые ресурсы и пути  Избежать

    дублирования бизнес-логики  Минимизировать версионные изменения  Гарантировать обратную совместимость Основные требования
  29. 29 Business-Logic Mapping From Version 1.2 To Version 1.3 Принципиальная

    схема Mapping From Version 1.3 To Latest read-only read-only
  30. 30 Business-Logic Virtual controller

  31. 31 Virtual controller

  32. 32 Business-Logic Абстракция бизнес-логики

  33. 33 Абстракция бизнес-логики

  34. 34 Business-Logic Mapping From Version 1.2 To Version 1.3 Принципиальная

    схема Mapping From Version 1.3 To Latest read-only read-only
  35. 35 Business-Logic Абстракция моделей

  36. 36 Абстракция моделей

  37. 37 Business-Logic Трансформация моделей Mapping From Version 1.2 To Latest

  38. 38 Mapping From Version 1.2 To Version 1.3 Трансформация моделей

    Mapping From Version 1.3 To Latest Business-Logic read-only read-only
  39. 39 Business-Logic Mapping From Version 1.2 To Version 1.3 Принципиальная

    схема Mapping From Version 1.3 To Latest read-only read-only
  40. 40 Полезные ресурсы для старта https://github.com/swagger-api/swagger-codegen https://github.com/RicoSuter/NSwag https://www.nuget.org/packages/Microsoft.AspNetCore.Mvc.Versioning https://www.nuget.org/packages/AutoMapper/ КОДОГЕНЕРАТОРЫ:

    ПОДДЕРЖКА ВЕРСИЙ: ТРАНСФОРМАЦИЯ МОДЕЛЕЙ: РЕДАКТОР СПЕЦИФИКАЦИИ ДЛЯ CONTRACT-FIRST РАЗРАБОТКИ: https://editor.swagger.io/ https://swagger.io/blog/api-design/design-first-or-code-first-api-development/
  41. 41 Мнение о кодогенераторе «Он нам очень сильно сократил время

    разработки рест сервиса. Если бы делали с нуля, то думаю там несколько месяцев ушло бы, а так пара недель и уже можно было делать UI и дёргать какие-то сервисные методы...» Семен П., Разработчик «Contract-first подход в разработке оказался очень удобным, просто описываешь спецификацию, а потом реализуешь бизнес-логику. Не надо вручную создавать контроллеры и модели» Александр Ш., Разработчик «Кодогенератор мы используем двух проектах. Он позволяет значительно ускорить работу и избавляет от необходимости писать рутинный код. Также автоматизированная генерация исключает возникновение ошибок в сгенерированном коде, особенно при рефакторинге – достаточно внести изменения в спецификацию и сгенерировать новые классы» Андрей П., Разработчик
  42. 42

  43. © 2020 Veeam Software. Confidential information. All rights reserved. All

    trademarks are the property of their respective owners. Спасибо!