简介本资源是面向Android初、中级开发者的网络编程示例工程演示如何基于Apache开源项目HttpClient访问Web站点核心在于区分并使用DefaultHttpClient与AndroidHttpClient两个子实现类完成网络请求。压缩包共51个文件以Java源码、class字节码、AndroidManifest与布局等XML配置、多分辨率PNG图标为主同时附带JAR库、APK成品与Eclipse工程配置便于直接导入查看、对照运行与二次改造。资源包整体约1.18MB结构紧凑适合学习Android网络通信基础、理解HttpClient使用差异及客户端访问Web服务的编码要点。目前已有410人学习下载。通过该工程可掌握两种客户端的创建与请求方法查看从源码、资源到构建文件的完整项目组织还可直接安装APK观察实际效果为后续改用HttpURLConnection或OkHttp打下基础。1. 在OkHttp时代选Apache HttpClient微Web站点交互的兼容性现实做Android开发这几年我越来越意识到一个反直觉的结论在OkHttp几乎一统天下的今天Apache HttpClient不但没死反而在特定场景下活得相当滋润。某次给一个工控项目做配套App设备端是一个运行在嵌入式系统上的微Web站点请求量不大但极其挑剔——它只认HTTP/1.0的握手方式对TLS版本敏感OkHttp默认的协议策略直接导致握手失败。折腾了两天之后换回Apache HttpClient 4.2.x问题一秒钟消失。那之后我养成了一个习惯凡是Android要访问微Web站点、老式内网设备或定制固件上的轻量服务第一反应不再是“上OkHttp”而是先确认服务端到底认哪个协议栈。这篇笔记就是围绕这个场景展开的讲清楚版本选型、核心参数、踩坑记录和封装思路。2. 版本选型与依赖配置HttpClient 4.2.5与4.5.6该怎么挑2.1 两个大版本的差异API风格、连接池行为与TLS支持Apache HttpClient在Android上的可用版本大致分成两个阵营4.2.x系列和4.4.x/4.5.x系列。注意Android SDK里曾经内置过一份HttpClient但那个版本停留在4.0API老旧且官方早已不维护属于能用但别深究的范畴。我自己的经验是如果项目minSdk低于21且目标设备是那种几年不升级的工控机、扫码枪、定制PDA优先考虑4.2.5如果minSdk在21以上且服务端支持标准HTTP/1.1可以考虑4.5.x。两代版本的差异不只是命名空间从org.apache.http换成了org.apache.http.impl.client而是底层的连接管理逻辑完全重写了。4.2.x的ConnectionPool是PerRoute连接池的雏形行为相对静态线程安全程度尚可但不适合高并发。4.5.x引入了PoolingHttpClientConnectionManager支持最大连接数、每路由最大连接数、连接空闲回收时间等精细控制并且通过HttpClientBuilder可以链式配置代码可读性高出一截。以我对微Web站点的理解这类站点通常部署在低功耗设备上并发承载能力弱一个App同时发起超过5个连接就可能把服务端打挂。所以连接池参数的设置逻辑不是“开得越大越好”而是要限制并发、尽量复用连接。4.2.x默认每个路由只有2个连接这个限制在访问微Web站点时反而成了保护机制4.5.x默认最大连接数是20如果你不做任何配置直接怼上去设备端的压力会明显增加。版本选择还需要看Gradle依赖写法。4.2.5的坐标长这样implementation org.apache.httpcomponents:httpclient:4.2.5 implementation org.apache.httpcomponents:httpcore:4.2.5这个版本以来古老Gradle同步时通常不会冲突但它不内置任何TLS 1.2代码。如果服务端要求HTTPS且只支持TLS 1.24.2.5会直接抛SSLException。常见的过渡方案是引入conscrypt或自行扩展SSLSocketFactory但每多一个依赖排查问题时就多一个黑匣子。我一般会直接用4.5.6它在Android上有官方推荐的兼容配置且API风格更现代implementation org.apache.httpcomponents:httpclient:4.5.6这个版本配合Android的编译选项可以正常工作但有一个必须处理的坑Android系统本身已经内置了一份org.apache.http如果Gradle里直接添加依赖编译期可能因为重复类而报错。解决办法是在android节点里加packagingOptions排除后面会详细写。2.2 依赖冲突处理packagingOptions与编译选项Android项目引入Apache HttpClient时最常见的报错是“Duplicate class org.apache.http.*** found in modules”。这个现象的本质是Android系统框架里捆绑了一份HttpClient类库你的Gradle依赖又引入了一份两者在打包时撞车。4.2.5时代系统内置库和外部库的包名完全一致几乎必然冲突用4.5.x也无法完全避免因为META-INF和部分核心类仍然重名。解决方案在build.gradle里做两层处理。第一层是Packaging排除android { packagingOptions { exclude META-INF/DEPENDENCIES exclude META-INF/LICENSE exclude META-INF/LICENSE.txt exclude META-INF/NOTICE exclude META-INF/NOTICE.txt } }这些META-INF文件是Apache项目发布时的标准标配Android打包器会把它们当作重复资源拦截做了排除之后类冲突问题基本消失。第二层是useLibrary针对Android 9API 28及以上的系统HttpClient被标记为deprecated且默认不出现在boot classpath里需要在android节点声明android { useLibrary org.apache.http.legacy }这句声明的作用是告诉编译器虽然系统不再默认提供HttpClient但我们允许该应用链接系统内置的legacy库。这个选项加上之后即使你完全不引入外部HttpClient依赖也可以用Android系统内置的4.0版本。但我要明确一点别用内置版本我踩过坑它的连接池实现有内存泄漏问题长时间运行后会导致Socket资源无法释放。2.3 不同Gradle版本的兼容性细节如果你的项目用的是Gradle 3.x老版本implementation指令不支持需要换成compile。代码本身没有区别但依赖管理的行为有差异compile是懒加载implementation是严格隔离。HttpClient在编译期被多个模块引用时用compile反而省事不会出现“运行时找不到类”的诡异问题。我还遇到过一种情况部分厂商的Android SDK比如某些定制系统的开发包自己捆绑了一份旧版HttpClient你即使不在build.gradle里添加依赖编译也能通过但运行时会报NoSuchMethodError。这个问题的排查思路是先看libs目录和依赖树的输出确认到底哪一层引入了HttpClient。用Gradle的依赖报告命令最直接./gradlew :app:dependencies --configuration releaseRuntimeClasspath执行后搜索httpclient你会看到完整依赖链。常见的情况是某个第三方SDK传递依赖了HttpClient 4.3.x和你自己引入的4.5.x发生方法签名冲突。解决思路是全局排除传递依赖然后统一指定版本。这段命令只是定位手段真正的解法是在引入SDK的dependency里加exclude我习惯统一写成一个数组避免每个模块重复处理。3. 从Get到Post核心请求类、超时与连接池参数落地3.1 HttpGet与HttpGet的请求搭建与Header设置Apache HttpClient的请求构建方式很直观先创建HttpClient实例再构造HttpGet或HttpPost对象然后执行。我刚接触时总觉得它啰嗦后来发现这种显式构建在调试时反而方便每个环节都能打印状态。下面是一个访问微Web站点的基础GET请求代码CloseableHttpClient httpClient HttpClients.custom() .setConnectionManager(connManager) .setDefaultRequestConfig(requestConfig) .build(); HttpGet getRequest new HttpGet(http://192.168.1.100/status); getRequest.setHeader(Accept, application/json); getRequest.setHeader(Connection, close); try (CloseableHttpResponse response httpClient.execute(getRequest)) { int statusCode response.getStatusLine().getStatusCode(); String body EntityUtils.toString(response.getEntity(), UTF-8); Log.d(HTTP, status statusCode body body); } catch (IOException e) { Log.e(HTTP, request failed, e); }这里有几个参数值得说。setHeader(Connection, close)是针对微Web站点的一个常用设置很多嵌入式设备的HTTP服务端对keep-alive支持不完整客户端复用连接反而会导致服务端Socket状态错乱。如果你确认服务端支持Keep-Alive可以去掉这个Header不确定时带上它更稳妥。EntityUtils.toString的第二个参数指定字符集微Web站点经常不按规范返回charset强制用UTF-8解析要比自动探测可靠得多。POST请求的构造逻辑同样直白关键是设置实体。常见做法是UrlEncodedFormEntity配合BasicNameValuePairListNameValuePair params new ArrayList(); params.add(new BasicNameValuePair(cmd, reboot)); params.add(new BasicNameValuePair(token, authToken)); HttpPost postRequest new HttpPost(http://192.168.1.100/control); postRequest.setEntity(new UrlEncodedFormEntity(params, UTF-8)); try (CloseableHttpResponse response httpClient.execute(postRequest)) { int statusCode response.getStatusLine().getStatusCode(); if (statusCode ! 200) { Log.w(HTTP, unexpected status: statusCode); } }UrlEncodedFormEntity这个类的作用是把参数列表编码成HTTP请求体中的keyvalue串默认Content-Type是application/x-www-form-urlencoded。如果你对接的微Web站点只接受application/json那就要换成StringEntity并手动设置ContentType否则服务端解析不到参数。3.2 超时与连接池参数单个数值背后的真实语义超时配置是HttpClient最容易被误解的部分。很多人以为setConnectTimeout就是“整个请求的超时时间”实际上它只管TCP连接建立这一阶段。完整的超时有三个维度我列一下语义和推荐值参数作用阶段适用于微Web站点的推荐值说明connectTimeoutTCP连接建立3000ms内网设备通常1秒内响应超3秒基本可判定不可达socketTimeout连接建立后的数据读写5000ms微Web站点处理慢太短会导致任务被误杀connectionRequestTimeout从连接池取连接的等待2000ms并发紧张时避免请求无限排队这三个参数用RequestConfig统一设置代码写法如下RequestConfig requestConfig RequestConfig.custom() .setConnectTimeout(3000) .setSocketTimeout(5000) .setConnectionRequestTimeout(2000) .build();从技术上来说socketTimeout是每个数据包间隔的超时不是整个响应体的总耗时。如果服务端分多次返回数据每次间隔小于5秒总时长哪怕超过30秒也不会中断。理解这个语义很重要不然你会遇到“明明设了超时请求却跑了很久才报错”的迷惑现象。连接池的设置和超时是配套的。我维护过的一个现场App跑在某安卓工控机上每隔30秒轮询一次微Web站点高峰期还有手动操作。连接池参数按下面的方式设置PoolingHttpClientConnectionManager connManager new PoolingHttpClientConnectionManager(); connManager.setMaxTotal(10); connManager.setDefaultMaxPerRoute(4); connManager.setValidateAfterInactivity(1000);setMaxTotal(10)限制了全局总连接数setDefaultMaxPerRoute(4)限制单一路由的并发连接。setValidateAfterInactivity(1000)的作用是从连接池取连接时如果连接空闲超过1秒先做一次有效性检查。微Web站点的服务端经常主动断开空闲连接不设置这个参数的话客户端拿到一个失效连接去发请求得到的是Connection reset异常。3.3 Cookie与Session维持BasicCookieStore的坑很多微Web站点没有完整的Session框架认证逻辑就是“登录后下发一个Cookie后续请求带着Cookie就能通过”。这种情况下HttpClient的Cookie策略直接影响你能不能保持会话。我最初的习惯是每次请求前手动从SharedPreferences读Cookie并塞进Header后来发现服务端返回的新Cookie没有回写没过多久Session就失效了。HttpClient原生提供了CookieStore机制正确做法是在创建HttpClient时绑定一个BasicCookieStore实例BasicCookieStore cookieStore new BasicCookieStore(); CloseableHttpClient httpClient HttpClients.custom() .setDefaultCookieStore(cookieStore) .setDefaultRequestConfig(requestConfig) .build();这个实例在应用进程生命周期内保持单例登录接口返回的Set-Cookie会自动写入cookieStore后续请求自动携带Cookie。它的生命周期注意点BasicCookieStore只是内存存储App进程被杀后Cookie就没了需要自己持久化。我通常在登录成功后把cookieStore里的Cookie序列化存盘下次启动时重新加载。这里有一个容易翻车的细节不是所有Cookie都能序列化成功有些服务端返回的Cookie字段带了非法字符需要先过滤。4. 微Web站点联调避坑自签名证书、Keep-Alive与六条踩坑记录4.1 自签名证书与SSL信任链处理微Web站点使用自签名HTTPS证书的比例相当高。Android的HttpClient默认只信任系统CA遇到自签名证书直接抛SSLHandshakeException。到这一步网上流传的“全信任”代码大多是重写X509TrustManager让所有证书都通过校验。这个方法在测试环境可行但在实际项目中风险极大连接劫持、数据链路被中间人窃听随便一个都够喝一壶。我采用的折中方案是仅对特定IP或域名的连接放开校验其他请求走系统默认校验。代码实现的核心是自定义SSLContext给HttpClient设置一个覆盖默认socket factory的SSLSocketFactory。下面对关键部分做说明。SSLContext sslContext SSLContext.getInstance(TLS); sslContext.init(null, new TrustManager[]{new X509TrustManager() { public void checkClientTrusted(X509Certificate[] chain, String authType) {} public void checkServerTrusted(X509Certificate[] chain, String authType) {} public X509Certificate[] getAcceptedIssuers() { return new X509Certificate[0]; } }}, new SecureRandom()); SSLConnectionSocketFactory socketFactory new SSLConnectionSocketFactory(sslContext, NoopHostnameVerifier.INSTANCE);这里有两个关键点一是TrustManager的三个方法都是空实现表示对服务端证书不做任何校验二是NoopHostnameVerifier关闭了主机名验证否则即使证书信任IP和证书域名不匹配依然会失败。但这样写的代价是没有证书校验我很少在生产环境直接这么用。另一个思路是把这个HttpClient只用于特定的、可控的设备IP段不要让它处理公网请求。如果有服务端的证书文件比如pem或crt格式更好的方案是把证书导入本地信任库只信任这一张证书CertificateFactory cf CertificateFactory.getInstance(X.509); InputStream certStream new FileInputStream(server.pem); X509Certificate cert (X509Certificate) cf.generateCertificate(certStream); KeyStore ks KeyStore.getInstance(KeyStore.getDefaultType()); ks.load(null, null); ks.setCertificateEntry(server, cert); TrustManagerFactory tmf TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm()); tmf.init(ks);这种方式通过KeyStore保存证书TrustManagerFactory从KeyStore读取信任证书后续连接只接受这张证书安全性远高于全信任方案。需要说明的是证书文件要随App打包或首次连接时下载后存在私有目录不能用外部存储否则存在被替换的风险。4.2 Keep-Alive的真实限制与Header伪装微Web站点的Keep-Alive支持状况比较复杂。有的设备固件用的是精简HTTP Server不支持连接复用每个请求都独占Socket有的设备实现了Keep-Alive但超时时间很短比如5秒内没有新请求就断开。这种不稳定的行为让客户端非常难受因为连接池并不知道服务端已经断开了它只是拿着一个“看起来有效”的Socket去发请求。我调试过一个典型案例服务端3秒断开空闲连接客户端连接池里的连接有效期设置成60秒。结果是每次轮询请求有大概30%的概率第一次执行就报Connection reset第二次才成功。排查时在服务端看到大量TIME_WAIT状态的连接。这个问题的根源在于客户端和服务端对“空闲连接的有效期”认知不一致。解决思路有两层。第一层是设置较短的validateAfterInactivity比如500毫秒让客户端认为“空闲超过0.5秒的连接都不可靠”第二层是在请求层做一次自动重试。注意这两层作用不同validate控制的是连接池行为重试控制的是请求层行为都不可少。另外有个细节很多微Web站点会校验User-Agent不认识的就直接返回403。我之前被这个问题卡了半天因为从服务端日志看不出任何异常直到用抓包工具才发现请求的User-Agent是Dalvik/2.1.0服务端直接拒了。解决方法是把User-Agent伪装成浏览器getRequest.setHeader(User-Agent, Mozilla/5.0 (Linux; Android 10) AppleWebKit/537.36);4.3 避坑记录五条血泪经验下面这几条是我在多个项目里实打实踩过的坑每条都是“现象 → 原因 → 解决”的结构希望你能绕开。坑一连接池溢出导致后续请求全部排队超时现象是App正常使用一两个小时后所有请求都变慢最终在connectionRequestTimeout处报超时。原因连接池里的连接大部分被服务端悄悄断开客户端不知道每次请求占用一个连接后长时间得不到响应池子里的有效连接被占满新请求只能等。解决设置setValidateAfterInactivity(500)同时把连接空闲回收交给一个后台线程定期执行connManager.closeExpiredConnections()和closeIdleConnections(30, TimeUnit.SECONDS)。坑二自签名证书的Hostname校验导致SSLException现象是明明在TrustManager里放行了证书握手还是失败报错是“No subject alternative names present”。原因服务端的证书里没有配置IP SAN字段HttpClient的HostnameVerifier在证书中找不到匹配的IP或域名。解决在SSLConnectionSocketFactory的构造参数里传入NoopHostnameVerifier.INSTANCE或者在证书的subjectAltName里加入服务器IP。坑三服务端返回GBK编码解析后中文乱码现象是请求成功但响应体里的中文全部变成乱码。原因服务端的Content-Type没有声明charsetHttpClient默认按ISO-8859-1解码。解决不要用EntityUtils.toString(entity)的无参版本显式指定字符集。如果你能确认服务端返回的是GBK就用“GBK”不确定时可以先读byte数组用BOM或内容特征判断编码。坑四线程池使用不当导致应用闪退现象是在高频轮询时App偶发闪退Logcat里显示OutOfMemoryError。原因我在每次轮询时都新建HttpClient实例旧的没有关闭导致连接和底层资源持续累积。解决HttpClient实例全局单例化不要每次请求都new。如果必须动态创建必须保证每次用完都调用httpClient.close()。坑五响应体没有关闭导致Socket泄漏现象是长时间运行后连接数持续增长内网设备的负载越来越高。原因execute返回的CloseableHttpResponse没有放进try-with-resourcesEntityUtils.toString读取后也没有close。解决统一用try-with-resources包裹response和httpClient都实现Closeable接口关闭异常不会影响业务逻辑。5. 把HttpClient封装进Service层线程池、重试与缓存改造5.1 单例封装与线程池隔离HttpClient不适合在UI线程执行网络请求这是Android开发的基本认知。但封装成什么样不同项目差异很大。我现在的做法是把HttpClient的单例和线程池绑定在一起用静态内部类实现懒加载public class HttpClientManager { private final CloseableHttpClient httpClient; private final ExecutorService executor; private static class Holder { private static final HttpClientManager INSTANCE new HttpClientManager(); } public static HttpClientManager getInstance() { return Holder.INSTANCE; } private HttpClientManager() { PoolingHttpClientConnectionManager connManager new PoolingHttpClientConnectionManager(); connManager.setMaxTotal(10); connManager.setDefaultMaxPerRoute(4); RequestConfig config RequestConfig.custom() .setConnectTimeout(3000) .setSocketTimeout(5000) .setConnectionRequestTimeout(2000) .build(); httpClient HttpClients.custom() .setConnectionManager(connManager) .setDefaultRequestConfig(config) .build(); executor Executors.newFixedThreadPool(4); } public void enqueue(CallableString task, Callback callback) { executor.submit(new Runnable() { Override public void run() { try { String result task.call(); callback.onSuccess(result); } catch (Exception e) { callback.onFailure(e); } } }); } }这个封装的核心不是代码优雅而是把HttpClient的生命周期和应用的生命周期绑定。线程池固定4个线程对应连接池的4条路由连接让并发模型上下匹配。Callback接口需要自己在主线程切换回UI更新因为executor里的线程是后台线程直接更新UI会崩。Callback里用Handler或runOnUiThread切换都可以。5.2 重试策略与幂等性判断访问微Web站点的过程中Connection reset和SocketTimeout是最高频的失败类型。针对这两种异常我通常会在请求层设置重试。但重试并不是无条件进行的尤其是POST请求必须考虑幂等性。private String executeWithRetry(HttpUriRequest request, int maxRetries) { IOException lastException null; for (int i 0; i maxRetries; i) { try { try (CloseableHttpResponse response httpClient.execute(request)) { return EntityUtils.toString(response.getEntity(), UTF-8); } } catch (IOException e) { lastException e; // 只有连接类异常才值得重试 if (!(e instanceof ConnectTimeoutException) !(e instanceof ConnectionClosedException) !(e instanceof SocketTimeoutException)) { break; } } } throw new RuntimeException(request failed after retries, lastException); }重试的关键有两点第一只对“服务端可能没收到请求”的异常重试比如连接超时和连接被重置。对于“请求已到达服务端但处理失败”的情况重试会导致重复数据或重复操作。第二HttpUriRequest对象不能直接重试因为执行一次后它的状态就已经变掉了。上面代码为了便于阅读省略了重建请求的逻辑实际使用时需要传入一个RequestSupplier每次都返回全新的请求对象。另外重试间隔要做递增退避我习惯于50毫秒起步、最多4次间隔乘以2翻倍这样不会给微Web站点造成瞬时压力。5.3 本地缓存与ETag/Last-Modified的处理微Web站点响应慢且带宽有限但对数据实时性要求不高的场景加上本地缓存是性价比最高的优化。HttpClient本身没有缓存模块需要自己做。我常用的方案是内存缓存加磁盘缓存两层内存用LruCache磁盘用文件。关键点在条件请求上每次请求时带上Last-Modified或ETag。File cacheFile new File(context.getCacheDir(), device_status.json); if (cacheFile.exists()) { getRequest.setHeader(If-Modified-Since, lastModified); }服务端收到If-Modified-Since后如果资源没有变化会返回304 Not Modified响应体为空。这时就不需要重新解析数据直接用本地缓存的内容。如果返回200则说明资源有变化写入缓存并更新Last-Modified时间。这套机制用在轮询场景下能显著减少内网带宽消耗和设备负载。但要小心一个坑很多微Web站点的Last-Modified实现并不标准它返回的时间是服务器当前时间而不是资源最后修改时间导致每次请求都返回200。这种情况下需要降级要么去掉条件请求只做本地缓存要么让服务端加上ETag支持。另有一种折中策略是无论服务端是否支持条件请求客户端只在本地缓存有效期过期后才发起网络请求比如30秒内直接返回缓存超过30秒再走网络。这个策略的取舍是实时性损失但只要不是那种按秒刷新的监控页面体验上完全没问题。6. 抓包与调参的最后一公里固定Host、日志分级与超时阈值如果你已经把HttpClient跑通了联调阶段还有一个高频问题怎么确认请求真的发出去了、服务端到底收到了什么。我在多个项目里验证过的做法是先固定Host再做日志分级最后按实际服务质量微调超时阈值。固定Host解决的是内网多IP环境下的指向问题。微Web站点有时会同时配置有线IP和无线IPApp请求的IP地址不一样服务端看到的来源就不同会让设备端的黑白名单和访问控制产生混乱。可以在App的网络配置里加一个debug开关运行时打印“本次请求URL 实际解析出的IP”出现问题时能快速定位环境差异。日志分级方面我习惯在封装层预留一个HttpLoggingInterceptor类似的功能但不用第三方库。因为Apache HttpClient原生没有Interceptor机制最省事的做法是在execute前后手动打点long start System.currentTimeMillis(); try (CloseableHttpResponse response httpClient.execute(getRequest)) { long cost System.currentTimeMillis() - start; Log.d(HTTP, method getRequest.getMethod() url getRequest.getURI() cost cost ms status response.getStatusLine().getStatusCode()); }这段日志的价值在于时间消耗分布connect超时、socket读写超时、服务端响应慢三类问题在cost和异常类型上表现完全不同。ConnectTimeoutException说明IP不可达SocketTimeoutException说明连接建立了但服务端一直没有数据response接收到但status非200说明服务端业务逻辑报错。看到日志后按异常类型去调整对应超时参数就行。超时阈值的调整我一般遵循一个经验法则connectTimeout不要超过5秒内网设备绝大多数1秒内握手完成超过5秒基本可以断定网络路径有问题socketTimeout要结合业务特征如果轮询接口固定5秒超时但服务端平均处理时间就要4秒那这个阈值迟早误杀。一个可操作的做法是用Weekday和Weekend两套参数做对比连续观察几天日志里的告警分布再决定是否调整。最后的收尾有个习惯我得提一下。从那以后我每次在Android上对接微Web站点都会强制先走一遍“三个确认”确认服务端协议是HTTP/1.0还是1.1、确认服务端连接的Keep-Alive超时时间、确认证书是自签名还是CA签发。这个过程看起来很基础但能过滤掉大概七成的联调问题。如果你也在和微Web站点打交道希望这些记录能帮你少走一段弯路。本文还有配套的精品资源点击获取