Софтуерно инженерство
Версиониране на API без спиране на производството
Практическо ръководство за развиване на API, от които зависят индустриални клиенти, обхващащо стратегии за версиониране, механика на отпадане и как да се провери, че старите клиенти все още работят.

Защо индустриалните API остаряват по различен начин
API, което обслужва производствената площадка, не е същото като API, което обслужва мобилно приложение. Клиентите често са вградени шлюзове, колектори, свързани с PLC, или дълготрайни локални табла, които са въведени в експлоатация преди години и се обновяват в прозорци за поддръжка, а не по график на магазин за приложения. Промяна, която нарушава съвместимостта, може да спре производствената телеметрия и хората, които първи я усетят, не са вашите потребители, а операторите, които наблюдават линията.
Тази статия е за развиването на такива API, без да се налага синхронизирано обновяване на всеки обект. Тя не е заместител на оценка, специфична за обекта, и не заменя вашия собствен преглед на управлението на промените и безопасността.
Какво всъщност нарушава работата на клиента
Първата стъпка е да се съгласим какво означава „нарушаваща съвместимостта“. Една промяна е нарушаваща, ако съществуващ, правилно написан клиент вече не може да прави това, което е правил преди. Често срещани примери включват премахване или преименуване на поле, промяна на типа или единиците на поле, превръщане на незадължително поле в заявката в задължително, затягане на валидацията, промяна на стойности по подразбиране, промяна на кодове за грешки или семантика на пагинацията и промяна на поведението при удостоверяване или ограничаване на честотата без път за преход.
Адитивните промени обикновено са безопасни: ново незадължително поле в отговора, нов крайна точка, нова стойност на изброяване, ако на клиентите е казано да толерират неизвестни стойности. Тънката повреда е клиентът, който десериализира в строга схема и отхвърля неизвестни полета. Това е грешка в клиента, но все пак трябва да я планирате, защото не можете бързо да поправите фърмуера на място.
Избор на стратегия за версиониране
Няма универсално правилна схема, а само компромиси.
- Версиониране в URI (
/v1/readings) е видимо, лесно за маршрутизиране и лесно за логване. То също насърчава увеличаване на версията на цялото API и може да доведе до дублиране на крайни точки. - Версиониране в хедър или медиен тип поддържа URL адресите стабилни и позволява по-фина договорка, но е по-трудно за виждане в логовете и лесно клиентите да го пропуснат по погрешка.
- Без версия, само адитивно работи, когато можете да гарантирате обратна съвместимост и имате силни договорни тестове. Проваля се в момента, в който наистина трябва да промените семантиката.
Практичен модел е стабилен базов път с изрична основна версия, плюс адитивна еволюция в рамките на тази версия. Запазете нова основна версия за семантични промени, които не могат да бъдат изразени адитивно. Избягвайте версиониране на отделни полета; версионирайте договора като цяло.
Отпадането като инженерен процес
Отпадането не е съобщение; то е последователност от наблюдаеми стъпки.
1. Инструментирайте използването по версия и по идентичност на клиента. Не можете да отпишете това, което не можете да измерите. 2. Публикувайте промяната с конкретна дата и ръководство за миграция, не само запис в дневника на промените. 3. Пуснете двете версии паралелно, като старата е в режим на поддръжка (само поправки за сигурност). 4. Предупреждавайте на ниво протокол, където е възможно, например хедър за отговор Deprecation и хедър Sunset, и покажете същата информация в портала за разработчици. 5. Премахнете само след като използването падне до нула или договореният прозорец се затвори, и запазете път за връщане за самото премахване.
Дължината на прозореца зависи от системата. Типично правило в индустриални контексти се измерва в тримесечия, не в седмици, защото циклите на обновяване на фърмуера са бавни. Потвърдете действителното ограничение с екипите, които отговарят за устройствата.
Договорни тестове и проверки, водени от потребителя
Единственият надежден начин да знаете, че една промяна е безопасна, е да я тествате срещу реалните очаквания на клиента. Договорните тестове, водени от потребителя, позволяват на всеки потребител да декларира какво му е необходимо от доставчика, а доставчикът проверява тези очаквания в собствения си pipeline. Това хваща случайни нарушения преди издаването.
Минимален договорен тест за крайна точка за телеметрия може да проверява формата и типовете на задължителните полета, а не техните стойности:
{
"consumer": "line-gateway",
"provider": "telemetry-api",
"interactions": [
{
"description": "fetch latest reading",
"request": { "method": "GET", "path": "/v1/devices/42/readings/latest" },
"response": {
"status": 200,
"body": {
"deviceId": "string",
"timestamp": "string",
"value": "number",
"unit": "string"
}
}
}
]
}Поддържайте договорите фокусирани върху полетата, които потребителят действително използва. Прекаленото специфициране превръща всяка адитивна промяна в фалшива тревога и подкопава доверието в тестовия набор.
Внедряване, връщане и проверка
Версионираните API все още се нуждаят от безопасно внедряване. Използвайте канарско или поетапно внедряване по кохорта от клиенти и поддържайте предишната версия разгръщаема. Флаговете за функции ви помагат да развържете внедряването на код от промяната в поведението, но добавят собствен режим на отказ: остарели флагове, които никой не премахва. Третирайте почистването на флагове като част от промяната.
Проверката трябва да отговори на три въпроса. Дали новата версия се държи както е указано? Дали старите клиенти продължиха да работят? Можете ли бързо да откриете и обърнете регресия? Полезни сигнали включват проценти на грешки по версия, персентили на латентност, неуспехи при валидация на схема на шлюза и телеметрия от страна на клиента за грешки при парсване. Логвайте версията и идентичността на клиента при всяка заявка, за да можете да отговорите на „кой все още е на v1?“ без догадки.
Планът за връщане е реален само ако е бил упражняван. Репетирайте връщането на маршрута на шлюза или версията на услугата в среда за подготовка и потвърдете, че състоянието, записано от новата версия, все още е четимо от старата. Ако не е, имате проблем с миграцията на данни, не само с API.
Практичен контролен списък
- Дефинирайте какво се счита за нарушаваща промяна и го запишете там, където и доставчиците, и потребителите могат да го видят.
- Изберете една схема за версиониране и я прилагайте последователно; документирайте защо сте я избрали.
- Инструментирайте използването по версия и по идентичност на клиента, преди да се наложи да отпишете нещо.
- Предпочитайте адитивни промени; третирайте промените в тип, единица и семантика като нарушаващи.
- Публикувайте заедно датите за отпадане, ръководствата за миграция и предупрежденията на ниво протокол.
- Поддържайте договорни тестове, водени от потребителя, за полетата, от които клиентите действително зависят.
- Внедрявайте по кохорта с канарско пускане и поддържайте предишната версия разгръщаема.
- Репетирайте връщането, включително съвместимостта на данните в двете посоки.
- Наблюдавайте процентите на грешки по версия, латентността и неуспехите при валидация на схема.
- Премахвайте отпадналите версии само след като използването достигне нула или договореният прозорец се затвори, и прегледайте решението с екипите, които отговарят за устройствата.


