Ubuntu 22.04 安装 Apache HttpComponents 指南

目标:Apache HttpComponents 是 Java 侧低层 HTTP 组件库,并非可独立启动的守护进程,因此本文以「集成/环境搭建」形态呈现——从零安装 JDK 11 与 Maven 3.6.3,用 Maven 引入 HttpClient 4.5.14 与 HttpClient 5.4.1 依赖,真实编译并运行一个调用 httpbin.org 与本地 HTTP 服务的 Java 示例,采集真实回显。已在 Ubuntu 22.04.5 LTS(x86_64)实测通过。

一、环境信息

操作系统:Ubuntu 22.04.5 LTS,Kernel 6.8.0-138-generic,架构 x86_64(amd64)
OpenJDK 11:11.0.32.1(示例运行默认 JDK)
OpenJDK 17:17.0.20.1(环境同时安装,可选切换)
Apache Maven 3.6.3(Maven home:/usr/share/maven)
Python 3.10.12(用于本地 http.server 回显,非 HttpComponents 依赖)
目标库版本:HttpClient 4.5.14、HttpCore 4.4.16;HttpClient 5.4.1、HttpCore 5.3.1
示例工作目录:/opt/hc4(HttpClient 4.x)、/opt/hc5(HttpClient 5.x)
公网回显服务:httpbin.org(真实返回 JSON);本地回显:Python http.server(端口 18080)

二、前置条件

已具备 root 或 sudo 权限,可执行 apt-get install、wget。
服务器可联网访问 Maven 中央仓库(本文实测使用阿里云 Maven 镜像 https://maven.aliyun.com/repository/central,见第五节)。
服务器可访问 httpbin.org 用于回显验证;内网隔离环境可改用本地 HTTP 服务(本文第六节给出)。

三、版本选型说明

HttpComponents 家族分为三大构件,均以 jar 形式提供(库,无独立进程):

构件	Maven 坐标(groupId : artifactId)	本次实测版本	说明
HttpClient 4.x	org.apache.httpcomponents : httpclient	4.5.14	经典同步客户端,依赖 HttpCore 4.x
HttpCore 4.x	org.apache.httpcomponents : httpcore	4.4.16	HttpClient 4.x 的底层传输与消息层
HttpClient 5.x	org.apache.httpcomponents.client5 : httpclient5	5.4.1	新一代客户端,支持经典(Classic)与异步(Async)接口
HttpCore 5.x	org.apache.httpcomponents.core5 : httpcore5	5.3.1	HttpClient 5.x 的底层核心

选型建议:

新项目优先选择 HttpClient 5.x(5.4.1):API 更现代,分离同步/异步,连接管理与配置更规范,HttpCore5 重构了超时/连接管理模型。
老项目或依赖较旧的第三方库(如旧版 Spring 生态)常用 HttpClient 4.5.x:生态成熟、资料多、迁移成本低,当前最新为 4.5.14。
两者 Maven 坐标互不冲突,可在同一工程中按需混用,但同一逻辑建议只依赖一个大版本。

依赖解析(实测,mvn dependency:resolve 输出):

[INFO] org.apache.httpcomponents:httpclient:jar:4.5.14:compile
[INFO] org.apache.httpcomponents:httpcore:jar:4.4.16:compile

[INFO] org.apache.httpcomponents.client5:httpclient5:jar:5.4.1:compile
[INFO] org.apache.httpcomponents.core5:httpcore5:jar:5.3.1:compile

四、部署步骤(集成与编译运行)

4.1 安装 JDK 11

HttpClient 4.5.x 与 5.x 最低要求 Java 8,推荐 Java 11/17。本文以 JDK 11 为示例运行环境,通过 apt 安装:

apt-get update -y
apt-get install -y openjdk-11-jdk

验证安装:

java -version

真实回显:

openjdk version "11.0.32.1" 2025-07-15
OpenJDK Runtime Environment (build 11.0.32.1+1-post-Ubuntu-0ubuntu122.04)
OpenJDK 64-Bit Server VM (build 11.0.32.1+1-post-Ubuntu-0ubuntu122.04, mixed mode, sharing)

确认 JDK 目录:

ls /usr/lib/jvm/

真实回显:

default-java  java-1.11.0-openjdk-amd64  java-1.17.0-openjdk-amd64  java-11-openjdk-amd64  java-17-openjdk-amd64

4.2 安装 Maven

apt-get install -y maven

验证版本:

mvn -version

真实回显:

Apache Maven 3.6.3
Maven home: /usr/share/maven
Java version: 17.0.20.1, vendor: Ubuntu, runtime: /usr/lib/jvm/java-17-openjdk-amd64
Default locale: en_US, platform encoding: ANSI_X3.4-1968
OS name: "linux", version: "6.8.0-138-generic", arch: "amd64", family: "unix"

4.3 配置 Maven 本地化设置(镜像加速)

下载依赖耗时明显时,可配置阿里云中央仓库镜像以加速(实测节点即走该镜像):

mkdir -p /root/.m2

在 /root/.m2/settings.xml 中写入镜像配置:

<settings>
  <mirrors>
    <mirror>
      <id>aliyun</id>
      <mirrorOf>central</mirrorOf>
      <name>Aliyun Maven Central Mirror</name>
      <url>https://maven.aliyun.com/repository/central</url>
    </mirror>
  </mirrors>
</settings>

4.4 创建 HttpClient 4.x 工程并引入依赖

建立目录结构:

mkdir -p /opt/hc4/src/main/java/com/example

创建工程描述文件 /opt/hc4/pom.xml,引入 httpclient:4.5.14 依赖,并使用 maven-shade-plugin 将依赖打进可执行 fat-jar:

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>hc4-demo</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>
  <properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.apache.httpcomponents</groupId>
      <artifactId>httpclient</artifactId>
      <version>4.5.14</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>3.5.2</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals><goal>shade</goal></goals>
            <configuration>
              <transformers>
                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                  <mainClass>com.example.HttpClient4Demo</mainClass>
                </transformer>
              </transformers>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

编写主类 /opt/hc4/src/main/java/com/example/HttpClient4Demo.java(实现 HttpGet/HttpPost、连接池、RequestConfig 超时、连接释放,完整源码见同专栏《Apache HttpComponents 常用 API 与示例详解》)。

4.5 解析依赖(验证真实版本)

cd /opt/hc4
JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 mvn dependency:resolve -DincludeArtifactIds=httpclient,httpcore

真实回显:

[INFO] The following files have been resolved:
[INFO]    org.apache.httpcomponents:httpclient:jar:4.5.14:compile -- module org.apache.httpcomponents.httpclient [auto]
[INFO]    org.apache.httpcomponents:httpcore:jar:4.4.16:compile -- module org.apache.httpcomponents.httpcore [auto]
[INFO] BUILD SUCCESS

4.6 编译打包

cd /opt/hc4
JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 mvn package

真实回显(关键行):

[INFO] Building jar: /opt/hc4/target/hc4-demo-1.0.0.jar
[INFO] --- maven-shade-plugin:3.5.2:shade (default) @ hc4-demo ---
[INFO] Including org.apache.httpcomponents:httpclient:jar:4.5.14 in the shaded jar.
[INFO] Including org.apache.httpcomponents:httpcore:jar:4.4.16 in the shaded jar.
[INFO] Including commons-logging:commons-logging:jar:1.2 in the shaded jar.
[INFO] Including commons-codec:commons-codec:jar:1.11 in the shaded jar.
[INFO] Replacing /opt/hc4/target/hc4-demo-1.0.0.jar with /opt/hc4/target/hc4-demo-1.0.0-shaded.jar
[INFO] BUILD SUCCESS

4.7 运行示例并验证(公网 httpbin.org 回显)

HttpClient 4.x 示例请求 httpbin.org 的 GET/POST,采集真实回显:

cd /opt/hc4
JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 /usr/lib/jvm/java-11-openjdk-amd64/bin/java \
  -Xms256m -Xmx256m -Xmn128m -Dfile.encoding=UTF-8 -jar target/hc4-demo-1.0.0.jar

真实回显:

[HttpGet] URL=http://httpbin.org/get?name=hc4&version=4.5.14
[HttpGet] 状态码=200 协议=HTTP/1.1 原因=OK
[HttpGet] Content-Type=Content-Type: application/json
[HttpGet] 响应体:
{
  "args": {
    "name": "hc4",
    "version": "4.5.14"
  },
  "headers": {
    "Accept": "application/json",
    "Accept-Encoding": "gzip,deflate",
    "Host": "httpbin.org",
    "User-Agent": "Apache-HttpClient/4.5.14 (Java/11.0.32.1)",
    "X-Amzn-Trace-Id": "Root=1-6acb2191-1f8a167e01dee2e418a4d463"
  },
  "origin": "42.63.89.89",
  "url": "http://httpbin.org/get?name=hc4&version=4.5.14"
}

[HttpPost] 状态码=200
[HttpPost] 响应体(form 提交回显):
{
  "args": {},
  "data": "",
  "files": {},
  "form": {
    "method": "POST",
    "name": "hc4"
  },
  "headers": {
    "Accept-Encoding": "gzip,deflate",
    "Content-Length": "20",
    "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
    "Host": "httpbin.org",
    "User-Agent": "Apache-HttpClient/4.5.14 (Java/11.0.32.1)",
    "X-Amzn-Trace-Id": "Root=1-6acb2191-2ef096882c1263de5ff49a8a"
  },
  "json": null,
  "origin": "42.63.89.89",
  "url": "http://httpbin.org/post"
}

连接池统计: MaxTotal=50 已分配=0 可用=1 待释放=0

💡 说明:回显中的 User-Agent 为 Apache-HttpClient/4.5.14 (Java/11.0.32.1),origin 为本次请求出口公网 IP,两项均以实际环境为准。

4.8 创建 HttpClient 5.x 工程并引入依赖

建立目录:

mkdir -p /opt/hc5/src/main/java/com/example

创建 /opt/hc5/pom.xml,引入 org.apache.httpcomponents.client5:httpclient5:5.4.1 与 org.slf4j:slf4j-simple:1.7.36(HttpClient5 通过 SLF4J 记录日志):

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>com.example</groupId>
  <artifactId>hc5-demo</artifactId>
  <version>1.0.0</version>
  <packaging>jar</packaging>
  <properties>
    <maven.compiler.source>11</maven.compiler.source>
    <maven.compiler.target>11</maven.compiler.target>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  </properties>
  <dependencies>
    <dependency>
      <groupId>org.apache.httpcomponents.client5</groupId>
      <artifactId>httpclient5</artifactId>
      <version>5.4.1</version>
    </dependency>
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-simple</artifactId>
      <version>1.7.36</version>
    </dependency>
  </dependencies>
  <build>
    <plugins>
      <plugin>
        <groupId>org.apache.maven.plugins</groupId>
        <artifactId>maven-shade-plugin</artifactId>
        <version>3.5.2</version>
        <executions>
          <execution>
            <phase>package</phase>
            <goals><goal>shade</goal></goals>
            <configuration>
              <transformers>
                <transformer implementation="org.apache.maven.plugins.shade.resource.ManifestResourceTransformer">
                  <mainClass>com.example.HttpClient5Demo</mainClass>
                </transformer>
              </transformers>
            </configuration>
          </execution>
        </executions>
      </plugin>
    </plugins>
  </build>
</project>

4.9 解析并打包 HttpClient 5.x

cd /opt/hc5
JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 mvn dependency:resolve -DincludeArtifactIds=httpclient5,httpcore5

真实回显:

[INFO] The following files have been resolved:
[INFO]    org.apache.httpcomponents.client5:httpclient5:jar:5.4.1:compile
[INFO]    org.apache.httpcomponents.core5:httpcore5:jar:5.3.1:compile
[INFO] BUILD SUCCESS

打包:

cd /opt/hc5
JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 mvn package

真实回显(关键行):

[INFO] Building jar: /opt/hc5/target/hc5-demo-1.0.0.jar
[INFO] Replacing /opt/hc5/target/hc5-demo-1.0.0.jar with /opt/hc5/target/hc5-demo-1.0.0-shaded.jar
[INFO] BUILD SUCCESS

4.10 运行 HttpClient 5.x 示例并验证

cd /opt/hc5
JAVA_HOME=/usr/lib/jvm/java-11-openjdk-amd64 /usr/lib/jvm/java-11-openjdk-amd64/bin/java \
  -Xms256m -Xmx256m -Xmn128m -Dfile.encoding=UTF-8 -jar target/hc5-demo-1.0.0.jar

真实回显:

[HttpGet] URL=https://httpbin.org/get?name=hc5&version=5.4.1
[HttpGet] 状态码=200
[HttpGet] Content-Type=Content-Type: application/json
[HttpGet] 响应体:
{
  "args": {
    "name": "hc5",
    "version": "5.4.1"
  },
  "headers": {
    "Accept": "application/json",
    "Accept-Encoding": "gzip, x-gzip, deflate",
    "Host": "httpbin.org",
    "User-Agent": "Apache-HttpClient/5.4.1 (Java/11.0.32.1)",
    "X-Amzn-Trace-Id": "Root=1-6acb21b6-549e5159059c5050082137e5"
  },
  "origin": "42.63.89.89",
  "url": "https://httpbin.org/get?name=hc5&version=5.4.1"
}

[HttpPost] 状态码=200
[HttpPost] 响应体:
{
  "args": {},
  "data": "",
  "files": {},
  "form": {
    "method": "POST",
    "tool": "httpclient5"
  },
  "headers": {
    "Accept-Encoding": "gzip, x-gzip, deflate",
    "Content-Length": "28",
    "Content-Type": "application/x-www-form-urlencoded; charset=UTF-8",
    "Host": "httpbin.org",
    "User-Agent": "Apache-HttpClient/5.4.1 (Java/11.0.32.1)",
    "X-Amzn-Trace-Id": "Root=1-6acb21b6-058e71a902916b616b14ed9d"
  },
  "json": null,
  "origin": "42.63.89.89",
  "url": "https://httpbin.org/post"
}

连接池: MaxTotal=50 已分配Leased=0 可用Available=1

4.11 切换 JDK 版本

环境同时装了 JDK 11 与 JDK 17。构建或运行时通过 JAVA_HOME 显式指定:

# 用 JDK 17 构建
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 mvn package

# 用 JDK 17 运行
JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64 /usr/lib/jvm/java-17-openjdk-amd64/bin/java -jar /opt/hc4/target/hc4-demo-1.0.0.jar

💡 说明:HttpClient 4.5.x 与 5.x 在 JDK 11 与 17 下均可编译运行;示例回显中的 User-Agent 会随运行 JDK 变化(如 Java/17.0.20.1)。

五、配置说明

依赖配置(pom.xml):HttpClient 4.x 用 org.apache.httpcomponents:httpclient,HttpClient 5.x 用 org.apache.httpcomponents.client5:httpclient5,在 <dependencies> 中声明坐标与版本即可,Maven 自动拉取传递依赖。
构建配置:maven-shade-plugin 用于打可执行 fat-jar;发布到应用服务器时也可用普通 jar + 外部依赖目录(classpath)方式。
镜像加速:见 4.3,配置 /root/.m2/settings.xml 指向阿里云中央仓库镜像可显著加快依赖下载。
编译级别:maven.compiler.source/target=11,如需在更高 JDK 构建可调到 17。
JVM 参数:演示示例以 -Xms256m -Xmx256m -Xmn128m 运行,限制堆内存,避免占用过大(HttpComponents 本身为无守护进程的库,内存由宿主 Java 进程承载)。

⚠️ 注意:HttpComponents 不是守护进程,没有 systemd 服务、没有监听端口、没有数据目录。"安装"即"在工程中引入依赖并用 Maven 编译",编译产物为 jar,交由上层应用进程加载。

六、注意事项

连接释放:响应对象使用后必须在 finally 中 close(),否则连接不能被归还连接池,长期会造成连接泄漏。
超时配置:生产环境务必设置连接超时与读取超时(详见《Apache HttpComponents 配置参数详解》),避免线程无限阻塞。
TLS:访问 https 服务(如 https://httpbin.org)时需 JSSE 支持,JDK 缺省自带;企业内网证书需通过连接管理器配置 SSLContext。
编码:涉及中文与 JSON 时应显式指定 UTF-8 并设置 -Dfile.encoding=UTF-8,否则可能乱码。

七、常见问题

Q1:Maven 下载依赖极慢或失败

配置镜像加速(见 4.3),并确认服务器能访问 maven.aliyun.com。错误如 Could not resolve dependencies 时,先 mvn -U dependency:resolve 强制刷新。

Q2:运行报 java.lang.NoClassDefFoundError

说明 classpath 中缺少依赖。使用打好的 fat-jar(mvn package 由 shade 插件合并依赖)即可避免;若是手动 classpath,必须把 httpclient/httpcore(及 HttpClient4 的 commons-logging、commons-codec)全部加入。

Q3:访问 https 报 SSL 握手失败

多为自签名/内网证书。通过配置 SSLContext(信任自定义证书)解决;公网标准证书则无需处理。

Q4:控制台中文乱码

运行命令加 -Dfile.encoding=UTF-8,并在代码中对响应正文用 StandardCharsets.UTF_8 读取。

八、卸载方式

HttpComponents 为依赖库,卸载即从工程的 pom.xml 删除对应 <dependency>,并清理本地 Maven 仓库缓存:

# 清理 HttpClient4 相关本地缓存
rm -rf /root/.m2/repository/org/apache/httpcomponents/httpclient
rm -rf /root/.m2/repository/org/apache/httpcomponents/httpcore

# 清理 HttpClient5 相关本地缓存
rm -rf /root/.m2/repository/org/apache/httpcomponents/client5/httpclient5
rm -rf /root/.m2/repository/org/apache/httpcomponents/core5/httpcore5

如不再需要 JDK/Maven 环境:

apt-get remove -y openjdk-11-jdk maven

如需删除示例工程目录:

rm -rf /opt/hc4 /opt/hc5

九、参考链接

Apache HttpComponents 官网:https://hc.apache.org/
HttpClient 4.5.x 快速入门:https://hc.apache.org/httpcomponents-client-4.5.x/quickstart.html
HttpClient 5.x 官方指南:https://hc.apache.org/httpcomponents-client-5.4.x/
阿里云 Maven 镜像:https://developer.aliyun.com/mirror/maven
httpbin 回显服务:https://httpbin.org/