How to Simplify Third‑Party HTTP Integration with UniHttp: A Declarative Java Framework

Introduction

In enterprise projects, using traditional programmatic HTTP clients like HttpClient or OkHttp leads to scattered, hard‑to‑maintain code when integrating many third‑party HTTP APIs. UniHttp provides a declarative framework that lets you call remote HTTP services as if they were local methods.

1. Overview

UniHttp is a declarative HTTP integration framework that automatically handles request construction, parameter binding, and response deserialization (using FastJSON). It focuses on high cohesion and readability rather than low‑level request sending.

2. Quick Start

2.1 Add Dependency

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

2.2 Define Interface

Mark an interface with @HttpApi (specify base URL) and annotate methods with @GetHttpInterface, @PostHttpInterface, etc. Parameters are annotated with @QueryPar, @HeaderPar, @BodyJsonPar, and other @*Par annotations.

@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);
}

Inject the generated proxy with Spring’s @Autowired and call methods directly.

3. Annotation Details

@HttpApi

Marks the interface; you can set the base URL and a custom HttpApiProcessor for lifecycle hooks.

@HttpInterface

Specifies HTTP method, path, headers, query parameters, cookies, etc. Shortcut annotations like @GetHttpInterface, @PostHttpInterface, @PutHttpInterface, @DeleteHttpInterface are provided.

@QueryPar, @PathPar, @HeaderPar, @CookiePar, @BodyJsonPar, @BodyFormPar, @BodyMultiPartPar, @BodyBinaryPar, @ComposePar

Define where a method argument should be placed in the request (query string, path variable, header, cookie, JSON body, form data, multipart, binary, or composite object).

4. Raw HttpResponse

If you need the original response (status code, headers, cookies), use HttpResponse<T>. The generic type T is the deserialized body.

5. File Download

For download endpoints, return HttpBinaryResponse, HttpFileResponse, or HttpInputStreamResponse to obtain the file content.

6. HttpApiProcessor Lifecycle Hooks

Implement HttpApiProcessor to intercept the request/response lifecycle:

postBeforeHttpMetadata : modify request before sending (e.g., add signatures).

postSendHttpRequest : custom sending logic or logging.

postAfterHttpResponseBodyString : process raw response body.

postAfterHttpResponseBodyResult : modify deserialized result.

postAfterMethodReturnValue : final AOP‑style processing.

7. Custom Processor Example

The article shows a concrete MTuanHttpApiProcessor that adds an appId query parameter, generates a sign header, fetches a token and sessionId from a separate endpoint, inserts them as cookies, logs the request, and forces the response code to 999.

@Component
public class MTuanHttpApiProcessor implements HttpApiProcessor<MTuanHttpApi> {
    // fields, autowired beans ...

    @Override
    public HttpMetadata postBeforeHttpMetadata(HttpMetadata meta,
            HttpApiMethodInvocation<MTuanHttpApi> inv) {
        // add appId, compute sign, put into header
        return meta;
    }

    @Override
    public HttpResponse<?> postSendHttpRequest(HttpSender sender,
            HttpMetadata meta) {
        // obtain token/sessionId, add as cookies, send request, log
        return sender.sendHttpRequest(meta);
    }

    @Override
    public Object postAfterHttpResponseBodyResult(Object body,
            HttpResponse<?> rsp, Method method, HttpMetadata meta) {
        if (body instanceof BaseRsp) {
            ((BaseRsp) body).setCode(999);
        }
        return body;
    }
}

8. Real‑World Integration

Using the custom annotation @MTuanHttpApi, you can define a WeatherApi interface that automatically handles token acquisition, signing, and appId injection for every request, demonstrating enterprise‑level third‑party channel integration.

Conclusion

UniHttp turns repetitive HTTP client code into clean, declarative interfaces, supports extensive customization via annotations and lifecycle processors, and integrates smoothly with Spring Boot.