UniHttp: Declarative HTTP Interface Integration Framework for Java Backend Projects

UniHttp is a declarative HTTP interface integration framework that enables Java backend projects to call third‑party HTTP services as if they were local methods, eliminating repetitive HttpClient/OkHttp code and improving maintainability.

1. Overview

The framework automatically handles request construction, parameter binding, response deserialization, and supports various request body types.

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

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

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

2.3 Scan Packages

@UniAPIScan("com.xxx.demo.api")
@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

2.4 Inject and Use

@Service
public class UserAppService {
    @Autowired
    private UserHttpApi userHttpApi;

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

3. Annotation Details

The framework provides a family of annotations to describe how method parameters map to HTTP request parts:

@HttpApi : marks an interface as an HTTP API and can specify a base URL.

@HttpInterface and its shortcuts @GetHttpInterface , @PostHttpInterface , @PutHttpInterface , @DeleteHttpInterface : define HTTP method, path, headers, cookies, and query strings.

@QueryPar , @PathPar , @HeaderPar , @CookiePar : bind method arguments to query parameters, path variables, request headers, and cookies respectively.

@BodyJsonPar , @BodyFormPar , @BodyMultiPartPar , @BodyBinaryPar : specify the request body format (JSON, form‑urlencoded, multipart, binary).

@ComposePar : groups multiple @Par annotations inside a single object to reduce parameter count.

4. Lifecycle Hooks (HttpApiProcessor)

Developers can implement HttpApiProcessor to intercept the request/response lifecycle:

postBeforeHttpMetadata : modify the request metadata before it is sent (e.g., add signatures, extra query parameters).

postSendingHttpRequest : custom send logic or logging.

postAfterHttpResponseBodyString : post‑process the raw response body (e.g., decryption).

postAfterHttpResponseBodyResult : modify the deserialized result.

postAfterMethodReturnValue : AOP‑style processing of the final method return value.

5. Custom HTTP Client

@Configuration
public class CustomConfiguration {
    @Bean
    public OkHttpClient myHttpClient() {
        return new OkHttpClient.Builder()
            .readTimeout(50, TimeUnit.SECONDS)
            .writeTimeout(50, TimeUnit.SECONDS)
            .connectTimeout(10, TimeUnit.SECONDS)
            .connectionPool(new ConnectionPool(20, 10, TimeUnit.MINUTES))
            .build();
    }
}

6. Enterprise Integration Example

The article demonstrates a real‑world scenario where a weather service requires token, sessionId, appId, and request signing. It shows how to configure channel information in application.yml , create a custom @MTuanHttpApi annotation, and implement MTuanHttpApiProcessor to inject appId, generate a SHA‑256 signature, fetch token/sessionId dynamically, and add them to cookies before sending the request.

@Inherited
@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@HttpApi(processor = MTuanHttpApiProcessor.class)
public @interface MTuanHttpApi {
    @AliasFor(annotation = HttpApi.class)
    String url() default "${channel.mtuan.url}";
    String appId() default "${channel.mtuan.appId}";
}

Finally, the WeatherApi interface uses the custom annotation to define getCityWeather and getToken methods, and the processor sets response code to 999 as a demonstration.

GitHub repository: https://github.com/burukeYou/UniAPI