Wywołanie HTTP — to nie wywołanie metody Javy

1. Metoda w pamięci, HTTP w sieci

Gdy po raz pierwszy słyszysz „zrób żądanie HTTP”, mózg Java-developera często automatycznie tłumaczy to na „no, to jak wywołać metodę, tylko przez internet”. W praktyce właśnie ta myśl potem tworzy połowę dziwnych bugów: od „dlaczego tu nie ma wartości” do „dlaczego wszystko zawisło”. Zafiksujmy granicę od razu, póki jeszcze nie zdążyła ci zorganizować imprezki z debuggerem.

W tym miejscu forma wymiany jest już widoczna w całości: klient składa request, wysyła go przez sieć i dostaje response z powrotem. W logach i narzędziach wygląda to jak wymiana wiadomości, a nie jak „skok w cudzy kod”. Z tego obrazka rośnie główny wniosek wykładu: wywołania HTTP nie można utożsamiać ze zwykłym wywołaniem metody Javy.

Metoda Javy ma bardzo wyraźną mechanikę: JVM wykonuje kod w ramach jednego procesu, z jedną pamięcią, z jednymi typami, z jednym stosem wywołań. Wywołanie HTTP to nie „wykonać cudzą metodę”, tylko wysłać ustrukturyzowaną wiadomość (request) do innego programu i poczekać na inną ustrukturyzowaną wiadomość (response). Między tobą a wynikiem pojawia się cała warstwa rzeczywistości: serializacja danych, sieć, routing po stronie serwera, format odpowiedzi, status, opóźnienia, a czasem po prostu „nikt nie odpowiedział”.

Żeby to utrwalić nie na poziomie „bo tak powiedzieli”, porównajmy dwa światy w jednej tabeli.

Jeśli trzymasz w głowie tę tabelę, masz prawidłowy „inżynierski odruch”: HTTP to osobny wszechświat, i należy się do niego odnosić inaczej.

2. Lokalne wywołanie metody w Javie

Żeby poczuć kontrast, warto na chwilę wrócić do znanego świata metod Javy i zobaczyć, jak tam wszystko jest „domowe”. Gdy wywołujesz metodę, nie składasz wiadomości, nie myślisz o trasach sieciowych i nie sprawdzasz kodu statusu wyniku. Po prostu mówisz JVM-owi: „wykonaj ten fragment kodu” — i dostajesz wartość. Wszystko dzieje się w jednej pamięci, pod kontrolą jednego procesu.

Oto minimalny przykład lokalnego wywołania. Wydaje się nudny — i to dobrze. Nuda tu oznacza przewidywalność.

public class LocalCallExample {

    static String localTitle() {
        // Lokalna metoda: wykonuje się tutaj, w tej JVM
        return "Clean Code";
    }

    public static void main(String[] args) {
        // Zwykłe wywołanie metody: żadnych sieci, statusów i nagłówków
        String title = localTitle();
        System.out.println(title); // Clean Code
    }
}

Co tu jest ważne, poza tym, co oczywiste?

Po pierwsze, typ wyniku znasz z wyprzedzeniem. Metoda jest zadeklarowana jako String, więc dostaniesz String (albo program padnie z exception-em, ale „po cichu zwrócić coś dziwnego” metoda nie ma prawa). Po drugie, wszystko dzieje się we wspólnej pamięci. Zwracana wartość to obiekt/wartość, który już żyje w tej samej JVM. Nie musisz go „dekodować” i „rozpakowywać” z tekstu.

Po trzecie, lokalne wywołanie albo zwraca wartość, albo rzuca wyjątek. I ten wyjątek jest częścią twojego programu: możesz go złapać try/catch-em, popatrzeć na stack trace, zobaczyć linijkę, gdzie wszystko się zepsuło, i porządnie się w tym rozeznać.

Wreszcie, lokalna metoda — to „swój kod”. Nawet jeśli leży w innym pakiecie (package) i pisał go kolega, i tak możesz otworzyć źródła, postawić breakpoint i zobaczyć, co się dzieje. Przy wywołaniu HTTP takiego luksusu zwykle nie ma: komunikujesz się z cudzym systemem przez kontrakt, a nie przez dostęp do źródeł i debuggera.

3. Wywołanie HTTP: żądanie i odpowiedź

Teraz przenieśmy się do świata transportu. Wywołanie HTTP zaczyna się nie od „wywołać funkcję”, tylko od „uformować wiadomość”. Decydujesz, jaki method, jaki path, jakie headers i czy będzie body. Potem wysyłasz tę wiadomość przez sieć — a dalej wszystko, co dzieje się po drugiej stronie, nie jest już pod twoją bezpośrednią kontrolą.

Na poziomie koncepcyjnym można nawet opisać HTTP-request i HTTP-response jako proste struktury danych (w rzeczywistości są one oczywiście bardziej skomplikowane, ale chodzi nam o ideę „to osobny obiekt-wiadomość”).

import java.util.Map;

public record HttpRequestData(
        String method, // Metoda HTTP: GET/POST/PUT/DELETE itd.
        String pathWithQuery, // Ścieżka i parametry query, np.: /search?q=clean+code
        Map<String, String> headers, // Nagłówki (metadane żądania)
        String body // Ciało żądania (ładunek), często JSON
) { }

I odpowiedź:

import java.util.Map;

public record HttpResponseData(
        int status, // Status HTTP: 200, 404, 500 itd.
        Map<String, String> headers, // Nagłówki odpowiedzi (metadane odpowiedzi)
        String body // Ciało odpowiedzi (dane albo opis błędu)
) { }

Zwróć uwagę na odczucie: przy lokalnym wywołaniu czekasz na String title, a w świecie HTTP czekasz na kopertę (response). Nawet jeśli „główne dane” leżą w body, nie istnieją w próżni: ich sens zależy od status i czasem od headers. Widzieliśmy to już w wykładzie o response: identyczne ciało przy różnych statusach może oznaczać zupełnie różne rzeczy.

Żeby wizualnie utrwalić różnicę, oto uproszczony schemat sekwencji zdarzeń przy wywołaniu HTTP:

sequenceDiagram
    %% Uproszczony schemat: request/response — to osobne wiadomości, które wędrują przez sieć
    participant C as "Klient (twój kod/narzędzie)"
    participant N as "Sieć"
    participant S as "Serwer (inna aplikacja)"

    C->>N: "Wysłać HTTP request (method + path + headers + body)"
    N->>S: Dostarczyć bajty
    S->>S: Rozebrać request i wybrać handler
    S-->>N: "Zwrócić HTTP response (status + headers + body)"
    N-->>C: Dostarczyć bajty

Kluczowy moment: nie możesz tego odbierać jako „wywołałem metodę i dostałem wartość”, bo między „wywołałem” i „dostałem” jest mnóstwo powodów, dla których możesz nic nie dostać, dostać błędny status, dostać nieoczekiwany format albo dostać powolną odpowiedź.

4. Obiekty vs bajty: nie da się „przekazać obiektu przez HTTP”

Następna pułapka dla początkującego brzmi tak: „No, skoro w Javie pracuję z obiektami, to i przez HTTP przekażę obiekt”. Wewnątrz jednego procesu to prawie prawda: przekazujesz referencję do obiektu albo wartość. W sieci referencji do obiektów nie ma, bo inny program ma inną pamięć. Między aplikacjami wędrują bajty, czyli dane trzeba zamieniać na coś przenośnego: tekst, JSON, format binarny itd.

Dokładnie po to wiadomość HTTP ma body: to miejsce, gdzie wkładasz „ładunek”. Na razie można myśleć o body jak o napisie.

Porównaj: lokalnie możesz zwrócić obiekt…

public record Book(String title, String author) { } // Dane domenowe: obiekt w pamięci JVM

public class LocalDomainExample {

    static Book localBook() {
        // Zwracamy obiekt bezpośrednio: żyje w tej samej pamięci co kod wywołujący
        return new Book("Clean Code", "Robert C. Martin");
    }
}

…a „przez HTTP” najczęściej będziesz mieć coś w stylu:

public class RemoteBodyExample {

    static String remoteBody() {
        // Przez sieć „lecą” bajty: najczęściej to tekst (np. JSON), a nie obiekt Book
        return """
               {"title":"Clean Code","author":"Robert C. Martin"}
               """;
    }
}

Drugi listing to nie obiekt Book. To tekst (zbiór znaków), który na umowę można interpretować jako książkę. I tu zaczyna się ważna robota: żeby dwie aplikacje rozumiały się nawzajem, muszą umówić się, w jaki konkretnie sposób tekst w body opisuje dane. A jeśli umowa zostanie naruszona — jedna z aplikacji będzie „czytać nie to”.

Nawet jeśli teraz wydaje się to drobiazgiem, myśl jest prosta: przy lokalnym wywołaniu typy chronią cię niemal automatycznie, a przy wywołaniu HTTP ochrona pojawia się tylko, jeśli sam zdyscyplinowanie podchodzisz do kontraktu wymiany.

5. Wynik: return/exception i status/body

W lokalnej metodzie wynik to albo return, albo exception. Przy wywołaniu HTTP masz co najmniej trzy różne sytuacje, które początkujący developer często miesza w jedną kaszę:

Pierwsza sytuacja — serwer odpowiedział, i masz response. To znaczy: dostałeś status, być może headers, być może body. Nawet jeśli status mówi „błąd”, to wciąż pełnoprawna odpowiedź.

Druga sytuacja — serwer nie odpowiedział, bo nie udało ci się połączyć, sieć padła, adres jest nieprawidłowy, połączenie zostało zerwane, nie doczekałeś odpowiedzi. W tej sytuacji może w ogóle nie być żadnego HttpResponseData.

Trzecia sytuacja — serwer odpowiedział „niby pomyślnie”, ale body jest puste/nieoczekiwane/nie tego formatu. I to osobny ból: formalnie odpowiedź jest, ale „danych, których chciałeś”, nie ma.

Spróbujmy zobrazować to w bardzo prostym pseudo-kodzie, nie przywiązując się do konkretnego klienta HTTP (bo naszym celem jest model w głowie, a nie biblioteka).

public class RemoteResultExample {

    String handle(HttpResponseData response) {
        // 1) Najpierw sprawdzamy status: to „koperta”, bez której nie można rozumieć body
        if (response.status() != 200) {
            // Serwer odpowiedział, ale zgłosił błąd przez HTTP-status
            return "Serwer odpowiedział błędem: status=" + response.status();
        }

        // 2) Dopiero po udanym statusie ma sens czytanie danych z body
        return "Dane z body: " + response.body();
    }
}

Zauważ: w świecie lokalnym zwykle nie piszesz if (ok) wokół każdego wywołania. A w świecie HTTP to całkowicie normalna część życia: najpierw zrozumieć, jaki jest status, i dopiero potem decydować, jak interpretować body.

Właśnie dlatego myślenie „wywołanie HTTP ≈ metoda” łamie architekturę. Człowiek czeka na „zwracaną wartość”, i drażni go konieczność czytania statusu. Ale status to nie „zbędna biurokracja”, tylko część umowy: serwer nie jest zobowiązany oddawać ci danych, jest zobowiązany uczciwie powiedzieć, co się stało.

6. Czas i niepewność w HTTP

Jest jeszcze jedna sprawa, która w świecie metod często jest niezauważalna: czas. Lokalne wywołanie metody to zwykle mikroskopowa operacja w porównaniu z dowolnym I/O. Wywołanie HTTP to niemal czyste I/O. Nawet jeśli serwer pracuje szybko, masz sieć, która lubi być nieprzewidywalna: to normalnie, to wolno, to „ojej, Wi-Fi postanowił pomyśleć o sensie życia”.

Można poczuć to nawet na zabawkowym przykładzie. Lokalna metoda wywołuje się natychmiast:

public class TimingExample {

    static String localTitle() {
        // Operacja lokalna: bez czekania na sieć, dysk itp.
        return "Clean Code";
    }

    public static void main(String[] args) {
        // Ważne: nanoTime() — do mierzenia czasów trwania, a nie „bieżącego czasu”
        long start = System.nanoTime();
        localTitle();
        long end = System.nanoTime();

        // Tu prawie zawsze będzie „bardzo mała liczba”
        System.out.println("ns = " + (end - start)); // ns = <bardzo mała liczba>
    }
}

Liczba będzie mała (i w różnych uruchomieniach różna), ale chodzi o to, że lokalne wywołanie mierzy się w nanosekundach/mikrosekundach, a każde realne wywołanie HTTP będziesz odczuwać jako milisekundy, a czasem jako sekundy. To nie „słaba biblioteka” ani „Java zwalnia”. To fizyka świata: komunikujesz się z innym programem, często przez kilka węzłów sieciowych.

Stąd prosty nawyk backend-developera: do wywołania HTTP odnoszą się jak do drogiej operacji. Nie robi się go „na wszelki wypadek”, nie wkłada się w bezsensowne pętle i nie oczekuje się, że zawsze będzie szybki.

7. Kontrakty: sygnatura i HTTP

Jest jeszcze jeden powód, dla którego nie da się utożsamiać wywołania HTTP z metodą: kontrakt w tych światach jest zbudowany inaczej. U metody kontrakt to jej sygnatura i typy. Kompilator ci pomaga: zmieniłeś typ argumentu — natychmiast czerwieni się połowa projektu, i to wspaniale (boli, ale leczy).

Kontrakt HTTP „kompilatora” nie ma. Są umowy: jaki method, jaki path, jakie headers, czy będzie body, jaki format danych, jaki status przy sukcesie i jaki przy błędzie. Jeśli po jednej stronie zmienisz coś w kontrakcie, druga strona może się o tym dowiedzieć tylko w runtime, i zwykle dowiaduje się w najbardziej „odpowiednim” momencie: gdy użytkownik już naciska przycisk, a tobie już za późno.

Porównajmy bardzo praktycznie:

I właśnie dlatego myślenie backendowe każe ci traktować HTTP jako osobną dyscyplinę. Nie po prostu „zdalnie szarpiesz metodę”. Wchodzisz w świat umów i wiadomości, gdzie ważne są szczegóły, których nie da się ukryć pod dywanem bez konsekwencji.

8. ReadLater Starter: granica systemów

W naszym projekcie ReadLater Starter ta różnica będzie pojawiać się ciągle, nawet jeśli na razie nie napisałeś jeszcze ani linijki kodu do HTTP. Z założenia projektu jest zewnętrzny katalog książek (osobny serwis) i jest nasza aplikacja, która z nim się komunikuje. I tu trzeba sobie uświadomić: nawet jeśli w 100% rozumiesz, że „na zewnątrz jest API”, mózg i tak będzie próbował oszukać i myśleć: „no chcę po prostu dostać listę książek, czyli to jak catalog.search()”.

Prawidłowy obrazek jest taki: catalog.search() wewnątrz naszej aplikacji (jeśli ją zrobisz) — to lokalna metoda, która w pewnym momencie uformuje HTTP-request, wyśle go na zewnątrz, dostanie HTTP-response, sprawdzi status, i dopiero potem zamieni body w coś wygodnego dla reszty programu.

Czyli wewnątrz aplikacji rzeczywiście będziesz pracować metodami. Ale granica na zewnątrz zawsze będzie wyglądać jak „wiadomość tam — wiadomość z powrotem”. To warto pamiętać nawet na poziomie codziennym: gdy widzisz napis postaci https://.../search?q=clean+code, to nie „nazwa metody w internecie”. To część adresu dla wiadomości, która pójdzie do innego systemu. A gdy ta granica stanie się normalna, inaczej zaczynają się czytać i method, i path: to już nie „nazwa zdalnej funkcji”, tylko części kontraktu między dwoma systemami.

Tak samo, gdy ktoś będzie zwracał się do naszej aplikacji przez HTTP (np. z przeglądarki albo z innego narzędzia), nie będzie „wywoływał naszej metody”. Będzie wysyłał request, a my będziemy decydować, który fragment kodu powinien na niego odpowiedzieć i w jakiej postaci zwrócimy response.

Jeśli trzymać ten obraz w głowie, architektura projektu wychodzi staranniejsza: lokalny kod można projektować typami i metodami, a zewnętrzne interakcje — kontraktami wiadomości.

9. Typowe błędy przy wywołaniach HTTP

Błąd nr 1: myśleć, że wywołanie HTTP „musi zwrócić wartość”, jak metoda.
Początkujący psychologicznie czeka, że skoro „wywołał”, to „mu zwrócą”. W świecie HTTP może wrócić response z błędnym status, może wrócić puste body, a może nie wrócić w ogóle nic, bo sieć albo adres zawiodły. Prawidłowy nawyk to najpierw przyjąć rzeczywistość response (albo jego brak), i dopiero potem mówić o danych.

Błąd nr 2: czytać tylko body i ignorować status.
To prawie jak w życiu: patrzeć tylko na treść listu i ignorować pieczątkę „Adresat nieznany”. Ciało odpowiedzi samo w sobie nie gwarantuje, że żądanie jest udane. Jeśli nie patrzysz na status, możesz wesoło próbować „sparsować” tekst błędu jako dane i potem długo się dziwić, dlaczego „mam krzywy JSON”.

Błąd nr 3: mieszać „serwer odpowiedział błędem” i „serwer w ogóle nie odpowiedział”.
Odpowiedź ze statusem błędu to wciąż odpowiedź, czyli połączenie było, protokół zadziałał, serwer coś powiedział. A awaria sieci to inna sytuacja: nawet nie doszedłeś do etapu otrzymania response. Te przypadki wymagają innego myślenia i, w realnym kodzie, innej obsługi.

Błąd nr 4: próbować mentalnie „przekazać obiekt przez HTTP”.
Wewnątrz JVM przekazujesz wartości i referencje. Przez HTTP przekazujesz bajty. Jeśli nie utrzymujesz tej granicy, zaczniesz budować oczekiwania w stylu „no przecież wysłałem Book, dlaczego po drugiej stronie nie ma Book”. Po drugiej stronie nie ma twojej pamięci, twoich klas i twoich referencji — jest tylko to, co realnie włożyłeś w body.

Błąd nr 5: oczekiwać od wywołania HTTP takiej samej szybkości i stabilności, jak od metody.
Lokalna metoda to zwykle bardzo szybko. Wywołanie HTTP to I/O, a I/O może być powolne. Jeśli założysz w głowie „jak metoda”, zaczniesz wywoływać zdalny serwis zbyt często, zbyt głęboko wewnątrz logiki, a potem zderzysz się z „skądś wzięło się opóźnienie”. Nawet w projektach edukacyjnych warto trzymać poczucie „to droga operacja”.