Függőségi verzióütközések elhárítása
Ez a cikk a függőségek verzióütközéseit és azok hibaelhárítását ismerteti.
A Java-hoz készült Azure-ügyfélkódtárak a népszerű külső kódtáraktól függenek, például az alábbiaktól:
Számos Java-alkalmazás és keretrendszer közvetlenül vagy tranzitív módon használja ezeket a kódtárakat, ami verzióütközésekhez vezet. A függőségkezelők, például a Maven és a Gradle minden függőséget feloldanak, hogy az osztályúton csak az egyes függőségek egyetlen verziója legyen. Azonban nem garantált, hogy a feloldott függőségi verzió kompatibilis az alkalmazás ezen függőségének összes fogyasztójával. További információ : Bevezetés a függőségi mechanizmusba a Maven dokumentációjában és a függőségfeloldás ismertetése a Gradle dokumentációjában.
A közvetlen függőségek API-kompatibilitása fordítási hibákat eredményez. A gyémántfüggőség inkompatibilitása általában olyan futtatókörnyezeti hibákat eredményez, mint a NoClassDefFoundError, a NoSuchMethodError vagy más LinkageError. Nem minden kódtár szigorúan követi a szemantikai verziókövetést, és a kompatibilitástörő változások néha ugyanazon a főverzión belül történnek.
Verzióeltérési problémák diagnosztizálása
A következő szakaszok a verzióeltérési problémák diagnosztizálására vonatkozó módszereket ismertetik.
Az Azure SDK for Java buildelési eszköz használata
Az Azure SDK for Java buildelési eszköze, amely az Azure SDK és az Apache Maven használatának első lépéseiben mutatkozik be, segít azonosítani a gyakran előforduló problémákat. Javasoljuk, hogy vegye fel ezt a buildelési eszközt a projektbe, és futtassa úgy, hogy hozzáadja a azure:run Maven-célt a szokásos buildelési folyamathoz. A megfelelő konfigurációval proaktívabban azonosíthatja és megoldhatja a függőségi ütközéseket, mielőtt futásidőben problémákba ütköznének.
Függőségi fa megtekintése
Futtassa mvn dependency:tree vagy gradle dependencies --scan jelenítse meg az alkalmazás teljes függőségi fáját verziószámokkal. mvn dependency:tree -Dverbose több információt ad, de félrevezető lehet. További információ: Apache Maven Dependency Tree a Maven dokumentációjában. Minden olyan kódtár esetében, amelyről gyanítható, hogy verzióütközés van, jegyezze fel annak verziószámát, és állapítsa meg, hogy mely összetevők függnek attól.
A fejlesztési és éles környezetekben a függőségfeloldás eltérően működhet. Az Apache Spark, az Apache Flink, a Databricks és az IDE beépülő moduloknak további konfigurációra van szükségük az egyéni függőségekhez. Saját Azure-ügyfélkódtárakat vagy közös összetevőket is használhatnak. További információért tekintse át az alábbi cikkeket:
- Az alkalmazás függőségeinek összekapcsolása az Apache Sparkhoz
- Az Apache Flink projektkonfigurációja
- Maven-kódtár helyes frissítése a Databricks for Databricksben
Az ilyen környezetekben előforduló ütközésfeloldásról a cikk későbbi, zsíros JAR-jának létrehozása című szakaszában olvashat bővebben.
Az Azure Functions konfigurálása
Az Azure Functions belső függőségi verziója (csak Java 8-at futtat) elsőbbséget élvez a felhasználó által biztosított verzióval szemben. Ez a függőség verzióütközéseket okoz, különösen a Jackson, a Netty és a Reactor esetén.
A probléma megoldásához állítsa a környezeti változót a FUNCTIONS_WORKER_JAVA_LOAD_APP_LIBS következőre true : vagy 1. Mindenképpen frissítse az Azure-függvényeszközöket (v2 vagy v3) a legújabb verzióra.
Feljegyzés
Ez a konfiguráció csak a Java 8-at futtató Azure Functionsre vonatkozik, a Java 11-et futtató függvényekhez nincs szükség speciális konfigurációra.
Az Apache Spark konfigurálása
A Java-hoz készült Azure SDK támogatja a Jackson több verzióját, de a buildelési eszköztől és a függőségek megoldásának sorrendjétől függően időnként problémák léphetnek fel. Erre jó példa az Apache Spark 3.0.0-s és újabb verziója, amely a Jackson 2.10-es verziójától függ. Bár kompatibilis a Java Azure SDK-val, a fejlesztők gyakran felfedezik, hogy a Jackson újabb verzióját használják, ami inkompatibilitást eredményez. A probléma megoldásához rögzítenie kell a Jackson egy adott verzióját (amely kompatibilis a Sparkkal). További információt a jelen cikk Több Jackson-verzió támogatása című szakaszában talál.
Ha a Spark korábbi verzióit használja, vagy ha egy másik használt kódtárhoz a Jackson egy korábbi verziója szükséges, amelyet az Azure SDK for Java nem támogat, olvassa el ezt a cikket a lehetséges megoldási lépésekért.
A Jackson-futtatókörnyezet verziójának észlelése
Az Azure Core 1.21.0-ban hozzáadtuk a futtatókörnyezet észlelését és a Jackson-futtatókörnyezet verziójának jobb diagnosztikát.
Ha a Jackson API-val kapcsolatos (vagy annak alosztályait) látja LinkageError , ellenőrizze a kivétel üzenetét a futtatókörnyezet verzióadataihoz. Például: com.azure.core.implementation.jackson.JacksonVersionMismatchError: com/fasterxml/jackson/databind/cfg/MapperBuilder Package versions: jackson-annotations=2.9.0, jackson-core=2.9.0, jackson-databind=2.9.0, jackson-dataformat-xml=2.9.0, jackson-datatype-jsr310=2.9.0, azure-core=1.19.0-beta.2
Keresse meg a figyelmeztetési és hibanaplókat a következőből JacksonVersion: . További információ: Naplózás konfigurálása a Java Azure SDK-ban. Például: [main] ERROR com.azure.core.implementation.jackson.JacksonVersion - Version '2.9.0' of package 'jackson-core' is not supported (too old), please upgrade.
Feljegyzés
Ellenőrizze, hogy az összes Jackson-csomag ugyanazzal a verzióval rendelkezik-e.
Az Azure SDK és a támogatott Jackson-verziók által használt csomagok listáját a Több Jackson-verzió támogatása című szakaszban találja.
Verzióeltérési problémák elhárítása
A következő szakaszok ismertetik, hogyan hárítható el a verzióeltérésekkel kapcsolatos problémák.
Az Azure SDK BOM használata
Használja a legújabb stabil Azure SDK BOM-t , és ne adja meg az Azure SDK-t és a függőségi verziókat a POM-fájlban. Szükség esetén használja az Azure Spring Boot BOM-t.
Az Azure SDK BOM-ban felsorolt függőségeket szigorúan teszteljük a függőségi ütközések elkerülése érdekében.
A szükségtelen függőségek elkerülése
Ha lehet, távolítsa el a függőségeket. Előfordulhat, hogy egy alkalmazás több kódtártól is függ, amelyek lényegében ugyanazt a funkciót biztosítják. Az ilyen szükségtelen függőségek biztonsági réseknek, verzióütközéseknek, valamint támogatási és karbantartási költségeknek teszik ki az alkalmazásokat.
Függőségi verziók frissítése
Ha a legújabb Azure SDK BOM-ra való váltás nem segít, azonosítsa az ütközéseket okozó kódtárakat és az azokat használó összetevőket. (További információ: Függőségfaszakasz megtekintése a cikk korábbi részében.) Próbáljon meg újabb verzióra frissíteni, amely védelmet nyújt a biztonsági rések ellen, és gyakran új funkciókat, teljesítménybeli fejlesztéseket és hibajavításokat hoz létre.
Kerülje az Azure SDK-verzió leminősítését, mert az ismert biztonsági rések és problémák miatt teheti elérhetővé az alkalmazást.
Tárak árnyékolása
Néha a kódtárak nem működnek együtt, és az árnyékolás az utolsó megoldás.
Feljegyzés
Az árnyékolásnak jelentős hátrányai vannak: növeli a csomagméretet és az osztályok számát az osztályúton, megnehezíti a kódnavigációt és a hibakeresést, nem helyezi át a JNI-kódot, megszakítja a tükrözést, és többek között megsértheti a kódlicenceket. Csak más lehetőségek kimerülése után szabad használni.
Az árnyékolás lehetővé teszi, hogy a buildeléskor függőségeket tartalmazzon a JAR-ban, majd átnevezze a csomagokat, és frissítse az alkalmazás kódját, hogy az árnyékolt helyen használja a kódot. A gyémántfüggőség ütközése már nem jelent problémát, mert egy függőség két különböző példánya létezik. Az ütköző tranzitív függőséget vagy közvetlen alkalmazásfüggőséget tartalmazó kódtárak árnyékolását az alábbi listában leírtak szerint végezheti el:
- Tranzitív függőségi ütközés: A harmadik féltől származó kódtárhoz
Apéldául a Jackson 2.9 szükséges, amelyet az Azure SDK-k nem támogatnak, és nem lehet frissíteniA. Hozzon létre egy új modult, amely tartalmazzaAés árnyékolja (áthelyezi) a Jackson 2.9-et, és opcionálisan a többi függőségetAis. - Alkalmazásfüggőség-ütközés: Az alkalmazás közvetlenül a Jackson 2.9-et használja. Miközben a kód frissítésén dolgozik, árnyékolhatja és áthelyezheti a Jackson 2.9-et egy új modulba, helyette áthelyezett Jackson-osztályokkal.
Feljegyzés
A kövér JAR létrehozása az áthelyezett Jackson-osztályokkal nem oldja meg a verzióütközést ezekben a példákban – csak a Jackson egyetlen árnyékolt verzióját kényszeríti ki.
Zsíros JAR létrehozása
Az olyan környezetek, mint a Databricks vagy az Apache Spark egyéni függőségkezeléssel rendelkeznek, és olyan gyakori kódtárakat biztosítanak, mint a Jackson. A megadott kódtárakkal való ütközés elkerülése érdekében érdemes lehet létrehozni egy kövér JAR-t, amely tartalmazza az összes függőséget. További információt az Apache Maven Shade beépülő modulban talál. A Jackson-osztályok (com.fasterxml.jackson) áthelyezése sok esetben enyhíti a problémát. Előfordulhat, hogy az ilyen környezetek saját Azure SDK-verziót is használnak, így előfordulhat, hogy a névtér áthelyezésére com.azure van szükség a verzióütközések megkerülése érdekében.
A kompatibilis függőségi verziók ismertetése
Az adott függőségekről és azok verzióiról azure-corea Maven Central-adattár azure-core című témakörében olvashat bővebben. Az alábbi táblázat néhány általános szempontot mutat be:
| Dependency | Támogatott verziók |
|---|---|
| Jackson | A 2.10.0 és az újabb alverziók kompatibilisek. További információt a Több Jackson-verzió támogatása című szakaszban talál. |
| SLF4J | 1.7.* |
| netty-tcnative-boringssl-static | 2.0.* |
| netty-common | 4.1.* |
| reaktormag | 3.X.* – A fő- és alverziószámoknak pontosan meg kell egyezniük azokkal, amelyektől a azure-core verzió függ. További információ: Project Reactor-szabályzat az elavulásokról. |
Több Jackson-verzió támogatása
Az Azure SDK for Java számos Jackson-verzió használatát támogatja. A legalacsonyabb támogatott verzió a Jackson 2.10.0. Az Azure SDK for Java-ügyfélkódtárak a futtatókörnyezetben észlelt verziótól függően módosítják a konfigurációjukat és a Jackson-használatukat. Ez a beállítás nagyobb kompatibilitást tesz lehetővé a Spring-keretrendszer, az Apache Spark és más gyakori környezetek régebbi verzióival. Az alkalmazások a Jackson-verziókat (2.10.0-s vagy újabb verzióra) is visszaminősíthetik anélkül, hogy feltörik az Azure SDK for Java-ügyfélkódtárakat.
Feljegyzés
A Jackson régi verzióinak használata ismert biztonsági rések és problémák elé tárhatja az alkalmazásokat. További információkért tekintse meg a Jackson-kódtárak ismert biztonsági réseinek listáját.
A Jackson egy adott verziójának rögzítésekor mindenképpen végezze el az Azure SDK által használt összes modul esetében, amely az alábbi listában látható:
jackson-annotationsjackson-corejackson-databindjackson-dataformat-xmljackson-datatype-jsr310
Migrálás Jacksonból az azure-jsonba
A Java-hoz készült Azure-ügyfélkódtárak az azure-jsonra való migrálás folyamatában vannak, amely nem függ semmilyen külső összetevőtől, és megosztott primitíveket, absztrakciókat és segítőket kínál a JSON-hoz.
Az olyan környezetek, mint az Apache Spark, az Apache Flink és a Databricks, olyan régebbi verziókat azure-core is tartalmazhatnak, amelyek még nem függenek egymástól azure-json. Ennek eredményeképpen, ha az Azure-kódtárak újabb verzióit használja ilyen környezetekben, a következőhöz java.lang.NoClassDefFoundError: com/azure/json/JsonSerializablehasonló hibaüzenetek jelenhetnek meg. Ezt a hibát a explicit függőségének azure-jsonhozzáadásával háríthatja el.
Következő lépések
Most, hogy már ismeri a függőségi verzió ütközéseit, és hogyan háríthatja el őket, tekintse meg a Java-alapú függőségkezelést, és ismerje meg, hogyan akadályozhatja meg őket a legjobban.