When you’re building modern Java applications, particularly those that revolve around microservices or serverless setups, the Micronaut framework quickly earns its stripes for being both efficient and super user-friendly. One of the coolest features it offers is its declarative, compile-time HTTP client, which pretty much makes the art of making HTTP requests to external services a breeze.

Before we take a deep dive into that, setting up a basic Micronaut application is the first step. Micronaut is designed to be modular and test-friendly, which makes it an appealing choice for JVM-based applications. You can set up a brand new Micronaut project with all the bells and whistles via the Micronaut CLI like this:

mn create-app hello-world --features=http-client --build=maven --lang=java --test=junit

This handy command whips up a basic Micronaut app with the HTTP client feature ready to roll.

Now, let’s get into the nitty-gritty of the declarative HTTP client. This client stands out due to the @Client annotation, which allows you to define an HTTP client interface for making requests to outside services.

Picture this: You have a client for the GitHub API. It might look something like this:

import io.micronaut.http.annotation.Get;
import io.micronaut.http.annotation.Header;
import io.micronaut.http.client.annotation.Client;

@Client(id = "github", url = "https://api.github.com")
public interface GithubClient {

    @Get("/repos/{owner}/{repo}/releases")
    List<GithubRelease> fetchReleases(@Header("User-Agent") String userAgent, @Header("Accept") String accept, @PathVariable String owner, @PathVariable String repo);
}

In this setup, your GithubClient interface defines a method, fetchReleases, which makes a GET request to GitHub’s API to fetch releases for a specific repository. The @Client annotation lays down the base URL, and the @Get annotation spells out the path and HTTP method.

To actually use this GithubClient in your application, you need to inject it into your service or controller class, like so:

import jakarta.inject.Singleton;
import jakarta.inject.Inject;

@Singleton
public class GithubService {

    private final GithubClient githubClient;

    @Inject
    public GithubService(GithubClient githubClient) {
        this.githubClient = githubClient;
    }

    public List<GithubRelease> getReleases(String owner, String repo) {
        return githubClient.fetchReleases("Micronaut HTTP Client", "application/vnd.github.v3+json, application/json", owner, repo);
    }
}

Here, the GithubService class grabs the GithubClient and uses it to fetch releases for any given repo. Easy peasy.

Micronaut also allows for a lot of customization through configuration files. For instance, you could tweak your HTTP client settings using the application.yml file, like so:

github:
  url: https://api.github.com
  user-agent: Micronaut HTTP Client
  accept: application/vnd.github.v3+json, application/json

And then, use these configs in your client interface:

@Client(id = "github", url = "${github.url}")
public interface GithubClient {

    @Get("/repos/{owner}/{repo}/releases")
    List<GithubRelease> fetchReleases(@Header("User-Agent") String userAgent, @Header("Accept") String accept, @PathVariable String owner, @PathVariable String repo);
}

If you’re ever in need of more control over your HTTP requests, Micronaut also offers a low-level client API that lets you create and manage HTTP clients programmatically. For instance, creating a client for the GitHub API might look like this:

import io.micronaut.http.HttpRequest;
import io.micronaut.http.HttpResponse;
import io.micronaut.http.client.HttpClient;
import io.micronaut.http.uri.UriBuilder;
import jakarta.inject.Singleton;

@Singleton
public class GithubLowLevelClient {

    private final HttpClient httpClient;
    private final URI uri;

    public GithubLowLevelClient(@Client(id = "github") HttpClient httpClient, GithubConfiguration configuration) {
        this.httpClient = httpClient;
        uri = UriBuilder.of("/repos")
                .path(configuration.organization())
                .path(configuration.repo())
                .path("releases")
                .build();
    }

    public Publisher<List<GithubRelease>> fetchReleases() {
        HttpRequest<?> req = HttpRequest.GET(uri)
                .header("User-Agent", "Micronaut HTTP Client")
                .header("Accept", "application/vnd.github.v3+json, application/json");

        return httpClient.retrieve(req, Argument.listOf(GithubRelease.class));
    }
}

In this nifty example, the GithubLowLevelClient class uses the low-level API to send a GET request to GitHub’s API. This method gives you tons of flexibility for customizing requests.

To keep things on the up-and-up, testing your HTTP client is crucial. Micronaut offers several testing utilities, including mock servers and test annotations. Here’s a snapshot of how you might test the GithubClient using a mock server:

import io.micronaut.http.HttpResponse;
import io.micronaut.http.client.exceptions.HttpClientResponseException;
import io.micronaut.test.annotation.MockBean;
import io.micronaut.test.annotation.MicronautTest;
import org.junit.jupiter.api.Test;

@MicronautTest
public class GithubClientTest {

    @Test
    public void testFetchReleases() {
        GithubClient client = applicationContext.getBean(GithubClient.class);

        // Mock the HTTP response
        HttpResponse response = HttpResponse.ok("[{\"id\":1,\"name\":\"release-1\"}]");
        MockHttpClientResponseException exception = new MockHttpClientResponseException(response);

        // Test the client
        List<GithubRelease> releases = client.fetchReleases("micronaut-projects", "micronaut-core");

        // Assert the results
        assertNotNull(releases);
        assertEquals(1, releases.size());
    }

    @MockBean(GithubClient.class)
    GithubClient githubClient() {
        return new GithubClient() {
            @Override
            public List<GithubRelease> fetchReleases(String owner, String repo) {
                // Return a mock response
                return Arrays.asList(new GithubRelease(1, "release-1"));
            }
        };
    }
}

In this setup, the GithubClientTest class creates a mock bean to simulate the HTTP response and tests the fetchReleases method of the GithubClient.

Micronaut’s declarative HTTP client is a seriously powerful tool for pulling off HTTP requests in your Java applications. With its compile-time generation and annotation-based configs, it streamlines the process of connecting with external services. Whether you’re building microservices, serverless functions, or even more traditional web apps, Micronaut’s HTTP client makes your code more efficient and manageable.

By sticking to these examples and best practices, you can harness the full power of Micronaut’s HTTP client in your projects, making your development journey smooth and enjoyable.