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

Даниил Доронкин «Версионирование API»

Даниил Доронкин «Версионирование API»

В докладе будут расмотрены все тонкости версионирования програмного обеспечения. В частности семантическое версионирование, секрет его популярности и области применения. Конечно, затронем версионирование Web API и практические сценарии его использования. Разберём поддержку в библиотеке Microsoft ASP.NET API Versioning и её интеграцию с пакетом Swagger.

Ceecdee9ee77b63d81100be62b7e1090?s=128

DotNetRu

May 24, 2018
Tweet

More Decks by DotNetRu

Other Decks in Programming

Transcript

  1. 1 Версионирование API Доронкин Даниил www.rubius.com

  2. 2 Что обсудим ▪ Версионирование; ▪ Подходы к управлению версиями;

    ▪ SemVer; ▪ Aspnet-api-versioning; ▪ Swagger интеграция. 2
  3. 3 Ассоциации ▪ Уникальное имя; ▪ Эволюция ПО; ▪ Стадия

    готовности; ▪ Минимальное документирование. 3
  4. 4 Примеры ▪ C# 7.2, Python 3.6.4; ▪ .net core

    2.0.6, NodeJs 9.7.1; ▪ VueJs 2.0, Swashbuckle 2.3.0; ▪ http://sdb.amazonaws.com?...&Version=2009-04-15&... ; ▪ Corel Draw 11; ▪ Windows 2000; ▪ Delphi XE; ... 4
  5. 5 Зачем управлять версиями ▪ Контроль изменений и жизненного цикла;

    ▪ Прозрачная работы с зависимостями. 5
  6. 6 Dependency hell 6

  7. 7 Demo 7

  8. 8 8

  9. 9 Инструменты ▪ Nuget; ▪ Npm; ▪ Gb. ... 9

  10. 10 10

  11. 11 Существующие подходы ▪ Целое число: Corel Draw 10; ▪

    Текст: Delphi XE; ▪ Семантическое версионирование: .net core 2.0.6; ▪ Стадия разработки: AspNet.SignalR.Core 1.0.0-alpha1; ▪ Календарное версионирование: Rider 2018.1 ... 11
  12. 12 SemVer ▪ X.Y.Z, где X, Y и Z –

    неотрицательные целые числа; ▪ X – мажорная версия, Y – минорная версия, Z – патч- версия; 12 1. 5. 4 major minor patch
  13. 13 Patch версия ▪ Инкрементируем после баг-фиксов. 13

  14. 14 Minor версия ▪ Добавление совместимой функциональности. 14

  15. 15 Major версия ▪ Breaking changes. 15

  16. 16 Расширение номера версии 16 ▪ Суффикс для отображения стадии

    разработки; 1.0.0-beta2 ▪ Сборочные метаданные. 1.0.0-beta+exp.sha.5114f85
  17. 17 Изменения версии ▪ Версия 0.Y.Z до первого релиза; ▪

    После релиза содержимое пакета не изменяется. 17
  18. 18 Production? ▪ Да - укажите начальную версию 1.0.0; ▪

    Нет - начните с версии 0.1.0. 18
  19. 19 Функциональность устарела ▪ Увеличьте minor-версию: 1.0.0 -> 1.1.0; ▪

    Увеличьте major-версию после удаления: 1.1.0 -> 2.0.0. 19
  20. 20 Стадия разработки ▪ Укажите идентификатор в названии версии: 2.0.0-alpha;

    ▪ 2.0.0-alpha < 2.0.0-beta < 2.0.0 < 3.0.0-alpha < 3.0.0. 20
  21. 21 Размер номера версии ▪ Без ограничений. * чем короче

    - тем лучше :) 21
  22. 22 Внутренние зависимости обновлены 22 ▪ Могут быть рассмотрены как

    внутренние изменения; ▪ Обновлены для правки багов - patch-релиз.
  23. 23 Breaking changes в minor релизе 23 ▪ Верните обратную

    совместимость в новом minor релизе; ▪ Отразите данную проблему в документации; ▪ Проинформируйте пользователей.
  24. 24 Breaking changes вне спецификации 24

  25. 25 Breaking changes вне спецификации 25 ▪ Ориентируйтесь по ситуации;

    ▪ Попробуйте решить проблему напрямую с клиентом; ▪ Обновите спецификацию в minor релизе и следом опубликуйте major релиз с исправлениями.
  26. 26 SemVer 1.0.0 - 2.0.0 26 + Сборочные метаданные; 1.0.0+20130313144700

    1.0.0-beta+exp.sha.5114f85 - SemVerTag. vX.Y.Z
  27. 27 Преимущества ▪ Польза от номера версии; ▪ Формализованный набор

    правил; ▪ Простота. 27
  28. 28 GitVersion SemVer по мотивам git истории. 28

  29. 29 CalVer ▪ Упрощенная семантика; ▪ Чувствительность к дате. 29

    2018. 1 year release
  30. 30 Microsoft aspnet-api-versioning ▪ Управление версиями API; ▪ Open source;

    ▪ Open closed принцип; 30
  31. 31 Подключение 31

  32. 32 Конфигурация через атрибуты 32

  33. 33 Передача версии в запросе 33

  34. 34 Стратегии передачи версии 34 ▪ URL; ▪ Content negotiation;

    ▪ Query parameter.
  35. 35 URL 35 ▪ https://app.com/api/v1.0/<params> - Отдельная точка доступа под

    каждую версию; - Не REST; + Версия всегда на виду; + Легко тестировать.
  36. 36 Content negotiation 36 ▪ accept, content-type; - Тестировать сложнее;

    - Требуется обработка заголовков; + Один ресурс - одна точка доступа; + REST;
  37. 37 Query parameter 37 ▪ https://app.com/api/<params>?api-version=1.0 - Размер URL; -

    Непрозрачное поведение если Query parameter не передан. + Одна и та же endpoint для всех версий; + Версия видна в адресной строке;
  38. 38 Options конфигурация 38

  39. 39 Устаревшая версия 39

  40. 40 Версия по умолчанию 40

  41. 41 Out of version 41

  42. 42 Кастомизация ▪ Способ отправки версии в запросе; ▪ Кастомные

    version-атрибуты; ▪ Переопределение Error response; ... 42
  43. 43 Swagger интеграция 43

  44. 44 Swagger интеграция 44

  45. 45 Demo 45

  46. 46 Подводные камни ▪ Media type API version reader; ▪

    Microsoft.AspNetCore.OData; ▪ Issues на Github. 46
  47. 47 Преимущества ▪ Простой и удобный API. 47

  48. 48 Преимущества ▪ Богатая функциональность; ▪ Кастомизация. 48

  49. 49 Преимущества ▪ Безболезненное внедрение. 49

  50. 50 Преимущества ▪ Swagger интеграция. 50

  51. 51 Источники ▪ https://github.com/Microsoft/aspnet-api-versioning/wiki; ▪ https://semver.org/; ▪ https://gitversion.readthedocs.io/en/latest/; ▪ https://github.com/ddydeveloper/ApiVersioning;

    ▪ https://github.com/ddydeveloper/DependencyHellExample; ▪ https://www.youtube.com/watch?v=ngcigr_8oxw&t=109s. 51
  52. 52 Спасибо за внимание www.rubius.com ddydeveloper@gmail.com 52