Simplify Third‑Party HTTP Calls with UniHttp: A Declarative Java Client

Background

In enterprise projects, using traditional programmatic HTTP clients such as HttpClient or OkHttp often leads to duplicated integration code, making the system hard to maintain and read. Different developers may create their own wrappers for each third‑party service, resulting in inconsistent code quality.

UniHttp Overview

UniHttp is a declarative HTTP‑interface framework for Java. An interface is annotated with @HttpApi (specifying the base URL) and method‑level annotations such as @GetHttpInterface, @PostHttpInterface, @PutHttpInterface, @DeleteHttpInterface. The framework builds the request, sends it (defaulting to OkHttp), and deserialises the response with Fastjson, allowing the call to look like a local method invocation.

Quick Start

Add the Maven dependency:

<dependency>
  <groupId>io.github.burukeyou</groupId>
  <artifactId>uniapi-http</artifactId>
  <version>0.0.4</version>
</dependency>

Define an API interface:

@HttpApi(url = "http://localhost:8080")
interface UserHttpApi {
    @GetHttpInterface("/getUser")
    BaseRsp<String> getUser(@QueryPar("name") String name, @HeaderPar("userId") Integer id);

    @PostHttpInterface("/addUser")
    BaseRsp<Add4DTO> addUser(@BodyJsonPar Add4DTO req);
}

Key parameter annotations:

@QueryPar – adds the value to the URL query string.

@HeaderPar – adds the value to request headers.

@BodyJsonPar – sends the value as JSON body (Content‑Type: application/json).

@BodyFormPar – sends the value as form data (Content‑Type: application/x-www-form-urlencoded).

@BodyMultiPartPar – sends multipart/form‑data, supporting file uploads.

@CookiePar – adds cookie data.

Inject the generated proxy with Spring:

@Service
class UserAppService {
    @Autowired
    private UserHttpApi userHttpApi;

    public void doSomething() {
        userHttpApi.getUser("jay", 3);
    }
}

Lifecycle Hooks (HttpApiProcessor)

UniHttp provides four extensible hooks via a custom HttpApiProcessor implementation: postBeforeHttpMetadata – invoked before the request is built; useful for adding signatures or extra query parameters. postSendHttpRequest – invoked when the request is about to be sent; can replace the sending logic or add logging. postAfterHttpResponseBodyResult – invoked after the response body has been deserialized; allows post‑processing of the result. postAfterMethodReturnValue – final AOP‑style hook after the proxy method returns.

An example processor adds an appId query parameter, generates a sign header, fetches a token and sessionId from a separate authentication endpoint, injects them as cookies, logs the raw request/response, and modifies the response code.

Enterprise Use‑Case: Weather Service Integration

Configuration in application.yml supplies the channel URL, appId, and public key. A custom annotation @MTuanHttpApi extends @HttpApi and references a processor MTuanHttpApiProcessor. The processor implements the three hooks to satisfy the following requirements:

Append the channel‑assigned appId to every request.

Generate a sign header by concatenating query parameters, request body and the public key, then hashing with SHA‑256.

Before each request, call the getToken endpoint to obtain a token (response body) and a sessionId (response header) and add them as cookies.

Log request URL and raw HTTP protocol, and after receiving the response, log the raw response protocol.

Set a custom response code (e.g., 999) in the deserialized BaseRsp object.

The concrete WeatherApi interface demonstrates two methods: getCityWeather – a simple GET returning BaseRsp<WeatherDTO>. getToken – returning HttpResponse<BaseRsp<TokenDTO>> to expose raw headers.

Repository

Source code and test cases are available at:

https://github.com/burukeYou/UniAPI