Я предлагаю небольшой API веб-сервисов для своих клиентов, которые я планирую со временем развиваться. Поэтому мне нужно какое-то управление версиями, но я не могу найти никакой информации о том, как вы делаете что-то подобное.API-интерфейсы веб-служб
Есть ли практика?
Как я могу продолжать добавлять новые функции без нарушения совместимости с пользователями веб-сервисов?
Добавить параметр «Номер версии API» в качестве параметра во всех ваших API-интерфейсах, а затем применить стратегический паттерн в коде веб-службы, где номер версии определяет, какую стратегию использовать.
Я обычно добавляю строку версии к URL-адресу веб-службы, предоставляя мне «конечные точки с версией». Код, реализующий эти конечные точки, может быть либо общим, если различия тривиальны и могут обрабатываться одним и тем же кодом, либо код может быть клонирован, либо где-то посередине.
Различные конечные точки с версией также могут использовать версии XML-схем, если это то, что вам нужно.
Versioning - сложная тема, поэтому сначала вам нужно определить свои цели более наглядно. Было бы здорово сказать, что у вас есть интерфейс, гарантирующий, что вы никогда не нарушите совместимость, но в зависимости от того, что такое новая функциональность, это может быть даже невозможно. Таким образом, существуют разные ситуации и разные компромиссы.
Если вы намерены предоставлять новые функции только новым пользователям, а все ваши потребители являются прямыми потребителями (без посредников, фреймворков и т. Д.), То выбор оптимальной конечной точки - лучший выбор. Каждый раз, когда вы добавляете функцию, которая рискует перерывом, создайте новую конечную точку, дайте ей новый номер версии, а затем пусть потребители узнают, чтобы проверить ее и переключить их конфигурации. Эта стратегия довольно испробована и верна, но у нее есть недостатки в том, чтобы возлагать нагрузку на потребителей на постоянную актуальность. Кроме того, если есть зависимости между службами, это может стать основной задачей для отслеживания. Воспроизведение вверх, если код сломается, не является (напрямую) вашей ошибкой.
Другой основной стратегией является расширяемый интерфейс. Здесь есть три разных разновидности, о которых я знаю. Во-первых, это тип интерфейса, который так хорошо описывает домен службы, что каждая возможная функция, которую вы могли бы добавить, каким-то образом возможна с учетом существующего интерфейса. Если это звучит сложно, это так. Вы можете назвать это идеальным интерфейсом. Все полностью описано, но весь домен также полностью описан. «Совершенно» действительно только на бумаге.
Второй сорт - это тип, который выглядит как обычный интерфейс, но добавляет общие точки расширения. В WSDL это означает, что xs: любые, пары имя-значение или что-то подобное. Вы можете назвать это основным расширяемым интерфейсом. Это не слишком сложно сделать, но это не без осложнений. Точки расширения могут затруднить работу интерфейса в определенных инструментах (xs: any) или явно потерять часть вашей способности проверять входы и выходы (пары имя-значение). Также довольно легко злоупотреблять этими точками расширения таким образом, чтобы сделать версию 3 или 4 довольно сложно использовать.
Третий сорт - это тип, который преобразует ваш интерфейс в байтовый поток. Вы можете назвать эти интерфейсы богов. Они не лишены своих оправданий, но если вы используете их, вы можете спросить, почему вы используете веб-службы вообще. Возможно, вам стоит подумать о необработанном TCP/IP или базовом HTTP GET/POST. Но, может быть, вам надоела сложность WSDL и XSD, и вы просто хотите начать с нуля, но вы привязаны к веб-сервисам по какой-то причине инфраструктуры. Поймите, однако, что, как только вы начнете с этого пути, вам понадобится совершенно новый способ описать вашим потребителям, как/не использовать вашу службу, и если вы используете XSD для этого. Ну, вы в основном назад, где ты начал.
Лучше всего знать все эти варианты и подойти к дизайну сервиса, сначала попробовав «идеальный интерфейс», а затем откажитесь от добавления и добавьте общие точки расширяемости. Попытка разработать идеальный интерфейс заставит вас научиться вещам, которые улучшат ваше обслуживание, а не только ваш интерфейс, но для этого потребуется время, и если вы не ограничите это время, это будет навсегда.
Немного отстает от интерфейса истинного бога, есть интерфейс оболочки. Если у вас есть слои, вы хотите, чтобы ваш интерфейс тоже был в слоях. Когда вы меняете слой B, вы хотите изменить слой B, а не все экземпляры в слое C.
все немного абстрактно и пирог в небе по своему вкусу. –
Как именно он должен быть наиболее конкретным, учитывая информацию, представленную в исходном вопросе? – HDave
Одна из возможностей заключается в проектировании всех операций веб-сервисов, чтобы иметь только один параметр типа, который наследуется от абстрактного тип, который содержит номер версии. Этот подход реализуется eBay web services platform. Что-то вроде следующего:
<xsd:complexType name="AbstractRequestType">
<xsd:attribute name="version" type="string" />
....
<xsd:complexType name="AddCustomerRequestType">
<xsd:complexContent>
<xsd:extension base="AbstractRequestType">
....
then use AddCustomerRequestType as a type of only parameter
in addCustomer web service operation.
Дополнительно, если вы работаете над HTTP вы можете потребовать, чтобы добавить версию в качестве HTTP GET параметра веб-службы конечной точки URL, так что вы сможете обнаружить запрашиваемую версию легко http://server/service?version=1
наиболее распространенная стратегия, что я видел это версии WSDL путем добавления контроля версий идентификации (обычно yyyy/MM[/dd]) к пространству имен объектов в WSDL, а именно:
targetNamespace="http://schemas.mycompany.com/2010/01/widgets"
Это можно сделать либо на уровне type (types/schema), либо на всем уровне WSDL - <definitions> в 1.1 или <description> в 2.0.
несколько устарел, но this link от IBM Developer Works дает основание для такого подхода, и, в частности, когда версии должны быть увеличены:
задом версия Compatable/неразрывных изменения:
Ломая изменения:
Это будет работать только в том случае, если Версионированные веб-службы принимают * точно * те же аргументы, поэтому применяется тот же WSDL. Если в новой версии требуется добавление нового атрибута, что вы делаете? –