UniHttp是一个声明式的HTTP接口对接框架，它能够帮助开发者以极快的方式完成对一个第三方HTTP接口的对接和使用。以下是对UniHttp的详细使用说明及示例：
一、UniHttp简介
UniHttp框架注重于如何保持高内聚和可读性高的代码情况下与快速第三方渠道接口进行对接和集成。与其说是对接的HTTP接口，不如说是对接的第三方渠道。UniHttp可支持自定义接口渠道方HttpAPI注解以及一些自定义的对接和交互行为，为此扩展了发送、响应和反序列化一个HTTP请求的各种生命周期钩子，开发者可自行去扩展实现。
二、UniHttp的使用
1. 引入依赖
首先，需要在项目的pom.xml文件中引入UniHttp的依赖：
<dependency>
<groupId>io.github.burukeyou</groupId>
<artifactId>uniapi-http</artifactId>
<version>0.0.4</version>
</dependency>
2. 创建接口并标记
创建一个接口，并在接口上标记@HttpApi注解，指定请求的域名URL。然后，在方法上配置对接的接口，并使用各种@Par后缀的注解来指定请求的参数。
例如：
@HttpApi(url = "http://localhost:7001/test")
public interface TestHttpApi {
@GetHttpInterface("/getUser")
HttpResponse<String> getUser(@QueryPar("name") String param, @HeaderPar("userId") Integer id);
@PostHttpInterface("/addUser")
HttpResponse<String> addUser(@BodyJsonPar VideoDTO req);
}
在上述示例中，@GetHttpInterface和@PostHttpInterface分别用于配置GET和POST请求。@QueryPar表示将参数值放到HTTP请求的查询参数内，@HeaderPar表示将参数值放到HTTP请求的请求头里，@BodyJsonPar表示将参数值放到HTTP请求body内，并且content-type是application/json。
3. 声明定义的HttpAPI的包扫描路径
在Spring的配置类上使用@UniAPIScan注解标记定义的@HttpAPI的包扫描路径。这样，UniHttp会自动为标记了@HttpApi接口的生成代理对象，并将其注入到Spring容器中。之后，只需要像使用Spring的其他bean一样，通过依赖注入来使用这些接口。
例如：
@UniAPIScan("com.hdx.contractor.util")
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
4. 依赖注入并使用
通过依赖注入的方式，将创建的接口注入到需要使用的地方，并调用其方法。
例如：
@Service
public class UserAppService {
@Autowired
private TestHttpApi testHttpApi;
public void doSomething() {
HttpResponse<String> response = testHttpApi.getUser("test", 1);
// 处理响应结果
}
}
三、UniHttp的注解说明
- @HttpApi：用于标记接口，指定请求的域名URL，也可指定自定义的HTTP代理逻辑等。
- @HttpInterface及其变种（如@GetHttpInterface、@PostHttpInterface等）：用于配置一个接口的参数，包括请求方式、请求路径、请求头、请求cookie、请求查询参数等。
- @Par后缀的注解（如@QueryPar、@HeaderPar、@BodyJsonPar等）：用于方法参数上，指定在发送请求时将参数值放到HTTP请求体的哪部分上。
四、示例详解
以下是一个完整的示例，展示了如何使用UniHttp对接一个第三方HTTP接口：
// 引入必要的依赖和注解
import com.burukeyou.uniapi.http.annotation.HttpApi;
import com.burukeyou.uniapi.http.annotation.param.*;
import com.burukeyou.uniapi.http.annotation.request.GetHttpInterface;
import com.burukeyou.uniapi.http.annotation.request.PostHttpInterface;
import com.burukeyou.uniapi.http.core.response.HttpResponse;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;
import org.springframework.stereotype.Service;
// 声明HTTP接口
@HttpApi(url = "http://localhost:7001/test")
public interface TestHttpApi {
@GetHttpInterface("/getUser")
HttpResponse<String> getUser(@QueryPar("name") String param, @HeaderPar("userId") Integer id);
@PostHttpInterface("/addUser")
HttpResponse<String> addUser(@BodyJsonPar UserDTO req);
}
// 用户数据传输对象
public class UserDTO {
private String name;
private Integer age;
// getter和setter方法
}
// Spring Boot应用主类
@SpringBootApplication
@UniAPIScan("com.example.demo.api") // 指定@HttpApi接口所在的包路径
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
// 服务类，用于调用HTTP接口
@Service
public class UserService {
@Autowired
private TestHttpApi testHttpApi;
public void getUserAndAddUser() {
// 调用GET接口
HttpResponse<String> getUserResponse = testHttpApi.getUser("John", 123);
System.out.println("GetUser Response: " + getUserResponse.getBody());
// 准备POST请求的数据
UserDTO userDTO = new UserDTO();
userDTO.setName("Jane");
userDTO.setAge(25);
// 调用POST接口
HttpResponse<String> addUserResponse = testHttpApi.addUser(userDTO);
System.out.println("AddUser Response: " + addUserResponse.getBody());
}
}
在上面的示例中，我们首先定义了一个TestHttpApi接口，用于对接第三方的HTTP接口。然后，在Spring Boot应用主类上使用了@UniAPIScan注解来指定@HttpApi接口所在的包路径。最后，在UserService类中通过依赖注入的方式注入了TestHttpApi接口，并调用了其方法。
通过以上步骤，就可以使用UniHttp框架快速对接和使用第三方HTTP接口了。
五、高级功能与自定义配置
1. 自定义HTTP代理逻辑
UniHttp允许开发者通过实现HttpProxy接口来自定义HTTP请求的处理逻辑。这包括在发送请求之前和接收响应之后执行自定义操作。
public class CustomHttpProxy implements HttpProxy {
@Override
public HttpRequestWrapper beforeSend(HttpRequestWrapper requestWrapper) {
// 在发送请求之前修改请求，例如添加自定义请求头
requestWrapper.addHeader("Custom-Header", "HeaderValue");
return requestWrapper;
}
@Override
public <T> HttpResponse<T> afterReceive(HttpResponse<T> response, HttpRequestWrapper requestWrapper) {
// 在接收响应之后处理响应，例如记录日志或修改响应内容
System.out.println("Received response: " + response.getBody());
return response;
}
}
然后，在@HttpApi注解中指定这个自定义代理：
@HttpApi(url = "http://localhost:7001/test", proxy = CustomHttpProxy.class)
public interface TestHttpApi {
// ... 接口方法
}
2. 配置全局请求参数
有时，你可能需要在所有请求中都包含某些全局参数，例如API密钥或用户令牌。这可以通过实现GlobalRequestParamProvider接口来实现。
@Component
public class GlobalRequestParamProviderImpl implements GlobalRequestParamProvider {
@Override
public Map<String, Object> provideParams() {
Map<String, Object> params = new HashMap<>();
params.put("apiKey", "your-api-key");
return params;
}
}
UniHttp会自动将这个全局参数添加到所有HTTP请求中。
3. 自定义错误处理
UniHttp允许你通过实现HttpErrorHandler接口来自定义错误处理逻辑。这包括处理HTTP状态码错误和请求/响应解析错误。
@Component
public class CustomHttpErrorHandler implements HttpErrorHandler {
@Override
public void handleError(HttpRequestWrapper requestWrapper, Throwable throwable) {
// 自定义错误处理逻辑，例如记录日志或抛出异常
System.err.println("Error occurred: " + throwable.getMessage());
}
}
4. 配置连接池和超时
UniHttp使用Apache HttpClient作为底层的HTTP客户端库，因此你可以通过配置Apache HttpClient的HttpClientBuilder来自定义连接池和超时设置。
@Bean
public CloseableHttpClient httpClient() {
HttpClientBuilder builder = HttpClients.custom();
// 配置连接池和超时
builder.setMaxConnTotal(100);
builder.setDefaultRequestConfig(RequestConfig.custom()
.setConnectTimeout(5000)
.setSocketTimeout(5000)
.build());
// ... 其他配置
return builder.build();
}
然后，在UniHttp的配置类中指定这个CloseableHttpClient实例：
@Configuration
public class UniHttpConfig {
@Autowired
private CloseableHttpClient httpClient;
@Bean
public UniHttpConfigurer uniHttpConfigurer() {
return new UniHttpConfigurer() {
@Override
public void configure(UniHttpProperties properties) {
properties.setHttpClient(httpClient);
// 其他配置
}
};
}
}
六、总结
UniHttp是一个强大的HTTP接口对接框架，它提供了声明式的接口定义方式、丰富的注解支持、自定义代理逻辑、全局请求参数、自定义错误处理和连接池/超时配置等高级功能。通过UniHttp，开发者可以快速地对接和使用第三方HTTP接口，同时保持代码的高内聚和可读性。无论是简单的GET/POST请求还是复杂的自定义请求处理，UniHttp都能提供灵活且强大的支持。
