Begrijpen van Afhankelijkheden…Visueel!

Steek uw hand op, hoeveel van ons begrijpen echt hoe uw build automation tool zijn afhankelijkheidsboom bouwt? Nu, haal je hand omlaag als je begrijpt omdat je aan build automatiseringstools werkt. Dacht het al!

Een frustrerende verantwoordelijkheid van software engineers is het begrijpen van de afhankelijkheden van je project: welke transitieve afhankelijkheden zijn meegenomen en door wie; waarom v1.3.1 wordt gebruikt terwijl v1.2.10 werd aangekondigd; wat er gebeurde toen de transitieve afhankelijkheden veranderden; hoe zijn er meerdere versies van hetzelfde artefact ontstaan?

Elke software engineer heeft een afhankelijkheidsboom naar een tekstbestand gepijp, gezocht naar specifieke artefacten, en vervolgens hun weg teruggewerkt om de oorsprong ervan te identificeren. Voor alles dat meer is dan triviale projecten, is het creëren van een mentale kaart van de afhankelijkheden uiterst moeilijk, zo niet onmogelijk.

I faced this problem when starting a new job with a mature code base, presenting a challenge to assemble the puzzle pieces.  I’ve previously worked with graph databases and thought a graphical view of the dependency artifacts could be created using Neo4J, which resulted in DependencyLoader.

Opmerking: dit is geen tutorial over grafische databases, noch vereist dit tutorial een achtergrond in grafische databases. Als je geïnteresseerd bent, heeft Neo4J tutorials en witte papieren om je aan de slag te helpen.

Omgevingsinstelling

Java installeren

Java 11 of later is vereist. Indien nog niet beschikbaar, installeer je favoriete OpenJDK variant.

Installeer Neo4J

De tutorial vereist een Neo4J-database waarin de afhankelijkheidsinformatie wordt geladen, bij voorkeur niet gedeeld, aangezien de loader de database blijft leegmaken voor elke run. Je bent gewaarschuwd!

Neo4J biedt persoonlijke sandboxes, ideaal voor korte termijn projecten zoals deze tutorial.

Als alternatief, installeer Neo4J lokaal op je desktop of laptop. Homebrew vereenvoudigt MacOS-installaties: 

brew install neo4j && brew services start neo4j

Voordat je verdergaat, bevestig toegang tot je Neo4J-database met de browser, met behulp van de link en referenties voor de Neo4J sandbox of lokaal op http://localhost:7474. De standaardreferenties voor een lokale installatie zijn neo4j/neo4j; bij een succesvolle login wordt je gedwongen het wachtwoord te wijzigen.

Kloon Repositories

Het neo4j-gradle-dependencies repository bevat de middelen voor het laden van afhankelijkheden in Neo4J. Deze tutorial zal een afhankelijkheidsgrafiek genereren voor spring-boot. U moet deze twee repositories klonen.

Scott.Sosna@mymachine src% git clone [email protected]:scsosna99/neo4j-gradle-dependencies.git
Scott.Sosna@mymachine src% git clone [email protected]:spring-projects/spring-boot.git

Opmerking: lokaal Gradle is niet vereist, aangezien beide repositories de Gradle Wrapper gebruiken, die alle noodzakelijke componenten voor het eerst downloadt wanneer de wrapper wordt gebruikt.

Afhankelijkheden genereren

DependencyLoader neemt de door Gradle gegenereerde afhankelijkheidsboom als invoer. Hoewel meerdere configuraties tegelijkertijd kunnen worden geladen – bijvoorbeeld compileClasspath, runtimeClasspath, testCompileClasspath, testRuntimeClasspath – is het beginnen met één configuratie eenvoudiger te navigeren, vooral voor een tutorial.

Om afhankelijkheden voor alle configuraties te genereren: 

• gradle dependencies
• ./gradlew dependencies

Om afhankelijkheden voor één configuratie te genereren

• gradle dependencies --configuration <configuration>
• ./gradlew dependencies --configuration <configuration>

Spring Boot Afhankelijkheden genereren

Dit tutorial maakt een afhankelijkheidsgrafiek in Neo4J aan met behulp van de compileClasspath afhankelijkheden van Spring Boot. Voer uit de directory waar de repositories werden gekloond, de volgende commando’s uit:

Scott.Sosna@mymachine src% cd spring-boot/spring-boot-project/spring-boot
Scott.Sosna@mymachine spring-boot% ./gradlew dependencies --configuration compileClasspath > dependencies.out

Het bestand dependencies.out bevat de compile-time classpath afhankelijkheden voor Spring Boot.

Afhankelijkheden laden

Controleer eerst de verbindings-URL en authenticatiereferenties in DependencyLoader.java en pas deze indien nodig aan.

Voer de volgende commando’s uit om de Spring Boot afhankelijkheden in Neo4j te laden:

Scott.Sosna@mymachine spring-boot% cd ../../../neo4j-gradle-dependencies
Scott.Sosna@mymachine neo4j-gradle-dependencies% ./gradlew clean run  --args="../spring-boot/spring-boot-project/spring-boot/dependencies.out"

Bij succesvolle uitvoering zijn de uitvoerregels van gradle:

Scott.Sosna@PVHY32M6KG neo4j-gradle-dependencies % ./gradlew clean run  --args="../spring-boot/spring-boot-project/spring-boot/dependencies.out"

> Task :compileJava
Note: /Users/Scott.Sosna/data/src/github/neo4j-gradle-dependencies/src/main/java/dev/scottsosna/neo4j/gradle/relationship/DependsOn.java uses unchecked or unsafe operations.
Note: Recompile with -Xlint:unchecked for details.

> Task :run
SLF4J: Failed to load class "org.slf4j.impl.StaticLoggerBinder".
SLF4J: Defaulting to no-operation (NOP) logger implementation
SLF4J: See http://www.slf4j.org/codes.html#StaticLoggerBinder for further details.
Jun 02, 2023 6:19:22 AM org.neo4j.driver.internal.logging.JULogger info
INFO: Direct driver instance 1606286799 created for server address localhost:7687
dependencies.out completed.
Jun 02, 2023 6:19:23 AM org.neo4j.driver.internal.logging.JULogger info
INFO: Closing driver instance 1606286799
Jun 02, 2023 6:19:23 AM org.neo4j.driver.internal.logging.JULogger info
INFO: Closing connection pool towards localhost:7687

Deprecated Gradle features were used in this build, making it incompatible with Gradle 8.0.

You can use '--warning-mode all' to show the individual deprecation warnings and determine if they come from your own scripts or plugins.

See https://docs.gradle.org/7.5.1/userguide/command_line_interface.html#sec:command_line_warnings

BUILD SUCCESSFUL in 3s

Afhankelijkheden weergeven

Er zijn meerdere tools beschikbaar voor het weergeven van Neo4J grafieken, maar de ingebouwde browsertool is voldoende voor dit tutorial.

Volledige boom weergeven

De query MATCH(a) RETURN a is het relationeel-equivalent van SELECT * FROM <tabel>

Details van een artefact weergeven

Elk gevonden artefact creëert een knooppunt waarvan de eigenschappen het artefact (groupId/artifactId) en zijn type identificeren, getoond in het rechterzijpaneel.

Bekijk Details van een Afhankelijkheid

Elke afhankelijkheid wordt gemaakt als een relatie waarvan de eigenschappen de specifieke kenmerken van de afhankelijkheid aangeven: configuratie, gespecificeerde/versie, en configuratie. De hieronder geselecteerde afhankelijkheid toont spring-security:spring-web die afhankelijk is van io.micrometer:micrometer-observation, maar de gespecificeerde versie 1.10.7 van spring-web werd opgelost als versie 1.11.0.

Doorkruisen van Afhankelijkheden

Neo4J stelt u in staat om de grafiek knooppunt-voor-knooppunt te verkennen, waardoor u handmatig het grafiek knooppunt kunt uitbreiden, waardoor een manier wordt geboden om specifieke gebieden van de afhankelijkheidsboom te verkennen.

Stel dat u de afhankelijkheden wilt begrijpen voor het artefact io.projectreactor.netty:reactor-netty-http. Eerst zullen we Neo4J vragen naar dat specifieke knooppunt.

MATCH(a:Artifact {groupId: 'io.projectreactor.netty', artifactId: 'reactor-netty-http'}) RETURN a

Dubbelklikken op het knooppunt toont zijn buren — de artefact(s) waarvan het afhankelijk is en de artefact(s) waarop het zelf afhankelijk is.

De uitgebreide grafiek toont één artefact dat ervan afhankelijk is — de root van het project met een artefacttype PROJECT en zes andere afhankelijkheden waarop het zelf afhankelijk is.

Volgende, dubbelklik op io.netty:netty-codehttps://github.com/netty/netty/tree/4.1/codec-httpc-http om de volgende niveau van afhankelijkheden te tonen. Merk op dat naast de relaties (afhankelijkheden) van het geselecteerde knooppunt, aanvullende relaties voor knooppunten die al op de grafiek staan, kunnen worden getoond.

Identificeer Versie Mismatch

Gradle’s afhankelijkheidsoutput geeft aan waar de opgegeven versie niet de versie was die door Gradle werd opgelost. De eigenschappen op de afhankelijkheid (relatie) kunnen worden gebruikt in een Neo4J-query, waardoor de getoonde relaties en de aangesloten artefacten (knooppunten) worden beperkt.

MATCH (a:Artifact)-[d:DEPENDS_ON]->(b:Artifact) WHERE d.specifiedVersion<>d.resolvedVersion RETURN a,b,d

Neo4J kan resultaten in een tabelvorm retourneren voor gemakkelijker beoordeling, indien nodig.

MATCH (a:Artifact)-[d:DEPENDS_ON]->(b:Artifact) WHERE d.specifiedVersion<>d.resolvedVersion RETURNa.name AS source, b.name AS dependency, d.specifiedVersion AS specified, d.resolvedVersion AS resolved

Aanvullende Informatie

mappings.out

Het mappings.out bestand stelt u in staat om het artefacttype toegewezen aan een knooppunt te customizen op basis van artefact groupId, meestal om artefacten specifiek te identificeren die door uw organisatie zijn gemaakt.

Invoer Directory

De command line argument voor DependencyLoader kan een directory zijn die meerdere Gradle afhankelijkheidsbomen bevat die in dezelfde Neo4J-database worden geladen. Dit helpt bij het begrijpen van de afhankelijkheden van gerelateerde projecten met aparte build.gradle bestanden.

Beperkt en Weggelaten

Gradle identificeert bepaalde afhankelijkheden als Beperkt en Weggelaten. Momenteel worden die niet geladen, maar zouden gemakkelijk kunnen worden opgenomen, waarschijnlijk door het aanmaken van extra eigenschappen voor de relaties.