Jak skonfigurować Maven w projekcie Java bez IDE krok po kroku

Wprowadzenie do konfiguracji Mavena w istniejącym projekcie Java

Wyobraź sobie taką sytuację: masz przed sobą projekt Java, który hulał sobie spokojnie od lat, ale bez żadnego systemu budowania. Może to prosta aplikacja konsolowa, może zestaw bibliotek, które piszesz na własny użytek. Teraz jednak chcesz dodać zależności, zarządzać wersjami, zautomatyzować kompilację i testy. Krótko mówiąc – chcesz, żeby Twój projekt stał się prawdziwym, nowoczesnym projektem Javowym.

W tym momencie na scenę wchodzi Maven. W głowie pojawia się pytanie: jak skonfigurować Maven w istniejącym projekcie Java bez IDE krok po kroku? Nie musisz od razu rzucać się na głęboką wodę z IntelliJ czy Eclipse, które mogłyby to zrobić za Ciebie. Czasem lepiej zrozumieć mechanizm od podszewki i samodzielnie zapanować nad całym procesem budowania.

Taka umiejętność jest bezcenna, gdy pracujesz na serwerze bez graficznego interfejsu albo gdy musisz debugować nietypowe problemy z kompilacją i zależnościami. Ręczna konfiguracja Mavena w istniejącym projekcie Java pozwala też lepiej zrozumieć, jak działa cykl życia builda i dlaczego struktura katalogów ma tak duże znaczenie.

Maven to potężne narzędzie do zarządzania projektami, które ułatwia budowanie, zarządzanie zależnościami i raportowanie. Działa na zasadzie Project Object Model (POM), czyli opisu projektu w pliku pom.xml. To właśnie ten plik stanie się sercem Twojego projektu i głównym punktem konfiguracji całego procesu budowania.

Z tego przewodnika dowiesz się, jak krok po kroku przejść od „luźnego” projektu Java do w pełni zintegrowanego projektu Maven, bez użycia IDE. Skupimy się na praktycznych krokach: od uporządkowania struktury katalogów, przez stworzenie pom.xml, aż po uruchomienie pierwszego builda i rozwiązywanie typowych problemów.

Dlaczego warto używać Mavena w istniejącym projekcie

Zanim przejdziemy do samych kroków konfiguracji, warto przypomnieć, dlaczego Maven w projekcie Java jest tak cenny. Po pierwsze, to potężne narzędzie do zarządzania zależnościami. Zamiast ręcznie pobierać pliki JAR i dodawać je do classpath, możesz dodać kilka linijek do pom.xml, a Maven sam pobierze potrzebne biblioteki oraz ich zależności pośrednie.

Po drugie, Maven wprowadza standaryzowaną strukturę projektu, dzięki czemu każdy kolejny programista może łatwo odnaleźć się w kodzie. Jeśli pracujesz w zespole albo planujesz udostępnić projekt innym, przewidywalny układ katalogów i spójny proces budowania stają się ogromnym ułatwieniem. To też podstawa do automatyzacji w narzędziach CI/CD.

Kolejna zaleta to cykl życia budowania. Maven definiuje standardowe fazy, takie jak kompilacja, testowanie, pakowanie, instalowanie i wdrażanie. Dzięki temu możesz jednym poleceniem wykonać cały proces: od kompilacji kodu, przez uruchomienie testów jednostkowych, aż po zbudowanie JAR-a i instalację w lokalnym repozytorium. To wszystko działa tak samo niezależnie od projektu.

Nie można też zapomnieć o wtyczkach Mavena, które rozszerzają jego funkcjonalność. Dzięki nim możesz generować dokumentację, integrować się z innymi narzędziami, tworzyć wykonywalne JAR-y czy raporty z testów. Cała konfiguracja odbywa się w pom.xml, więc masz pełną kontrolę nad tym, jak wygląda build Twojego istniejącego projektu Java.

Wymagania wstępne przed konfiguracją Mavena

Zanim zaczniesz konfigurację Mavena w istniejącym projekcie Java, upewnij się, że masz przygotowane odpowiednie środowisko. Potrzebujesz dwóch kluczowych elementów: zainstalowanego JDK oraz samego Apache Mavena. Bez nich nie uda się poprawnie zbudować projektu ani uruchomić komend Mavenowych.

Po pierwsze, zainstaluj Java Development Kit (JDK) w odpowiedniej wersji. Upewnij się, że zmienna środowiskowa JAVA_HOME wskazuje na katalog instalacyjny JDK, a katalog bin JDK znajduje się w zmiennej PATH. Możesz to sprawdzić, wpisując w terminalu polecenia:

java -version
javac -version

Jeśli zobaczysz informacje o wersji Javy i kompilatora, oznacza to, że JDK jest poprawnie zainstalowane.

Drugim wymogiem jest Apache Maven. Pobierz go ze strony oficjalnej, rozpakuj archiwum i dodaj katalog bin Mavena do zmiennej PATH. Aby zweryfikować poprawność instalacji, użyj polecenia:

mvn -version

Jeżeli w odpowiedzi pojawi się informacja o wersji Mavena oraz wykorzystywanym JDK, możesz przejść dalej. Gdyby pojawiły się błędy, sprawdź ścieżki i zmienne środowiskowe, zanim przejdziesz do kolejnych kroków.

Dzięki spełnieniu tych wymagań wstępnych masz pewność, że narzędzia nie będą przeszkodą podczas włączania Mavena do istniejącego projektu Java. Teraz możesz skoncentrować się na porządkowaniu struktury katalogów i tworzeniu pom.xml, zamiast walczyć z konfiguracją środowiska systemowego.

Standaryzacja struktury katalogów projektu Java

Pierwszym praktycznym krokiem przy konfiguracji Mavena w istniejącym projekcie Java jest uporządkowanie struktury katalogów. Maven ma swoje preferencje co do układu plików i katalogów, a korzystanie z nich znacząco ułatwia pracę. Bez tego Maven nie będzie wiedział, gdzie szukać kodu źródłowego, zasobów ani testów Twojego projektu.

Standardowa struktura projektu Maven wygląda następująco:

my-project/
├── pom.xml
└── src/
    ├── main/
    │   ├── java/        <- Tutaj umieścisz swój kod źródłowy Javy
    │   └── resources/   <- Tutaj umieścisz pliki konfiguracyjne, zasoby itp.
    └── test/
        ├── java/        <- Tutaj umieścisz kod źródłowy testów Javy
        └── resources/   <- Tutaj umieścisz pliki konfiguracyjne dla testów

Jeśli w Twoim projekcie pliki .java znajdują się np. bezpośrednio w katalogu my-project/src/, przenieś je do my-project/src/main/java/. W projektach dziedziczonych sprzed lat kod bywa rozrzucony po różnych katalogach, dlatego warto poświęcić chwilę na uporządkowanie wszystkiego zgodnie ze standardem Mavena.

Pliki konfiguracyjne, takie jak *.properties, *.yml czy inne zasoby używane przez aplikację, umieść w katalogu my-project/src/main/resources/. Dzięki temu Maven automatycznie dołączy je do artefaktu budowanego podczas fazy package. Analogicznie testy jednostkowe i ich zasoby przenieś do src/test/java/ oraz src/test/resources/.

Jeżeli brakuje któregoś z wymienionych katalogów, po prostu go utwórz. Maven nie tworzy ich automatycznie w istniejących projektach, więc to Ty musisz zadbać o odpowiedni układ. Gdy struktura katalogów jest już zgodna ze standardem, możesz bez przeszkód przejść do tworzenia pliku pom.xml, który zepnie cały projekt w spójną całość.

Tworzenie pliku pom.xml – serca projektu Maven

Kolejnym krokiem w konfiguracji Mavena w istniejącym projekcie Java jest stworzenie pliku pom.xml w głównym katalogu projektu (my-project/). To właśnie ten plik opisuje Twój projekt dla Mavena i określa, jak ma wyglądać proces budowania. W nim znajdzie się identyfikacja artefaktu, wersje, zależności i konfiguracja wtyczek.

Zacznij od minimalnej, podstawowej wersji pom.xml:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.radoszewski.mojprojekt</groupId>
    <artifactId>moj-projekt</artifactId>
    <version>1.0-SNAPSHOT</version>
    <packaging>jar</packaging>

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
    </properties>

    <dependencies>

    </dependencies>

    <build>
        <plugins>

        </plugins>
    </build>

</project>

Element <project> stanowi główny kontener całej konfiguracji, a atrybuty xmlns oraz xsi:schemaLocation są standardowe. W groupId podajesz unikalny identyfikator organizacji lub aplikacji, zazwyczaj w formie odwróconej nazwy domeny. Z kolei artifactId to nazwa Twojego modułu lub biblioteki, która pojawi się w nazwie generowanego pliku JAR lub WAR.

Tag <version> określa wersję projektu. Dopisek SNAPSHOT sugeruje, że jest to wersja rozwojowa, zmieniająca się dynamicznie. Gdy zdecydujesz się na wydanie stabilne, możesz zmienić ją np. na 1.0.0. W <packaging> definiujesz typ artefaktu – dla większości bibliotek i aplikacji konsolowych będzie to jar, natomiast dla aplikacji webowych war.

Sekcja <properties> pozwala zdefiniować istotne parametry, takie jak kodowanie źródeł (UTF-8) oraz wersje Javy do kompilacji (maven.compiler.source i maven.compiler.target). Tym ustawieniom powinien odpowiadać zainstalowany JDK. Puste na razie sekcje <dependencies> i <build> uzupełnisz w kolejnych krokach zależnościami oraz konfiguracją wtyczek Mavena.

Dodawanie zależności w pom.xml

Gdy pom.xml jest już utworzony, następnym krokiem konfiguracji Mavena w istniejącym projekcie Java jest dodanie zależności. To właśnie dzięki tej sekcji unikniesz ręcznego kopiowania plików JAR i ręcznego zarządzania classpath. Maven automatycznie pobierze wszystkie wymagane biblioteki wraz z zależnościami pośrednimi.

Załóżmy, że Twój projekt używa biblioteki do testowania, takiej jak JUnit 5. Aby ją dodać, wyszukaj ją na Maven Central, np. wpisując „JUnit Jupiter API”, a następnie skopiuj fragment XML odpowiedni dla wybranej wersji. Przykładowa konfiguracja w sekcji <dependencies> wygląda tak:

    <dependencies>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-api</artifactId>
            <version>5.10.0</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupId>org.junit.jupiter</groupId>
            <artifactId>junit-jupiter-engine</artifactId>
            <version>5.10.0</version>
            <scope>test</scope>
        </dependency>
        <!--
        <dependency>
            <groupId>org.apache.commons</groupId>
            <artifactId>commons-lang3</artifactId>
            <version>3.12.0</version>
        </dependency>
        -->
    </dependencies>

Atrybut <scope>test</scope> oznacza, że dana zależność jest potrzebna wyłącznie podczas kompilacji i uruchamiania testów, natomiast nie będzie dołączana do finalnego artefaktu aplikacji. To przydatne, gdy chcesz utrzymać rozmiar JAR-a w ryzach i nie dołączać bibliotek testowych do środowiska produkcyjnego.

Jeśli dana biblioteka jest potrzebna w kodzie produkcyjnym, po prostu pomiń tag <scope> lub pozostaw go na domyślnym poziomie compile. W ten sposób możesz dodawać kolejne zależności, takie jak np. Apache Commons Lang, biblioteki logujące czy frameworki webowe. Pamiętaj tylko, aby zawsze sprawdzać poprawność groupId, artifactId i version, ponieważ literówka w tych polach jest częstą przyczyną błędów podczas pobierania artefaktów.

Konfiguracja procesu kompilacji i budowania

Kiedy sekcja zależności jest już gotowa, czas skonfigurować proces kompilacji i budowania w pom.xml. W tym celu używa się sekcji <build> oraz różnych wtyczek Mavena. Jedną z najważniejszych jest maven-compiler-plugin, który odpowiada za kompilowanie kodu źródłowego przy użyciu odpowiedniej wersji Javy.

Przykładowa konfiguracja sekcji <build> wygląda tak:

    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.8.1</version>
                <configuration>
                    <source>${maven.compiler.source}</source>
                    <target>${maven.compiler.target}</target>
                </configuration>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-jar-plugin</artifactId>
                <version>3.2.0</version>
                <configuration>
                    <archive>
                        <manifest>
                            <addClasspath>true</addClasspath>
                            <mainClass>com.radoszewski.mojprojekt.Mojaplikacja</mainClass>
                        </manifest>
                    </archive>
                </configuration>
            </plugin>
        </plugins>
    </build>

Wtyczka maven-compiler-plugin korzysta z parametrów zdefiniowanych wcześniej w <properties>, czyli maven.compiler.source i maven.compiler.target. Pozwala to w jednym miejscu kontrolować wersję Javy używaną do kompilacji. Jeżeli zmienisz ją z czasem, wystarczy edycja tych właściwości zamiast modyfikacji wielu fragmentów pom.xml.

Druga wtyczka, maven-jar-plugin, jest szczególnie przydatna, jeśli chcesz, aby projekt był wykonywalnym JAR-em. Kluczowy jest tu element <mainClass>, w którym podajesz pełną nazwę klasy zawierającej metodę main(). Dzięki tej konfiguracji Maven doda do manifestu JAR-a informację o klasie startowej, co umożliwi uruchamianie aplikacji poleceniem java -jar.

Tak skonfigurowany plik pom.xml sprawia, że Maven wie nie tylko, co ma kompilować, ale również jak ma spakować Twoją aplikację i jakie właściwości runtime są dla niej istotne. W kolejnych krokach skupimy się na uruchomieniu pierwszego builda oraz na tym, jak wystartować tak przygotowany plik JAR.

Pierwsze budowanie projektu Maven bez użycia IDE

Gdy masz już uporządkowaną strukturę katalogów i skonfigurowany pom.xml, możesz przejść do pierwszego budowania projektu Maven. Wszystko odbywa się z poziomu terminala, co idealnie pasuje do pracy bez IDE i pozwala lepiej zrozumieć poszczególne fazy cyklu życia Mavena.

Najpierw przejdź do katalogu głównego projektu, w którym znajduje się Twój pom.xml. Aby usunąć ewentualne artefakty z poprzednich kompilacji (np. katalog target/), uruchom:

mvn clean

Następnie, aby skompilować kod, uruchomić testy oraz spakować projekt do pliku JAR lub WAR, użyj fazy install:

mvn install

Podczas tej komendy Maven wykona szereg operacji: pobierze wszystkie brakujące zależności, skompiluje kod źródłowy, uruchomi testy jednostkowe, spakuje wszystko do artefaktu oraz zainstaluje wynikowy plik w lokalnym repozytorium (~/.m2/repository). Dzięki temu również inne Twoje projekty mogą w prosty sposób korzystać z tego samego artefaktu, odwołując się do niego w swoich pom.xml.

Jeśli proces zakończy się powodzeniem, zobaczysz komunikat BUILD SUCCESS. W katalogu target/ znajdziesz wygenerowany plik JAR, np. moj-projekt-1.0-SNAPSHOT.jar. W tym momencie Twój dawny projekt Java, który wcześniej nie miał żadnego systemu buildowania, stał się pełnoprawnym projektem Mavenowym i można nim zarządzać w sposób standaryzowany i powtarzalny.

Uruchamianie aplikacji jako wykonywalnego JAR-a

Jeśli skonfigurowałeś maven-jar-plugin i podałeś poprawną klasę główną, Twój projekt Maven można uruchamiać jako wykonywalny JAR. To szczególnie wygodne w przypadku prostych aplikacji konsolowych, skryptów czy narzędzi uruchamianych z linii poleceń bez udziału IDE.

Po zbudowaniu projektu i wygenerowaniu pliku w katalogu target/, możesz uruchomić aplikację poleceniem:

java -jar target/moj-projekt-1.0-SNAPSHOT.jar

Manifest JAR-a, wygenerowany na podstawie konfiguracji w maven-jar-plugin, zawiera wpis Main-Class, który wskazuje na Twoją klasę z metodą main(). Dzięki temu Java wie, od czego zacząć wykonanie programu, a Ty nie musisz ręcznie wskazywać klasy startowej w linii poleceń.

Jeśli Twoja aplikacja korzysta z wielu zewnętrznych bibliotek, których maven-jar-plugin nie pakuje automatycznie do jednego pliku, możesz rozważyć użycie w przyszłości takich wtyczek jak maven-assembly-plugin albo maven-shade-plugin. Pozwalają one tworzyć tzw. „uber-JARy”, zawierające kod aplikacji oraz wszystkie jej zależności. To jednak bardziej zaawansowany temat, do którego możesz wrócić, gdy dobrze opanujesz podstawową konfigurację Mavena w istniejących projektach.

Typowe problemy i ich rozwiązywanie

Podczas konfiguracji Mavena w istniejącym projekcie Java możesz natrafić na kilka typowych problemów. Warto wiedzieć, jak je szybko diagnozować i rozwiązywać, aby nie utknąć na drobnostkach. Większość z nich wynika ze złej konfiguracji środowiska, nieprawidłowych ścieżek lub literówek w pom.xml.

Jednym z częstszych błędów jest komunikat „Compilation failure”. W takiej sytuacji sprawdź, czy wszystkie pliki źródłowe znajdują się w katalogu src/main/java oraz czy wymagane biblioteki zostały poprawnie zadeklarowane w sekcji <dependencies>. Zwróć też uwagę na dopasowanie wersji Javy – parametry maven.compiler.source i maven.compiler.target muszą odpowiadać wersji JDK, którą faktycznie wykorzystujesz.

Inny popularny problem to komunikat „Could not find artifact...”, oznaczający, że Maven nie może pobrać określonej zależności. Najpierw dokładnie sprawdź groupId, artifactId i version w pom.xml. Upewnij się, że masz dostęp do Internetu, ponieważ Maven musi połączyć się z zewnętrznymi repozytoriami. Czasem pomaga też uruchomienie:

mvn clean install -U

Opcja -U wymusza aktualizację snapshotów i zależności.

Możesz też napotkać problemy z konfiguracją zmiennych PATH, JAVA_HOME czy M2_HOME. Jeśli mvn -version nie działa, upewnij się, że katalogi bin Javy i Mavena są poprawnie dodane do PATH. W środowiskach korporacyjnych dodatkowym kłopotem bywa brak pliku settings.xml lub specjalna konfiguracja serwerów proxy i repozytoriów. W takich przypadkach najlepiej skonsultować się z administratorem lub wewnętrzną dokumentacją, aby poprawnie skonfigurować ~/.m2/settings.xml.

Co dalej po podstawowej konfiguracji Mavena

Kiedy opanujesz już podstawowe kroki konfiguracji Mavena w istniejącym projekcie Java, możesz zacząć korzystać z bardziej zaawansowanych możliwości. Jedną z nich są profile, które pozwalają zdefiniować różne konfiguracje budowania dla różnych środowisk, np. deweloperskiego, testowego czy produkcyjnego. Dzięki nim możesz zmieniać parametry builda, zależności czy wtyczki w zależności od scenariusza.

Warto też zgłębić temat faz cyklu życia i celów (goals) Mavena. Poza dobrze znanym install istnieją takie fazy jak validate, compile, test, package, verify czy deploy. Każdą z nich możesz uruchamiać osobno, w zależności od potrzeb. To daje dużą elastyczność i ułatwia integrację z systemami CI/CD, które mogą wykonywać tylko wybrane etapy budowania.

Kolejny obszar to raportowanie i integracja z innymi narzędziami. Maven potrafi generować m.in. raporty z pokrycia testów, dokumentację Javadoc czy raporty jakości kodu. W większych projektach szczególnie przydatne stają się multi-modułowe projekty, gdzie jeden główny pom.xml zarządza wieloma modułami składowymi systemu.

Zrozumienie, jak działa Maven „pod maską” – bez wspomagania IDE – daje ogromną elastyczność i pewność siebie. Gdy nauczysz się ręcznie zarządzać pom.xml, żaden problem z buildem nie będzie dla Ciebie straszny. To trochę jak nauka jazdy samochodem z manualną skrzynią biegów – gdy umiesz to, poradzisz sobie z każdym automatem. Nie bój się eksperymentować, modyfikować pliki i wywoływać różne fazy Mavena, bo właśnie w ten sposób najskuteczniej poznasz to narzędzie i wyniesiesz swój projekt Java na wyższy poziom.