Mikro hizmetlerin dinamik dünyasında her şey değişebilir; her bileşen farklı çerçeveler ve mimariler kullanılarak farklı bir dilde yeniden yazılabilir. Dahili metamorfozlardan bağımsız olarak mikro hizmetin dışarıdan kalıcı olarak etkileşime girebilmesi için yalnızca sözleşmeler değişmeden kalmalıdır. Bugün de sözleşmeleri açıklamak için format seçme problemimiz hakkında konuşacağız ve bulduğumuz eserleri paylaşacağız.
Gönderi hazırlandı и
Mikro hizmetler. Acronis Cyber Cloud'u geliştirirken onlardan kaçamayacağımızı anladık. Mikro hizmetin arayüzünü temsil eden sözleşmeyi resmileştirmeden bir mikro hizmet tasarlamak imkansızdır.
Ancak bir ürün birden fazla bileşen içerdiğinde ve sözleşme geliştirme düzenli bir faaliyet haline geldiğinde, süreç optimizasyonu hakkında düşünmeden duramazsınız. Arayüz (sözleşme) ve uygulamanın (mikro hizmet) birbiriyle eşleşmesi gerektiği, farklı bileşenlerin aynı şeyleri aynı şekilde yapması gerektiği ve tüm bu kararların merkezi bir karara bağlanması olmadan her ekibin aynı şeyi yapmak zorunda kalacağı açık hale geliyor. onları elde etmek için tekrar tekrar zaman harcayın.
Amazon mikro hizmetler diyagramı Werner Vogelis, Amazon CTO'su
İkilem nedir? Fiili olarak mikro hizmetlerle etkileşim kurmanın iki yolu vardır: HTTP Rest ve Google'dan gRPC. Google'ın teknoloji yığınına kapılmak istemediğimiz için HTTP Rest'i seçtik. HTTP REST sözleşme ek açıklamaları çoğunlukla iki formattan birinde tanımlanır: RAML ve OAS (önceden Swagger olarak biliniyordu). Bu nedenle, her geliştirme ekibi standartlardan birini seçme ihtiyacıyla karşı karşıya kalır. Ancak görünen o ki bu seçimi yapmak çok zor olabilir.
Ek açıklamalara neden ihtiyaç duyulur?
Ek açıklama, harici bir kullanıcının HTTP arayüzü aracılığıyla hizmetinizle neler yapılabileceğini kolayca anlayabilmesi için gereklidir. Yani, temel düzeyde ek açıklama en azından mevcut kaynakların bir listesini, bunların HTTP yöntemlerini, istek gövdelerini, parametrelerin bir listesini, gerekli ve desteklenen başlıkların bir göstergesinin yanı sıra dönüş kodları ve yanıt formatlarını içermelidir. Sözleşme ek açıklamasının son derece önemli bir unsuru sözlü açıklamasıdır (“bu sorgu parametresini talebe eklerseniz ne olacak?”, “400 kodu hangi durumda döndürülür?”)
Ancak konu çok sayıda mikro hizmet geliştirmeye geldiğinde, yazılı ek açıklamalardan ek değer elde etmek istersiniz. Örneğin, RAML/Swagger'ı temel alarak çok sayıda programlama dilinde hem istemci hem de sunucu kodu oluşturabilirsiniz. Ayrıca mikro hizmetin belgelerini otomatik olarak alabilir ve geliştirici portalınıza yükleyebilirsiniz :).
Yapılandırılmış sözleşme açıklaması örneği
Daha az yaygın olan ise mikro hizmetlerin sözleşme açıklamalarına göre test edilmesidir. Hem ek açıklama hem de bileşen yazdıysanız, çeşitli türdeki giriş verileriyle hizmetin yeterliliğini kontrol eden bir otomatik test oluşturabilirsiniz. Hizmet, ek açıklamada açıklanmayan bir yanıt kodu döndürüyor mu? Açıkça yanlış olan verileri doğru bir şekilde işleyebilecek mi?
Üstelik, yalnızca sözleşmelerin değil, aynı zamanda ek açıklamaların görselleştirilmesine yönelik araçların da yüksek kalitede uygulanması, mikro hizmetle çalışmayı basitleştirmeyi mümkün kılar. Yani, mimar sözleşmeyi niteliksel olarak tanımlamışsa, buna dayanarak tasarımcılar ve geliştiriciler hizmeti ek zaman maliyeti olmadan diğer ürünlere uygulayacaklardır.
Ek araçları etkinleştirmek için hem RAML hem de OAS, standart tarafından sağlanmayan meta verileri ekleme yeteneğine sahiptir ().
Genel olarak, mikro hizmetler için sözleşmelerin kullanılmasında yaratıcılığın kapsamı çok büyüktür... en azından teoride.
Kirpi ile yılanın karşılaştırılması
Şu anda Acronis'in öncelikli geliştirme alanı Acronis Siber Platformunun geliştirilmesidir. Acronis Cyber Platform, üçüncü taraf hizmetlerin Acronis Cyber Cloud ve temsilci kısmıyla entegrasyonunun yeni noktalarıdır. RAML'de açıklanan dahili API'lerimizden memnun olsak da, API'yi yayınlama ihtiyacı tekrar seçim sorusunu gündeme getirdi: Çalışmamız için hangi ek açıklama standardını kullanmak en iyisidir?
Başlangıçta iki çözüm varmış gibi görünüyordu; en yaygın gelişmeler RAML ve Swagger (veya OAS) idi. Ama aslında en az 2 değil, 3 veya daha fazla alternatifin olduğu ortaya çıktı.
Bir yanda güçlü ve etkili bir dil olan RAML var. Hiyerarşiyi ve kalıtımı iyi bir şekilde uygular, dolayısıyla bu format, çok sayıda açıklamaya (yani tek bir ürüne değil, sözleşmelerin ortak bölümlerine sahip birçok mikro hizmete) ihtiyaç duyan büyük şirketler için daha uygundur - kimlik doğrulama şemaları, aynı veri türleri, hata gövdeleri .
Ancak RAML'ın geliştiricisi Mulesoft, Open API konsorsiyumuna katıldı. . Bu nedenle RAML gelişimini askıya aldı. Etkinliğin formatını hayal etmek için, ana Linux bileşenlerinin bakımcılarının Microsoft için çalışmak üzere ayrıldığını hayal edin. Bu durum, dinamik olarak gelişen ve en son üçüncü versiyonda esneklik ve işlevsellik açısından RAML'ı pratik olarak yakalayan Swagger'ı kullanmanın ön koşullarını yaratıyor.
Bir şey için değilse ama ...
Görünen o ki tüm açık kaynak yardımcı programları OAS 3.0'a güncellenmedi. Go'daki mikro hizmetler için en kritik şey adaptasyon eksikliği olacak Standardın en son sürümü için. Ancak Swagger 2 ile Swagger 3 arasındaki fark . Örneğin, üçüncü versiyonda geliştiriciler:
- kimlik doğrulama şemalarının geliştirilmiş açıklaması
- JSON Şeması desteği
- Örnek ekleme yeteneği geliştirildi
Durum komik: Standart seçerken RAML, Swagger 2 ve Swagger 3'ü ayrı alternatifler olarak düşünmeniz gerekiyor. Ancak yalnızca Swagger 2, Açık Kaynak araçları için iyi bir desteğe sahiptir. RAML çok esnek... ve karmaşıktır ve Swagger 3 topluluk tarafından yeterince desteklenmemektedir, dolayısıyla oldukça pahalı olan özel araçları veya ticari çözümleri kullanmanız gerekecektir.
Üstelik Swagger'da hazır portal gibi pek çok güzel özellik varsa Bir ek açıklama yükleyebileceğiniz ve ayrıntılı bir açıklama, bağlantılar ve bağlantılarla görselleştirmesini alabileceğiniz, daha temel ve daha az kullanıcı dostu RAML için böyle bir fırsat yoktur. Evet, GitHub'daki projeler arasında bir şeyler arayabilir, orada bir analog bulabilir ve onu kendiniz dağıtabilirsiniz. Bununla birlikte, her durumda, birisinin portalın bakımını yapması gerekecek ve bu, temel kullanım veya test ihtiyaçları için pek uygun değildir. Ek olarak, havalılık daha "ilkesizdir" veya daha liberaldir; koddaki yorumlardan üretilebilir, bu da elbette API'nin ilk ilkesine aykırıdır ve RAML yardımcı programlarının hiçbiri tarafından desteklenmez.
Bir zamanlar daha esnek bir dil olarak RAML ile çalışmaya başladık ve bunun sonucunda birçok şeyi kendimiz yapmak zorunda kaldık. Örneğin, projelerden biri yardımcı programı kullanıyor yalnızca RAML 0.8'i destekleyen birim testlerinde. Bu nedenle yardımcı programın RAML 1.0 sürümünü "yiyebilmesi" için koltuk değneği eklemek zorunda kaldık.
Seçim yapmanız mı gerekiyor?
RAML çözüm ekosistemini tamamlamak için çalıştıktan sonra, RAML'ı Swagger 2'ye dönüştürmemiz ve tüm otomasyon, doğrulama, test ve sonraki optimizasyonları burada gerçekleştirmemiz gerektiği sonucuna vardık. Bu, hem RAML'nin esnekliğinden hem de Swagger'ın topluluk araçları desteğinden yararlanmanın iyi bir yoludur.
Bu sorunu çözmek için sözleşme dönüşümü sağlaması gereken iki Açık Kaynak aracı vardır:
- şu anda desteklenmeyen bir yardımcı programdır. Üzerinde çalışırken, çok sayıda dosyaya "yayılmış" karmaşık RAML'lerle ilgili bir takım sorunları olduğunu keşfettik. Bu program JavaScript ile yazılmıştır ve bir sözdizimi ağacında yinelemeli bir geçiş gerçekleştirir. Dinamik yazma nedeniyle bu kodu anlamak zorlaşıyor, bu nedenle ölmekte olan bir yardımcı program için yamalar yazarak zaman kaybetmemeye karar verdik.
- - aynı şirketten, her şeyi ve her şeyi herhangi bir yönde dönüştürmeye hazır olduğunu iddia eden bir araç. Bugüne kadar RAML 0.8, RAML 1.0 ve Swagger 2.0 için destek duyuruldu. Ancak araştırmamız sırasında fayda hala devam ediyordu. nemli ve kullanılamaz. Geliştiriciler bir tür yaratır gelecekte hızla yeni standartlar eklemelerine olanak tanır. Ama şu ana kadar işe yaramıyor.
Ve karşılaştığımız tüm zorluklar bu değil. İşlem hattımızdaki adımlardan biri, depodaki RAML'nin spesifikasyona göre doğru olduğunu doğrulamaktır. Çeşitli yardımcı programları denedik. Şaşırtıcı bir şekilde hepsi farklı yerlerde ve tamamen farklı kötü sözlerle şerhlerimize küfrettiler. Ve her zaman konuya değil :).
Sonunda, bir takım sorunları da olan (bazen birdenbire çöküyor, düzenli ifadelerle çalışırken sorunlar yaşıyor) artık güncelliğini kaybetmiş bir projeye karar verdik. Bu nedenle doğrulama ve dönüştürme sorunlarını ücretsiz araçlara dayalı olarak çözmenin bir yolunu bulamadık ve ticari bir yardımcı program kullanmaya karar verdik. Gelecekte Açık Kaynak araçları olgunlaştıkça bu sorunun çözülmesi daha kolay hale gelebilir. Bu arada “bitirme” için gereken işçilik ve zaman maliyetleri bize ticari bir hizmetin maliyetinden daha önemli göründü.
Sonuç
Tüm bunlardan sonra deneyimlerimizi paylaşmak istedik ve sözleşmeleri tanımlamak için bir araç seçmeden önce, ondan ne istediğinizi ve hangi bütçeye yatırım yapmak istediğinizi açıkça tanımlamanız gerektiğini belirtmek istedik. Açık Kaynak'ı unutursak, kontrol etmenize, dönüştürmenize ve doğrulamanıza yardımcı olacak çok sayıda hizmet ve ürün zaten mevcut. Ancak pahalıdırlar ve bazen çok pahalıdırlar. Büyük bir şirket için bu tür maliyetler tolere edilebilir, ancak yeni kurulan bir şirket için bunlar büyük bir yük haline gelebilir.
Daha sonra kullanacağınız araç setini belirleyin. Örneğin, yalnızca bir sözleşmeyi görüntülemeniz gerekiyorsa, güzel bir API'ye sahip olan Swagger 2'yi kullanmak daha kolay olacaktır çünkü RAML'de hizmeti kendiniz oluşturmanız ve sürdürmeniz gerekecektir.
Görevleriniz arttıkça, araçlara olan ihtiyaç da artacaktır ve bunlar farklı platformlar için farklıdır ve gelecekte maliyetlerinizi en aza indirecek bir seçim yapmak için mevcut sürümlere hemen alışmak daha iyidir.
Ancak bugün var olan tüm ekosistemlerin kusurlu olduğunu kabul etmeye değer. Bu nedenle şirkette "düşünceleri daha esnek bir şekilde ifade etmenize olanak sağladığı için" RAML'de çalışmayı seven veya tam tersine "daha net olduğu için" Swagger'ı tercih eden hayranlar varsa, onları çalışmaya bırakmak en iyisi Buna alışkınlar ve bunu istiyorlar çünkü herhangi bir formatın araçları bir dosyada değişiklik yapmayı gerektiriyor.
Deneyimlerimize gelince, önümüzdeki yazılarda RAML-Swagger mimarimizi temel alarak hangi statik ve dinamik kontrolleri yaptığımızdan, sözleşmelerden hangi belgeleri oluşturduğumuzdan ve bunların nasıl çalıştığından bahsedeceğiz.
Ankete sadece kayıtlı kullanıcılar katılabilir. Lütfen.
Mikro hizmet sözleşmelerine açıklama eklemek için hangi dili kullanıyorsunuz?
-
RAML0.8
-
RAML1.0
-
savurganlık 2
-
OAS3 (diğer adıyla)
-
Blueprint
-
Diğer
-
Kullanmıyor
100 kullanıcı oy kullandı. 24 kullanıcı çekimser kaldı.
Kaynak: habr.com