← Tüm yazılar

Yazılım mühendisliği

Fabrika Zeminini Bozmadan API Sürümleme

Endüstriyel istemcilerin bağımlı olduğu API'leri geliştirmeye yönelik bir uygulayıcı kılavuzu: sürümleme stratejileri, kullanımdan kaldırma mekanikleri ve eski istemcilerin hâlâ çalıştığını doğrulama.

Rootcastle Engineering & Innovation5 dk okuma
Fabrika cihazlarından ve panolardan arka uç hizmetlerine sürümlenmiş istekleri yönlendiren bir API ağ geçidinin genel gösterimi; sözleşme testi ve izleme sembolleriyle birlikte.

Endüstriyel API'ler neden farklı yaşlanır

Bir fabrika zeminine hizmet eden API, bir mobil uygulamaya hizmet eden API ile aynı değildir. İstemciler genellikle gömülü ağ geçitleri, PLC'ye yakın toplayıcılar veya yıllar önce devreye alınmış ve uygulama mağazası programlarıyla değil bakım pencereleriyle güncellenen uzun ömürlü şirket içi panolardır. Yıkıcı bir değişiklik üretim telemetrisini durdurabilir ve bunu ilk hissedenler kullanıcılarınız değil, hattı izleyen operatörlerdir.

Bu makale, her sahada eşzamanlı yükseltmeleri zorlamadan bu API'leri geliştirmekle ilgilidir. Sahaya özgü bir değerlendirmenin yerini tutmaz ve kendi değişiklik yönetimi ve güvenlik incelemenizin yerini almaz.

Bir istemciyi gerçekte ne bozar

İlk adım, "yıkıcı"nın ne anlama geldiği konusunda anlaşmaktır. Mevcut, doğru yazılmış bir istemci artık eskiden yaptığını yapamıyorsa değişiklik yıkıcıdır. Yaygın örnekler arasında bir alanı kaldırmak veya yeniden adlandırmak, bir alanın türünü veya birimini değiştirmek, isteğe bağlı bir istek alanını zorunlu kılmak, doğrulamayı sıkılaştırmak, varsayılan değerleri değiştirmek, hata kodlarını veya sayfalama semantiğini değiştirmek ve bir geçiş yolu olmadan kimlik doğrulama veya hız sınırı davranışını değiştirmek yer alır.

Eklemeli değişiklikler genellikle güvenlidir: yeni bir isteğe bağlı yanıt alanı, yeni bir uç nokta, istemcilere bilinmeyen değerleri tolere etmeleri söyleniyorsa yeni bir enum değeri. İnce başarısızlık, katı bir şemaya serileştiren ve bilinmeyen alanları reddeden istemcidir. Bu bir istemci hatasıdır, ancak yine de bunun için plan yapmalısınız, çünkü sahada ürün yazılımını hızlıca yamalayamazsınız.

Bir sürümleme stratejisi seçmek

Evrensel olarak doğru bir şema yoktur, yalnızca ödünleşimler vardır.

  • URI sürümleme (/v1/readings) görünürdür, yönlendirmesi kolaydır ve günlüğe kaydetmesi kolaydır. Aynı zamanda tüm API sürüm artışlarını teşvik eder ve yinelenen uç noktalara yol açabilir.
  • Başlık veya ortam türü sürümleme URL'leri sabit tutar ve daha ince taneli pazarlığa izin verir, ancak günlüklerde görmek daha zordur ve istemcilerin kazara atlaması kolaydır.
  • Sürüm yok, yalnızca eklemeli geriye dönük uyumluluğu garanti edebildiğinizde ve güçlü sözleşme testleriniz olduğunda işe yarar. Gerçekten semantiği değiştirmeniz gerektiği anda başarısız olur.

Pratik bir desen, açık bir ana sürüm içeren sabit bir temel yoldur ve bu sürüm içinde eklemeli evrimdir. Yeni bir ana sürümü, eklemeli olarak ifade edilemeyen semantik değişiklikler için ayırın. Tek tek alanları sürümlemekten kaçının; sözleşmeyi bir bütün olarak sürümleyin.

Mühendislik süreci olarak kullanımdan kaldırma

Kullanımdan kaldırma bir duyuru değildir; gözlemlenebilir adımlar dizisidir.

1. Sürüm başına ve istemci kimliği başına kullanımı izleyin. Ölçemediğiniz şeyi kullanımdan kaldıramazsınız. 2. Değişikliği somut bir tarih ve bir geçiş kılavuzuyla yayımlayın, sadece bir değişiklik günlüğü girdisiyle değil. 3. Her iki sürümü paralel çalıştırın, eski sürüm bakım modunda (yalnızca güvenlik düzeltmeleri) olsun. 4. Mümkün olduğunda protokol düzeyinde uyarın, örneğin bir Deprecation yanıt başlığı ve bir Sunset başlığı ve aynı bilgiyi geliştirici portalınızda gösterin. 5. Yalnızca kullanım sıfıra düştükten veya kararlaştırılan pencere kapandıktan sonra kaldırın ve kaldırmanın kendisi için bir geri alma yolu tutun.

Pencere uzunluğu sisteme bağlıdır. Endüstriyel bağlamlarda tipik bir deneyim kuralı haftalar değil çeyreklerle ölçülür, çünkü ürün yazılımı güncelleme döngüleri yavaştır. Gerçek kısıtı cihazların sahibi olan ekiplerle doğrulayın.

Sözleşme testleri ve tüketici odaklı kontroller

Bir değişikliğin güvenli olduğunu bilmenin tek güvenilir yolu, onu gerçek istemci beklentilerine karşı test etmektir. Tüketici odaklı sözleşme testleri, her tüketicinin sağlayıcıdan neye ihtiyacı olduğunu bildirmesine izin verir ve sağlayıcı bu beklentileri kendi işlem hattında doğrular. Bu, sürümden önce kazara bozulmayı yakalar.

Bir telemetri uç noktası için minimal bir sözleşme testi, gerekli alanların değerlerini değil şeklini ve türlerini doğrulayabilir:

{
  "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"
        }
      }
    }
  ]
}

Sözleşmeleri tüketicinin gerçekte kullandığı alanlara odaklı tutun. Aşırı belirtme, her eklemeli değişikliği yanlış alarm haline getirir ve test paketine olan güveni aşındırır.

Dağıtım, geri alma ve doğrulama

Sürümlenmiş API'ler yine de güvenli dağıtıma ihtiyaç duyar. İstemci grubu başına kanarya veya aşamalı dağıtım kullanın ve önceki sürümü dağıtılabilir tutun. Özellik bayrakları, kod dağıtımını davranış değişikliğinden ayırmanıza yardımcı olur, ancak kendi başarısızlık modlarını ekler: kimsenin kaldırmadığı bayat bayraklar. Bayrak temizliğini değişikliğin bir parçası olarak ele alın.

Doğrulama üç soruyu yanıtlamalıdır. Yeni sürüm belirtildiği gibi davrandı mı? Eski istemciler çalışmaya devam etti mi? Bir gerilemeyi hızlıca tespit edip tersine çevirebilir misiniz? Yararlı sinyaller arasında sürüm başına hata oranları, gecikme yüzdelikleri, ağ geçidinde şema doğrulama hataları ve ayrıştırma hataları hakkında istemci tarafı telemetrisi bulunur. Her istekte sürümü ve istemci kimliğini günlüğe kaydedin, böylece "kim hâlâ v1'de?" sorusunu tahmin yürütmeden yanıtlayabilirsiniz.

Bir geri alma planı ancak denenmişse gerçektir. Bir hazırlık ortamında ağ geçidi rotasını veya hizmet sürümünü geri almayı prova edin ve yeni sürüm tarafından yazılan durumun eski sürüm tarafından hâlâ okunabildiğini doğrulayın. Değilse, yalnızca bir API sorununuz değil, bir veri taşıma sorununuz var demektir.

Pratik bir kontrol listesi

  • Yıkıcı değişiklik olarak neyin sayıldığını tanımlayın ve hem sağlayıcıların hem de tüketicilerin görebileceği bir yere yazın.
  • Bir sürümleme şeması seçin ve tutarlı bir şekilde uygulayın; neden seçtiğinizi belgeleyin.
  • Herhangi bir şeyi kullanımdan kaldırmanız gerekmeden önce sürüm başına ve istemci kimliği başına kullanımı izleyin.
  • Eklemeli değişiklikleri tercih edin; tür, birim ve semantik değişiklikleri yıkıcı olarak değerlendirin.
  • Kullanımdan kaldırma tarihlerini, geçiş kılavuzlarını ve protokol düzeyindeki uyarıları birlikte yayımlayın.
  • İstemcilerin gerçekte bağımlı olduğu alanlar için tüketici odaklı sözleşme testlerini sürdürün.
  • Kanarya ile grup başına dağıtım yapın ve önceki sürümü dağıtılabilir tutun.
  • Her iki yönde veri uyumluluğu dahil olmak üzere geri almayı prova edin.
  • Sürüm başına hata oranlarını, gecikmeyi ve şema doğrulama hatalarını izleyin.
  • Kullanımdan kaldırılmış sürümleri yalnızca kullanım sıfıra ulaştıktan veya kararlaştırılan pencere kapandıktan sonra kaldırın ve kararı cihazların sahibi olan ekiplerle gözden geçirin.
api-sürümlemeendüstriyel-yazılımsözleşme-testikullanımdan-kaldırmagözlemlenebilirliksürüm-yönetimi

Güncellendi: 29.10.2026

Komut veya sayfa ara