# httpclient

**Repository Path**: gzcltech/httpclient

## Basic Information

- **Project Name**: httpclient
- **Description**: No description available
- **Primary Language**: Java
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-25
- **Last Updated**: 2026-07-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# httpclient

基于 [OkHttp](https://square.github.io/okhttp/) 的通用 HTTP 客户端封装，支持连接池 / 超时 / Dispatcher、拦截器、Fluent API、同步与 `CompletableFuture` 异步，以及 Spring Boot 下基于 spring-retry 的可配置重试。

| 模块 | 说明 |
|------|------|
| `httpclient-okhttp` | 纯 Java 核心，无 Spring 依赖 |
| `httpclient-okhttp-spring-boot-starter` | 自动配置、`httpclient.okhttp.*` Properties、spring-retry |
| `example-httpclient-okhttp` | 用法示例（不发布到仓库） |

当前版本：`4.0.0`（父 POM 中 `${revision}`）。技术栈：Java 25、OkHttp 5.4、Spring Boot 4。

## Maven 依赖

### 纯 Java（核心）

```xml
<dependency>
  <groupId>io.gitee.gzcltech.httpclient</groupId>
  <artifactId>httpclient-okhttp</artifactId>
  <version>4.0.0</version>
</dependency>
```

JSON 编解码可选引入 Jackson（与 Boot BOM 对齐即可）：

```xml
<dependency>
  <groupId>tools.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
</dependency>
```

### Spring Boot Starter

```xml
<dependency>
  <groupId>io.gitee.gzcltech.httpclient</groupId>
  <artifactId>httpclient-okhttp-spring-boot-starter</artifactId>
  <version>4.0.0</version>
</dependency>
```

多模块工程也可使用父 POM 的 `${revision}` / dependencyManagement，无需手写版本号。

## 纯 Java 用法（Builder）

```java
import io.gitee.gzcltech.httpclient.okhttp.OkHttpHttpClient;
import io.gitee.gzcltech.httpclient.okhttp.OkHttpHttpClientBuilder;
import java.time.Duration;

OkHttpHttpClient client = new OkHttpHttpClientBuilder()
    .connectTimeout(Duration.ofSeconds(5))
    .readTimeout(Duration.ofSeconds(30))
    .connectionPool(16, Duration.ofMinutes(5))
    .dispatcher(64, 5)
    .build();

String body = client.request()
    .get("https://httpbin.org/get")
    .queryParam("foo", "bar")
    .header("X-Demo", "1")
    .execute(String.class);

client.close();
```

也可复用已有 `OkHttpClient`，或通过 `okHttpClientCustomizer` / `addInterceptor` 做二次定制。

## Spring Boot 用法

### application.yml

```yaml
httpclient:
  okhttp:
    clients:
      payment:
        enabled: true
        base-url: https://payment.example.com
        read-timeout: 5s
        interceptors:
          - paymentInterceptor
        customizer: paymentCustomizer
        converter: paymentConverter
        connection-pool:
          max-idle: 8
        retry:
          enabled: true
          max-attempts: 3
          retry-on-status: [429, 502, 503, 504]
      user-service:
        read-timeout: 60s
```

### 多客户端

在 `httpclient.okhttp.clients` 下配置命名客户端；未显式设置的项使用 `ClientCO` 内置默认值。通过 `OkHttpHttpClientRegistry` 获取客户端：

```java
import io.gitee.gzcltech.httpclient.okhttp.OkHttpHttpClient;
import io.gitee.gzcltech.httpclient.okhttp.OkHttpHttpClientRegistry;
import org.springframework.stereotype.Service;

@Service
public class PaymentService {

    private final OkHttpHttpClient paymentClient;

    public PaymentService(OkHttpHttpClientRegistry registry) {
        this.paymentClient = registry.getRequired("payment");
    }
}
```

### 客户端扩展组件

每个客户端可单独指定多个 `Interceptor`、`OkHttpClientCustomizer`、`HttpConverter` Bean 名称，启动时从 Spring 容器解析：

```java
import io.gitee.gzcltech.httpclient.okhttp.OkHttpClientCustomizer;
import io.gitee.gzcltech.httpclient.okhttp.converter.HttpConverter;
import io.gitee.gzcltech.httpclient.okhttp.converter.StringHttpConverter;
import okhttp3.Interceptor;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

@Configuration
public class HttpClientExtensions {

    @Bean
    Interceptor paymentInterceptor() {
        return chain -> chain.proceed(
            chain.request().newBuilder().header("X-Service", "payment").build());
    }

    @Bean
    OkHttpClientCustomizer paymentCustomizer() {
        return builder -> builder.followRedirects(false);
    }

    @Bean
    HttpConverter paymentConverter() {
        return new StringHttpConverter();
    }
}
```

未配置 `converter` 时，默认注册 `StringHttpConverter`、`ByteArrayHttpConverter`，classpath 存在 Jackson 时额外注册 `JacksonHttpConverter`。

### 注入使用

引入 starter 后会注册 `OkHttpHttpClientRegistry` Bean，通过它按名称获取客户端：

```java
import io.gitee.gzcltech.httpclient.okhttp.OkHttpHttpClient;
import io.gitee.gzcltech.httpclient.okhttp.OkHttpHttpClientRegistry;
import org.springframework.stereotype.Service;

@Service
public class DemoService {

    private final OkHttpHttpClient httpClient;

    public DemoService(OkHttpHttpClientRegistry registry) {
        this.httpClient = registry.getRequired("payment");
    }

    public String fetch() {
        return httpClient.request()
            .get("/orders")
            .execute(String.class);
    }
}
```

可通过 `OkHttpClientCustomizer`、`Interceptor`、自定义 `HttpConverter` 等 Bean 扩展自动配置。

## 示例与设计文档

- 可运行示例：[`example-httpclient-okhttp`](example-httpclient-okhttp/)（`DemoRunner` 演示同步 / 异步 GET）
- 设计说明：[`docs/superpowers/specs/2026-07-25-okhttp-httpclient-design.md`](docs/superpowers/specs/2026-07-25-okhttp-httpclient-design.md)
- 实现计划：[`docs/superpowers/plans/2026-07-25-okhttp-httpclient.md`](docs/superpowers/plans/2026-07-25-okhttp-httpclient.md)

英文简介见 [README.en.md](README.en.md)。

## 构建与测试

## 本地发布
```text
./mvnw clean install -Plocal
```

## 上传到中央仓库
```text
./mvnw clean deploy -Prelease -Ppush-central -DskipTests
```

## 上传到阿里云私库
```text
./mvnw clean deploy -Prelease -Ppush-rdc -DskipTests
./mvnw clean deploy -Psnapshot -Ppush-rdc -DskipTests
```

若 Spotless 检查失败，先执行 `./mvnw spotless:apply` 再重测。

## 参与贡献

1. Fork 本仓库
2. 新建功能分支
3. 提交代码
4. 发起 Pull Request

## License

Apache License, Version 2.0