OkHttp 使用完全教程（下）

private final OkHttpClient client = new OkHttpClient ();

public void run () throws Exception {

RequestBody formBody = new FormBody . Builder ()

. add ( "search" , "Jurassic Park" )

. build ();

Request request = new Request . Builder ()

. url ( "https://en.wikipedia.org/w/index.php" )

. post ( formBody )

. build ();

Response response = client . newCall ( request ). execute ();

if ( ! response . isSuccessful ()) throw new IOException ( "Unexpected code " + response );

System . out . println ( response . body (). string ());

}

4.5 Post方式提交分块请求

MultipartBody.Builder可以构建复杂的请求体, 与HTML文件上传形式兼容. 多块请求体中每块请求都是一个请求体, 可以定义自己的请求头. 这些请求头可以用来描述这块请求, 例如它的Content-Disposition. 如果Content-Length和Content-Type可用的话, 他们会被自动添加到请求头中.

private static final String IMGUR_CLIENT_ID = "..." ;

private static final MediaType MEDIA_TYPE_PNG = MediaType . parse ( "image/png" );

private final OkHttpClient client = new OkHttpClient ();

public void run () throws Exception {

// Use the imgur image upload API as documented at https://api.imgur.com/endpoints/image

RequestBody requestBody = new MultipartBody . Builder ()

. setType ( MultipartBody . FORM )

. addFormDataPart ( "title" , "Square Logo" )

. addFormDataPart ( "image" , "logo-square.png" ,

RequestBody . create ( MEDIA_TYPE_PNG , new File ( "website/static/logo-square.png" )))

. build ();

Request request = new Request . Builder ()

. header ( "Authorization" , "Client-ID " + IMGUR_CLIENT_ID )

. url ( "https://api.imgur.com/3/image" )

. post ( requestBody )

. build ();

Response response = client . newCall ( request ). execute ();

if ( ! response . isSuccessful ()) throw new IOException ( "Unexpected code " + response );

System . out . println ( response . body (). string ());

}

5. 其他用法

5.1 提取响应头

典型的HTTP头像是一个Map : 每个字段都有一个或没有值. 但是一些头允许多个值, 像Guava的Multimap.

例如: HTTP响应里面提供的Vary响应头, 就是多值的. OkHttp的api试图让这些情况都适用.

当写请求头的时候, 使用header(name, value)可以设置唯一的name、value. 如果已经有值, 旧的将被移除, 然后添加新的. 使用addHeader(name, value)可以添加多值（添加, 不移除已有的）.

当读取响应头时, 使用header(name)返回最后出现的name、value. 通常情况这也是唯一的name、value. 如果没有值, 那么header(name)将返回null. 如果想读取字段对应的所有值, 使用headers(name)会返回一个list.

为了获取所有的Header, Headers类支持按index访问.

private final OkHttpClient client = new OkHttpClient ();

public void run () throws Exception {

Request request = new Request . Builder ()

. url ( "https://api.github.com/repos/square/okhttp/issues" )

. header ( "User-Agent" , "OkHttp Headers.java" )

. addHeader ( "Accept" , "application/json; q=0.5" )

. addHeader ( "Accept" , "application/vnd.github.v3+json" )

. build ();

Response response = client . newCall ( request ). execute ();

if ( ! response . isSuccessful ()) throw new IOException ( "Unexpected code " + response );

System . out . println ( "Server: " + response . header ( "Server" ));

System . out . println ( "Date: " + response . header ( "Date" ));

System . out . println ( "Vary: " + response . headers ( "Vary" ));

}

5.2 使用Gson来解析JSON响应

Gson是一个在JSON和Java对象之间转换非常方便的api库. 这里我们用Gson来解析Github API的JSON响应.

注意: ResponseBody.charStream()使用响应头Content-Type指定的字符集来解析响应体. 默认是UTF-8.

private final OkHttpClient client = new OkHttpClient ();

private final Gson gson = new Gson ();

public void run () throws Exception {

Request request = new Request . Builder ()

. url ( "https://api.github.com/gists/c2a7c39532239ff261be" )

. build ();

Response response = client . newCall ( request ). execute ();

if ( ! response . isSuccessful ()) throw new IOException ( "Unexpected code " + response );

Gist gist = gson . fromJson ( response . body (). charStream (), Gist . class );

for ( Map . Entry String , GistFile > entry : gist . files . entrySet ()) {

System . out . println ( entry . getKey ());

System . out . println ( entry . getValue (). content );

}

}

static class Gist {

Map String , GistFile > files ;

}

static class GistFile {

String content ;

}

5.3 响应缓存

为了缓存响应, 你需要一个你可以读写的缓存目录, 和缓存大小的限制. 这个缓存目录应该是私有的, 不信任的程序应不能读取缓存内容.

一个缓存目录同时拥有多个缓存访问是错误的. 大多数程序只需要调用一次new OkHttp(), 在第一次调用时配置好缓存, 然后其他地方只需要调用这个实例就可以了. 否则两个缓存示例互相干扰, 破坏响应缓存, 而且有可能会导致程序崩溃.

响应缓存使用HTTP头作为配置. 你可以在请求头中添加Cache-Control: max-stale=3600 , OkHttp缓存会支持. 你的服务通过响应头确定响应缓存多长时间, 例如使用Cache-Control: max-age=9600.

private final OkHttpClient client ;

public CacheResponse ( File cacheDirectory ) throws Exception {

int cacheSize = 10 * 1024 * 1024 ; // 10 MiB

Cache cache = new Cache ( cacheDirectory , cacheSize );

client = new OkHttpClient ();

client . setCache ( cache );

}

public void run () throws Exception {

Request request = new Request . Builder ()

. url ( "http://publicobject.com/helloworld.txt" )

. build ();

Response response1 = client . newCall ( request ). execute ();

if ( ! response1 . isSuccessful ()) throw new IOException ( "Unexpected code " + response1 );

String response1Body = response1 . body (). string ();

System . out . println ( "Response 1 response:          " + response1 );

System . out . println ( "Response 1 cache response:    " + response1 . cacheResponse ());

System . out . println ( "Response 1 network response:  " + response1 . networkResponse ());

Response response2 = client . newCall ( request ). execute ();

if ( ! response2 . isSuccessful ()) throw new IOException ( "Unexpected code " + response2 );

String response2Body = response2 . body (). string ();

System . out . println ( "Response 2 response:          " + response2 );

System . out . println ( "Response 2 cache response:    " + response2 . cacheResponse ());

System . out . println ( "Response 2 network response:  " + response2 . networkResponse ());

System . out . println ( "Response 2 equals Response 1? " + response1Body . equals ( response2Body ));

}

如果需要阻值response使用缓存, 使用CacheControl.FORCE_NETWORK. 如果需要阻值response使用网络, 使用CacheControl.FORCE_CACHE.

警告: 如果你使用FORCE_CACHE, 但是response要求使用网络, OkHttp将会返回一个504 Unsatisfiable Request响应.

5.3.1 Force a Network Response

有些时候, 比如用户刚刚点击刷新按钮, 这时必须跳过缓存, 直接从服务器抓取数据. 为了强制全面刷新, 我们需要添加no-cache指令:

connection . addRequestProperty ( "Cache-Control" , "no-cache" );

这样就可以强制每次请求直接发送给源服务器, 而不经过本地缓存版本的校验, 常用于需要确认认证的应用和严格要求使用最新数据的应用.

5.3.2 Force a Cache Response

有时你会想立即显示资源. 这样即使在后台正下载着最新资源, 你的客户端仍然可以先显示原有资源, 毕竟有个东西显示比没有东西显示要好.

如果需要限制让请求优先使用本地缓存资源, 需要增加only-if-cached指令:

try {

connection . addRequestProperty ( "Cache-Control" , "only-if-cached" );

InputStream cached = connection . getInputStream ();

// the resource was cached! show it

catch ( FileNotFoundException e ) {

// the resource was not cached

}

}

5.4 取消一个Call

使用Call.cancel()可以立即停止掉一个正在执行的call. 如果一个线程正在写请求或者读响应, 将会引发IOException. 当call没有必要的时候, 使用这个api可以节约网络资源. 例如当用户离开一个应用时, 不管同步还是异步的call都可以取消.

你可以通过tags来同时取消多个请求. 当你构建一请求时, 使用RequestBuilder.tag(tag)来分配一个标签, 之后你就可以用OkHttpClient.cancel(tag)来取消所有带有这个tag的call.

private final ScheduledExecutorService executor = Executors . newScheduledThreadPool ( 1 );

private final OkHttpClient client = new OkHttpClient ();

public void run () throws Exception {

Request request = new Request . Builder ()

. url ( "http://httpbin.org/delay/2" ) // This URL is served with a 2 second delay.

. build ();

final long startNanos = System . nanoTime ();

final Call call = client . newCall ( request );

// Schedule a job to cancel the call in 1 second.

executor . schedule ( new Runnable () {

@Override public void run () {

System . out . printf ( "%.2f Canceling call.%n" , ( System . nanoTime () - startNanos ) / 1e9f );

call . cancel ();

System . out . printf ( "%.2f Canceled call.%n" , ( System . nanoTime () - startNanos ) / 1e9f );

}

}, 1 , TimeUnit . SECONDS );

try {

System . out . printf ( "%.2f Executing call.%n" , ( System . nanoTime () - startNanos ) / 1e9f );

Response response = call . execute ();

System . out . printf ( "%.2f Call was expected to fail, but completed: %s%n" ,

( System . nanoTime () - startNanos ) / 1e9f , response );

} catch ( IOException e ) {

System . out . printf ( "%.2f Call failed as expected: %s%n" ,

( System . nanoTime () - startNanos ) / 1e9f , e );

}

}

5.5 超时

没有响应时使用超时结束call. 没有响应的原因可能是客户点链接问题、服务器可用性问题或者这之间的其他东西. OkHttp支持连接超时, 读取超时和写入超时.

private final OkHttpClient client ;

public ConfigureTimeouts () throws Exception {

client = new OkHttpClient . Builder ()

. connectTimeout ( 10 , TimeUnit . SECONDS )

. writeTimeout ( 10 , TimeUnit . SECONDS )

. readTimeout ( 30 , TimeUnit . SECONDS )

. build ();

}

public void run () throws Exception {

Request request = new Request . Builder ()

. url ( "http://httpbin.org/delay/2" ) // This URL is served with a 2 second delay.

. build ();

Response response = client . newCall ( request ). execute ();

System . out . println ( "Response completed: " + response );

}

5.6 每个call的配置

使用OkHttpClient, 所有的HTTP Client配置包括代理设置、超时设置、缓存设置. 当你需要为单个call改变配置的时候, 调用OkHttpClient.newBuilder(). 这个api将会返回一个builder, 这个builder和原始的client共享相同的连接池, 分发器和配置.

下面的例子中，我们让一个请求是500ms的超时、另一个是3000ms的超时。

private final OkHttpClient client = new OkHttpClient ();