Struktura projektu Java: src, package, classpath

1. Folder src — gdzie mieszka twój kod

Gdyby projekt Java był domem, folder src byłby przytulnym salonem, w którym zbierają się wszyscy główni lokatorzy (twoje klasy). To właśnie tutaj umieszcza się wszystkie pliki źródłowe z kodem, a nie w katalogu głównym projektu, nie w folderze z ustawieniami i nie na pulpicie (nawet jeśli bardzo kusi).

Dlaczego oddzielać źródła od całej reszty?

• W folderze src przechowywane są tylko pliki, które piszesz własnoręcznie: .java.
• Wszystko, co powstaje w trakcie budowania (na przykład pliki .class, pliki tymczasowe), trafia do innych folderów (out, build, target itd.).
• To ułatwia nawigację, czyni projekt czystszym, a IDE — szczęśliwszym.

Przykładowa struktura prostego projektu:

MyFirstProject/
├── .idea/           # pliki serwisowe IntelliJ IDEA — nie ruszamy
├── out/             # tutaj pojawiają się skompilowane pliki .class
├── src/             # tutaj znajduje się twój kod źródłowy!
│   └── Main.java
├── MyFirstProject.iml
└── README.md

Ważne:
Wszystko, co piszesz samodzielnie — klasy, pakiety, interfejsy — powinno znajdować się w folderze src. Nie wrzucaj tam obrazków, muzyki ani tajnych przepisów — do tego służą inne foldery.

2. Pakiety package

W Javie przyjęto grupować klasy w „pakiety” — to jak foldery w systemie plików, tylko dla klas. Pakiety pomagają:

• Unikać konfliktów nazw, jeśli w projekcie są dwie klasy Main — w różnych pakietach nie będą sobie przeszkadzać.
• Logicznie strukturyzować kod (na przykład com.codegym.tasks, com.mycompany.utils).
• Zarządzać dostępem do klas i metod.

Składnia deklarowania pakietu

Na początku każdego pliku Java (przed wszystkimi import i class) umieszcza się wiersz:

package com.codegym.lesson05;

To znaczy: klasa z tego pliku należy do pakietu com.codegym.lesson05.

Ważne:
Foldery w systemie plików muszą odpowiadać nazwie pakietu! Jeśli masz wpisane package com.codegym.lesson05;, to ścieżka do pliku będzie:

src/com/codegym/lesson05/Main.java

Jak utworzyć pakiet w IntelliJ IDEA

1. W panelu projektu kliknij prawym przyciskiem myszy na folderze src.
2. Wybierz New → Package.
3. Wpisz nazwę, na przykład: com.codegym.lesson05 (IDE samo utworzy zagnieżdżone foldery).
4. Teraz utwórz nową klasę wewnątrz tego pakietu. Kliknij prawym przyciskiem myszy na folderze com.codegym.lesson05 i wybierz New → Java Class. Następnie wpisz nazwę

Przykład:

src/
└── com/
    └── codegym/
        └── lesson05/
            └── User.java

Dlaczego nie można wszystkiego wrzucać po prostu do src?

Jeśli wrzucisz wszystkie klasy do jednego worka, projekt szybko zamieni się w „śmietnik”, w którym znalezienie potrzebnego pliku będzie trudniejsze niż znalezienie ładowarki do laptopa w akademiku. Używaj pakietów — łatwiej będzie skalować projekt, podłączać zewnętrzne biblioteki i dzielić kod między różne zespoły.

3. Pełna nazwa klasy

Każda klasa w Javie musi znajdować się w jakimś pakiecie. Pakiet to po prostu „folder” wewnątrz biblioteki klas. Na przykład:

• Klasa System znajduje się w pakiecie java.lang. Jej pełna nazwa — java.lang.System.
• Klasa Scanner znajduje się w pakiecie java.util. Jej pełna nazwa — java.util.Scanner.
• Klasa ArrayList także w java.util, więc pełna nazwa — java.util.ArrayList.

A więc pełna nazwa klasy = nazwa pakietu + kropka + nazwa klasy.

Spróbujmy użyć tego w kodzie:

java.util.Scanner sc = new java.util.Scanner(System.in);
String name = sc.nextLine();
System.out.println("Cześć, " + name);

Tutaj jawnie piszemy java.util.Scanner. Kompilator rozumie, o którą dokładnie klasę chodzi, nawet jeśli w programie są inne klasy o nazwie Scanner.

To bardzo ważne: nazwa klasy może się powtarzać, ale pełna nazwa zawsze jest unikalna.

Po co w ogóle potrzebna jest pełna nazwa?

Wyobraź sobie, że mamy dwie różne klasy Date:

• java.util.Date (stara klasa do pracy z datami),
• java.sql.Date (data do pracy z bazami danych).

Jeśli po prostu napiszesz:

Date d = new Date();

Kompilator nie zrozumie, której dokładnie klasy Date chcesz użyć. Ale jeśli podasz pełną nazwę:

java.util.Date d1 = new java.util.Date();
java.sql.Date d2 = new java.sql.Date(System.currentTimeMillis());

— nie będzie niejasności.

4. Operator import

Za każdym razem pisać pełną nazwę klasy jest niewygodnie. Dlatego w Javie istnieje operator import.

Jeśli napiszemy:

import java.util.Scanner;

To znaczy: „W tym programie będę używać klasy Scanner z pakietu java.util”. Po tym możemy pisać po prostu:

Scanner sc = new Scanner(System.in);

i kompilator zrozumie, że chodzi właśnie o java.util.Scanner.

Zwykły import (pojedyncza klasa)

To najczęstsza opcja. Wskazujemy konkretną klasę:

import java.util.Scanner;
import java.util.ArrayList;

Teraz można pisać krótkie nazwy: Scanner, ArrayList.

Import całego pakietu *

Czasem w programie używa się wielu klas z jednego pakietu. Wtedy można napisać:

import java.util.*;

To znaczy: „Pozwól używać wszystkich klas z pakietu java.util bez pełnej nazwy”.

Teraz można pisać:

Scanner sc = new Scanner(System.in);
ArrayList<String> list = new ArrayList<>();

Ale ważne, by pamiętać: import java.util.*; importuje tylko klasy z pakietu java.util, ale nie z podpakietów. Na przykład klasa java.util.concurrent.ConcurrentHashMap nie zostanie objęta. Trzeba ją zaimportować osobno.

Czego nie da się zrobić za pomocą import

• importu nie można używać wewnątrz metody — pisze się go tylko na początku pliku.
• import nie ładuje klas do pamięci. On tylko mówi kompilatorowi, skąd wziąć klasę.
• import nie zastąpi pełnej nazwy, jeśli istnieją dwie klasy o tej samej nazwie.

5. Classpath — jak Java szuka twoich klas

Classpath to „trasa”, po której Java szuka twoich klas podczas uruchamiania programu. Można to sobie wyobrazić jako listę folderów, w których Java będzie szukać potrzebnych plików .class (skomplikowanych wersji twoich .java).

Domyślnie IDE samo dodaje folder src (albo folder skompilowanych klas, na przykład out/production/ProjectName) do classpath. To znaczy, że jeśli napisałeś klasę w pakiecie com.codegym.lesson05, Java będzie jej szukać pod ścieżką:

out/production/ProjectName/com/javarush/lesson05/Main.class

Jak działa classpath w IntelliJ IDEA?

• Gdy uruchamiasz program przez IDE, ono automatycznie podkłada odpowiedni classpath.
• Jeśli uruchamiasz program z wiersza poleceń, musisz jawnie wskazać classpath za pomocą flagi -cp lub -classpath.
• Wszystkie klasy z twojego projektu i dołączonych bibliotek muszą znajdować się w folderach wskazanych w classpath.

6. Organizacja kodu w projekcie

Jedna klasa — jeden plik

W Javie przyjęte jest, aby każda public-klasa znajdowała się w osobnym pliku, który nazywa się tak samo jak sama klasa. Na przykład jeśli masz klasę Person, plik powinien nazywać się Person.java.

Przykład:

src/com/javarush/lesson05/Person.java

package com.codegym.lesson05;

public class Person {
    String name;
}

Nazwy plików i klas muszą się zgadzać

Jeśli klasa nazywa się MySuperClass, plik musi mieć nazwę MySuperClass.java. To nie kaprys, lecz wymaganie kompilatora Javy. Jeśli się pomylisz — dostaniesz błąd na etapie kompilacji.

Gdzie przechowywać zasoby (obrazy, pliki tekstowe)?

• Dla zasobów zwykle tworzy się osobny folder, na przykład resources lub res.
• W IntelliJ IDEA można oznaczyć taki folder poprzez kliknięcie prawym przyciskiem: Mark Directory as → Resources Root.
• Kod Javy może odwoływać się do tych plików przez classpath.

Przykładowa struktura:

MyFirstProject/
├── src/
│   └── com/javarush/lesson05/
│       └── Main.java
├── resources/
│   └── config.txt

8. Typowe błędy przy pracy ze strukturą projektu

Niezgodność struktury folderów i pakietu
Jeśli na początku pliku jest napisane package com.codegym.lesson05;, a plik leży w src/Main.java, kompilator wyświetli błąd "package does not exist" lub "class not found". Zawsze pilnuj, aby foldery odpowiadały nazwie pakietu!

Niezgodność nazwy pliku i klasy
Jeśli klasa nazywa się Person, a plik — People.java, dostaniesz "class Person is public, should be declared in a file named Person.java".

Ręczne przeniesienie plików bez aktualizacji pakietu
Jeśli przeniosłeś plik do innego folderu, ale zapomniałeś zmienić wiersz package, program się nie skompiluje. Rób to w oknie Project w IDE — ono samo zaktualizuje package!

Zasoby nie zostały dodane do classpath
Jeśli przechowujesz pliki (na przykład tekstowe) poza folderem resources i nie oznaczyłeś folderu jako Resources Root, program nie będzie mógł ich znaleźć przez classpath.