HttpUtils

HttpUtils 封装了 OkHttp 的请求构造与响应读取。项目需要提供 OkHttp 及客户端池使用的 Brotli 支持依赖，由项目统一管理依赖配置。

客户端池与 HTTPS

OkHttpClientPool 复用连接池，提供不同连接及读取超时的客户端：

方法	连接和读取超时
getHttpClient	30 秒
get60HttpClient	60 秒
get120HttpClient	120 秒
get300HttpClient	300 秒
get600HttpClient	600 秒
get1000HttpClient	1000 秒
get1200HttpClient	1200 秒
get3600HttpClient	3600 秒

这些超时不是整个调用的总时限。需要限制整个调用时，可以从客户端创建 builder 并配置 callTimeout。

所有预置客户端使用默认的证书链与主机名校验。x509TrustManager() 返回基于 JVM 信任库的校验器，sslSocketFactory() 使用同样的信任策略。内部 CA 或自签证书需要加入应用信任库；也可以为专用客户端配置独立信任库。

代理配置通过 EnvUtils 读取 http.proxyHost 和 http.proxyPort，应在首次使用客户端池之前完成配置。

import java.util.concurrent.TimeUnit;
import nexus.io.tio.utils.http.OkHttpClientPool;
import okhttp3.OkHttpClient;

public class HttpClientExample {
  public OkHttpClient client() {
    return OkHttpClientPool.getHttpClient().newBuilder()
        .callTimeout(45, TimeUnit.SECONDS)
        .build();
  }
}

读取响应结果

返回 ResponseVo 的便捷方法会读取响应体并关闭响应资源；返回原始 Response 的方法由调用方关闭。

get(url, token) 使用 Bearer Token，其 isOk() 与 HTTP 状态对应：2xx 为 true，401、500 等非 2xx 为 false。该方法保留状态码、响应头和响应体；网络或 TLS 异常通过运行时异常向外传播，不会转换成正常 HTTP 响应。

import nexus.io.model.http.response.ResponseVo;
import nexus.io.tio.utils.http.HttpUtils;

public class RemoteDataExample {
  public ResponseVo request(String url, String token) {
    ResponseVo response = HttpUtils.get(url, token);
    if (!response.isOk()) {
      return response; // 调用方可继续检查状态码、响应头和错误响应体。
    }
    return response;
  }
}

方法	结果与资源归属
get(url)、get(url, token)	返回已读取的 ResponseVo
call(request)、call(client, request)、call(call)	返回已读取的 ResponseVo
postJson、postText、upload、download	返回已读取的 ResponseVo
get(url, headers)、post 的原始响应重载、execute(request)	返回 Response，由调用方关闭
newCal(request)	返回尚未执行的 Call，由调用方执行或取消

原始响应示例：

import java.util.Collections;
import nexus.io.tio.utils.http.HttpUtils;
import okhttp3.Response;

public class RawResponseExample {
  public int status(String url) throws Exception {
    try (Response response = HttpUtils.get(url, Collections.singletonMap("Accept", "application/json"))) {
      return response.code();
    }
  }
}

请求体与文件上传

post(url, headers, bodyString) 在 bodyString 非 null 时原样发送字符串，包括空串和纯空白，默认内容类型是 JSON。该方法不会校验内容是不是合法 JSON。使用表单重载时会构建表单请求；bodyString 为 null 时沿用表单分支。

upload(url, file) 使用 multipart 表单，字段名为 file，文件部分的 Content-Type 根据文件名扩展名确定，例如 photo.PNG 对应 image/png，未知扩展名使用 application/octet-stream。

ContentTypeUtils

ContentTypeUtils.getContentType 接收扩展名，可带前导点，忽略大小写和两侧空白，结果不依赖系统语言区域。该方法的参数是扩展名，不是完整文件名。

import nexus.io.tio.utils.http.ContentTypeUtils;

public class MediaTypeExample {
  public String pngType() {
    return ContentTypeUtils.getContentType(".PNG");
  }
}