Что означает "публичный API" в семантическом управлении версиями?
Я узнаю о том, как назначать и увеличивать номера версий с помощью правила "Семантическое управление версиями" с http://semver.org/.
Среди всех его правил первый сказал:
Программное обеспечение, использующее Semantic Versioning, ДОЛЖНО объявить общедоступный API. Этот API может быть объявлен в самом коде или существовать строго в документации. Как бы это ни было сделано, оно должно быть точным и всеобъемлющим "
Я запутался по поводу "публичного API". Что оно относится к?
5 ответов
Публичный API относится к "точке доступа", которую внешний мир (пользователи, другие программы и / или программисты и т. Д.) Имеют к вашему программному обеспечению.
Например, если вы разрабатываете библиотеку, общедоступный API - это набор всех вызовов методов, которые могут быть сделаны в вашей библиотеке.
Существует понимание того, что, если основная версия не изменится, ваш API будет обратно совместим, то есть все вызовы, которые были действительны для версии, будут действительны для более поздней версии. Вы можете прочитать в пункте 9 этих правил:
Основная версия X (Xyz | X > 0) ДОЛЖНА быть увеличена, если в общедоступный API будут внесены какие-либо обратные несовместимые изменения.
Я открыл для себя SemVer сегодня и прочитал о нем из нескольких источников, чтобы убедиться, что я полностью его понял.
Меня смущает "общедоступный API". Что оно относится к?
Меня это тоже смутило. Я хотел немедленно приступить к использованию SemVer для версии некоторых моих скриптов, но у них не было
public APIи мне даже не было понятно, как они могли его получить.
Лучший ответ, который я нашел, - это тот, который объясняет:
SemVer явно не предназначен для управления версиями всего кода. Это только для кода, у которого есть общедоступный API.
Использование SemVer для версии неправильного программного обеспечения - слишком частый источник разочарования. SemVer не может создавать версии программного обеспечения, в котором не объявленобщедоступный API.
Программное обеспечение , объявляющее общедоступный API, включает библиотеки и приложения командной строки. Программное обеспечение, в котором не объявлен публичный API, включает множество игр и веб-сайтов. Рассмотрим блог; в отличие от библиотеки, у него нет общедоступного API. Другие части программного обеспечения не могут получить к нему программный доступ. Таким образом, концепция обратной совместимости не применима к блогу. Как мы объясним, номера версий semverзависят от обратной совместимости. Из-за этой зависимости semver не поддерживает версии программного обеспечения, как блоги.
Источник: Какое программное обеспечение поддерживает версию SemVer?
Для эффективного применения шаблона управления версиями требуется публичный API.
Например:
Исправления ошибок, не влияющие на API, увеличивают версию патча.
Обратно совместимые дополнения / изменения API увеличивают минорную версию и...
Обратно несовместимые изменения API увеличивают основную версию.
То, что представляет ваш API, является субъективным, поскольку они даже утверждают в документе SemVer:
Это может состоять из документации или выполняться самим кодом.
Семантическое управление версиями предназначено для устранения произвольности, которую можно увидеть, когда кто-то решает выбрать схему управления версиями для своего проекта. Для этого ему нужны правила, а общедоступный API — это правило, которое SemVer выбрал для использования. Если вы создаете личный проект, вам не нужно следовать SemVer или строго следовать ему. Вы можете, например, свободно интерпретировать это как
- ОСНОВНЫЕ: большая новая функция или серьезный рефакторинг
- MINOR: новая функция, которая не сильно влияет на остальную часть кода.
- ПАТЧ: исправление небольшой ошибки
Но расплывчатость этого расплывчатого толкования снова открывает для вас произвол. Это может не иметь значения ни для вас, ни для людей, которые, по вашему мнению, будут использовать ваше программное обеспечение.
Чем больше ваш проект, тем большее значение имеют детали вашей схемы управления версиями. Как человек, который некоторое время работал на третьем уровне поддержки крупной ИТ-компании (которая выдает клиентам лицензии на API), я много раз видел дебаты «это ошибка или функция». SemVer намерен упростить такие различия.
Публичный API, конечно, может быть REST API или общедоступным интерфейсом программной библиотеки. Различие публичного/частного важно, потому что у человека должна быть свобода изменять частный код без негативного влияния на других людей. (Если кто-то получает доступ к вашему личному коду, скажем, посредством отражения, и вы вносите изменения, которые нарушают его код, это его потеря.)
Но общедоступный API может быть даже чем-то вроде переключателей командной строки. Подумайте о POSIXсовместимые инструменты CLI. Эти инструменты являются автономными приложениями. Но они используются в сценариях оболочки, поэтому принимаемые ими входные данные и получаемые ими выходные данные могут иметь значение. Проект GNU может решить повторно реализовать стандартный инструмент POSIX и включить свои собственные функции, но для того, чтобы множество сценариев оболочки продолжали работать в разных системах, они должны поддерживать поведение существующих переключателей для этого приложения. Я видел людей, которым приходилось создавать оболочки вокруг приложений, потому что вывод команды версии меняется, и у них были сценарии, полагающиеся на вывод команды версии, чтобы быть в определенной форме. Должны ли выходные данные команды версии быть частью общедоступного API, или это то, что люди, использующие ее, сделали хаком? Ответ заключается в том, что это зависит от вас и от того, какие гарантии вы даете людям, использующим ваше программное обеспечение. Возможно, вы не сможете представить себе все варианты использования. Заявление о предполагаемом использовании вашего программного обеспечения создает контракт с вашими пользователями, что и является общедоступным API.
Таким образом, SemVer упрощает пользователям задачу узнать, что они получают при обновлении. Менялся только уровень патча? Да, поэтому лучше установить его быстро, чтобы получить последнее исправление. Изменилась ли основная версия? Лучше запустить полный, потенциально дорогостоящий набор регрессионных тестов, чтобы увидеть, будет ли мое приложение работать после обновления.
Прочитав спецификацию несколько раз,
- Программное обеспечение, использующее Semantic Versioning, ДОЛЖНО объявить общедоступный API. Этот API может быть объявлен в самом коде или существовать строго в документации. Как бы это ни было сделано, оно должно быть точным и всеобъемлющим.
Интересно, означает ли это, что потребители вашего программного обеспечения должны быть в состоянии установить точную "семантическую" версию, которую они используют.
Например, я мог бы создать простой скрипт, в котором семантическая версия находится в названии скрипта:
DoStuff_1.0.0.ps1
Это публично и точно. Не только в моей голове:)