OkHttp: 使用入门
文章目录
-
- 1. 领域对象
-
- 1. Request
- 2. Response
-
- 2.1 请求重写
- 2.2 重写返回
- 2.3 跟踪请求
- 2.4 自动重试
- 3. Calls
- 2. 创建连接
-
- 1、URLs
- 2、Addresses
- 3、Routes
- 4、Connections
- 3. 使用案例
-
- 1、同步GET请求
- 2、异步GET请求
- 3、发送和读取HTTP头
- 4、POST 字符传
- 5、POST 流
- 6、POST 文件内容
- 7、POST 表单
- 8、上传
- 9、使用Moshi在JSON和对象之间转换
- 10、缓存Response
- 11、取消Call调用
- 12、超时
- 13、设置
- 14、Authentication
- 15. 设置代理
1. 领域对象
HTTP客户端的作用就是接受你的请求，获取对应的返回。理论上简单的，然后实践过程会有一些陷阱。OkHttp是其中使用的比较广泛的一个。
okhttp主要包含的概念如下：
1. Request
包含请求的url，方法(GET/POST/PUT等待)，HTTP头，以及请求体。
2. Response
返回的编码(200 成功, 404 页面不存在)，HTTP头，以及返回体。
2.1 请求重写
我们会在高层次的描述请求哪个地址，包含什么头等等。为了正确性和高效，OkHttp会帮我们重写请求。
- 添加缺失的HTTP头，包括Content-Lenght、Transfer-Encoding、User-Agent、Host、Connection、Content-Type
- 动添加一个Accept-Encoding，支持自动解压gzip等压缩过的返回
- 如果你有Cookie，OkHttp会自动添加一个Cookie的HTTP头
- 可缓存的请求(Cache-Control、Expired、Etag等)，自动添加If-Modified-Since、If-None-Match头
2.2 重写返回
- 如果返回是压缩过的，OkHttp会自动解压，并删除Content-Encoding和Content-Length头，因为这两个值解压后已经不准确
- 如果是条件获取(If-Modified-Since等)，OkHttp会自动切换从本地缓存或者服务端获取内容
2.3 跟踪请求
- 自动完成302跳转，获取最终结果页面内容
- 如果配置了Authenticator，自动HTTP权限验证
2.4 自动重试
- 连接池内连接过期或者服务器不可触达，尝试重试(重试的机制还需要深挖)
3. Calls
由于请求重写、跟踪请求、自动重试等等，你描述的请求实际上会产生多个Request/Response， OkHttp将这个操作抽象为一个Call。
Call实际上有两种执行方式
- 同步执行，当前线程阻塞，指定请求完成
- 异步执行，当前请求如队列，完成请求会回调注册的接口
Call可以被其他线程取消。如果Call被取消后还有线程还有代码去写Request或者读Response会抛出IOException
在同步模式下，你使用自己线程，并负责管理simultaneous，太多的simultaneous connections浪费资源，过少则影响延时
在异步模式下，Dispatcher负责管理simultaneous，你可以设置每个webserver(默认5个)以及总(默认64个)的连接数。
2. 创建连接
尽管你只提供一个URL链接，OkHttp会使用三种类型去链接WebServer，它们分别是: URL、Address、Route
1、URLs
URL是HTTP和互联网的基础，处理提供Web上资源的统一命名服务，同样指定了怎么访问Web资源。
URL是抽象的
- 指定了请求内容是纯文本(http)还是加密的(https)
- 没有指定加解密算法，怎么去验证证书(HostnameVerifier)，哪些证书是可靠的(SSLSocketFactory)
- 没有指定怎么使用代理服务器，以及代理服务器怎么鉴权
2、Addresses
Adress指定了一个WebServer，包括所有连接服务器所需要的信息(包括端口、HTTPS设置、倾向的网络协议，如HTTP/2、SPDY等)。
相同服务器地址的URL可能会共享底层的TCP连接，共享TCP连接会有明显的性能优势:
- 更低延迟
- 更高吞吐量(TCP慢启动)
- 省电
OkHttp通过ConnectionPool自动重用连接。
3、Routes
Routes提供了自动链接WebServer里的必要信息，包括
- IP地址，通过DNS获取
- 确定的代理服务器，如果配置了ProxySelector的话
- TLS(传输层安全协议)版本号
一个Adress可能会有多个Routes，比如一个跨数据中心部署的WebServer，DNS解析后肯能会有多个地址。
4、Connections
当你请求URL时，OkHttp为你做了以下操作:
- 使用URL和配置好的OkHttpClient创建一个Addresss，里边包含了我们怎么去连接Web服务器的信息。
- 尝试从ConnectionPool里获取一个对应Address的连接。
- 找不到连接的话，它会尝试选择一个Route，这意味着DNS解析、选择TLS版本以及代理服务器(需要的话)。
- 如果这是一个新的Route，它会创建一个Socket连接、TLS隧道(经过HTTPS的代理服务)、TLS连接。如果需要的话，完成TLS握手。
- 发生请求并读取结果。
如果连接有问题的话，OkHttp会重新选择另外一个Route并重试。这有助于OkHttp从服务端部分地址不可用时恢复。同样有助于当连接过期，或者TLS版本不支持的时候。
当响应读取完成后，连接会被退回到连接池中等待重用，一段时间没有使用后会被从连接池里清除。
3. 使用案例
我们提供了一下用OkHttp解决常见问题的样例。
1、同步GET请求
当响应结果比较小的时候(<1M),response.body().string()是方便且高效的，否则应该使用流读取。
private final OkHttpClient client = new OkHttpClient();
public void run() throws Exception {
Request request = new Request.Builder().url("https://publicobject.com").build();
try (Response response = client.newCall(request).execute()) {
if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
Headers responseHeaders = response.headers();
for (int i = 0; i < responseHeaders.size(); i++) {
System.out.println(responseHeaders.name(i) + ": " + responseHeaders.value(i));
}
System.out.println(response.body().string());
}
}
2、异步GET请求
在OkHttp的工作线程里请求，当响应可读的时候调用回调函数。回调函数实在响应HTTP头读取后调用的，读取响应体还是需要同步完成。
private final OkHttpClient client = new OkHttpClient();
public void run() throws Exception {
Request request = new Request.Builder().url("http://publicobject.com").build();
client.newCall(request).enqueue(new Callback() {
@Override public void onFailure(Call call, IOException e) {
e.printStackTrace();
}
@Override public void onResponse(Call call, Response response) throws IOException {
try (ResponseBody responseBody = response.body()) {
if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
Headers responseHeaders = response.headers();
for (int i = 0, size = responseHeaders.size(); i < size; i++) {
System.out.println(responseHeaders.name(i) + ": " + responseHeaders.value(i));
}
System.out.println(responseBody.string());
}
}
});
}
3、发送和读取HTTP头
一般来说，HTTP头一个KEY会对应一个值，但是有的字段允许有多个值。OkHttp为这两种情况提供了支持:
- Request.Builder.header(name,value)方法，支持单值的HTTP头，把已存在的同名HTTP头删除。
- Request.Builder.addHeader(name,value)只是单纯的添加，不会有删除操作。
- Response.header(name)，获取多值的最后一个，没有的话返回null。
- Response.headers(name)，返回多值
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();
try (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"));
}
}
4、POST 字符传
public static final MediaType MEDIA_TYPE_MARKDOWN = MediaType.parse("text/x-markdown; charset=utf-8");
private final OkHttpClient client = new OkHttpClient();
public void run() throws Exception {
String postBody = "* _1.2_ August 11, 2013\n";
Request request = new Request.Builder()
.url("https://api.github.com/markdown/raw")
.post(RequestBody.create(MEDIA_TYPE_MARKDOWN, postBody))
.build();
try (Response response = client.newCall(request).execute()) {
if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
System.out.println(response.body().string());
}
}
5、POST 流
使用流做为请求体，请求体内容会在发送请求的时候输出，这个例子里使用的是Okio的BufferedSink，你也可以通过BufferedSkin.outputStream获取输出流。
public static final MediaType MEDIA_TYPE_MARKDOWN
= MediaType.parse("text/x-markdown; charset=utf-8");
private final OkHttpClient client = new OkHttpClient();
public void run() throws Exception {
RequestBody requestBody = new RequestBody() {
@Override public MediaType contentType() {
return MEDIA_TYPE_MARKDOWN;
}
@Override public void writeTo(BufferedSink sink) throws IOException {
sink.writeUtf8("Numbers\n");
sink.writeUtf8("-------\n");
for (int i = 2; i <= 997; i++) {
sink.writeUtf8(String.format(" * %s = %s\n", i, 2*i));
}
}
};
Request request = new Request.Builder()
.url("https://api.github.com/markdown/raw")
.post(requestBody)
.build();
try (Response response = client.newCall(request).execute()) {
if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
System.out.println(response.body().string());
}
}
6、POST 文件内容
public static final MediaType MEDIA_TYPE_MARKDOWN
= MediaType.parse("text/x-markdown; charset=utf-8");
private final OkHttpClient client = new OkHttpClient();
public void run() throws Exception {
File file = new File("README.md");
Request request = new Request.Builder()
.url("https://api.github.com/markdown/raw")
.post(RequestBody.create(MEDIA_TYPE_MARKDOWN, file))
.build();
try (Response response = client.newCall(request).execute()) {
if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
System.out.println(response.body().string());
}
}
7、POST 表单
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();
try (Response response = client.newCall(request).execute()) {
if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
System.out.println(response.body().string());
}
}
8、上传
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();
try (Response response = client.newCall(request).execute()) {
if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
System.out.println(response.body().string());
}
}
9、使用Moshi在JSON和对象之间转换
Moshi是一个简便的JSON转换类库。
ResponseBody.charStream()使用Content-Type里的编码解释响应内容，找不到编码默认UTF-8。
private final OkHttpClient client = new OkHttpClient();
private final Moshi moshi = new Moshi.Builder().build();
private final JsonAdapter gistJsonAdapter = moshi.adapter(Gist.class);
public void run() throws Exception {
Request request = new Request.Builder()
.url("https://api.github.com/gists/c2a7c39532239ff261be")
.build();
try (Response response = client.newCall(request).execute()) {
if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
Gist gist = gistJsonAdapter.fromJson(response.body().source());
for (Map.Entry entry : gist.files.entrySet()) {
System.out.println(entry.getKey());
System.out.println(entry.getValue().content);
}
}
}
static class Gist {
Map files;
}
static class GistFile {
String content;
}
10、缓存Response
要缓存Response，你需要一个可以读写的目录，以及设置缓存的大小。 大多数应用只需要创建一次OkHttpClient对象，两个实例使用同一个缓存目录会导致冲突，甚至使程序崩溃。
Response缓存通过服务端HTTP头控制。
添加一下HTTP头可以控制缓存的行为：
- CacheControl.FORCE_NETWORK，强制从服务端加载。
- CacheControl.FORCE_CACHE，强制从缓存加载，当缓存中信息不可获取(不存在或者过期)，返回504
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.Builder().cache(cache).build();
}
public void run() throws Exception {
Request request = new Request.Builder().url("http://publicobject.com/helloworld.txt").build();
String response1Body;
try (Response response1 = client.newCall(request).execute()) {
if (!response1.isSuccessful()) throw new IOException("Unexpected code " + response1);
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());
}
String response2Body;
try (Response response2 = client.newCall(request).execute()) {
if (!response2.isSuccessful()) throw new IOException("Unexpected code " + response2);
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));
}
11、取消Call调用
通Call.cancel()取消调用，如果另外一个线程正在写请求或者读取返回时，抛出IOException
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);
System.out.printf("%.2f Executing call.%n", (System.nanoTime() - startNanos) / 1e9f);
try (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);
}
}
12、超时
当端不可触达的时候，客户端连接问题、服务端不可用、或者两者之间的问题，可以通过设置超时。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();
try (Response response = client.newCall(request).execute()) {
System.out.println("Response completed: " + response);
}
}
13、设置
所有的设置都是通过OkHttpClient完成的，包括代理、超时、缓存等等。当你需要为一个请求修改设置的时候，调用OkHttpClient.builder()方法，返回的builder和原始的OkHttpClient共享连接池、Dispatcher和配置信息，只需要修改特有的配置即可。
private final OkHttpClient client = new OkHttpClient();
public void run() throws Exception {
Request request = new Request.Builder()
.url("http://httpbin.org/delay/1") // This URL is served with a 1 second delay.
.build();
// Copy to customize OkHttp for this request.
OkHttpClient client1 = client.newBuilder()
.readTimeout(500, TimeUnit.MILLISECONDS)
.build();
try (Response response = client1.newCall(request).execute()) {
System.out.println("Response 1 succeeded: " + response);
} catch (IOException e) {
System.out.println("Response 1 failed: " + e);
}
// Copy to customize OkHttp for this request.
OkHttpClient client2 = client.newBuilder()
.readTimeout(3000, TimeUnit.MILLISECONDS)
.build();
try (Response response = client2.newCall(request).execute()) {
System.out.println("Response 2 succeeded: " + response);
} catch (IOException e) {
System.out.println("Response 2 failed: " + e);
}
}
14、Authentication
OkHttp会自动重试未授权的请求，当服务端返回401的时候，OkHttp会尝试寻找Authenticator注册信息，如果有的话通过对应信息进行验证。代码关键点:
- response.challenges()
- Credentials.basic
- response.request().newBuilder()
private final OkHttpClient client;
public Authenticate() {
client = new OkHttpClient.Builder()
.authenticator(new Authenticator() {
@Override public Request authenticate(Route route, Response response) throws IOException {
if (response.request().header("Authorization") != null) {
return null; // Give up, we've already attempted to authenticate.
}
System.out.println("Authenticating for response: " + response);
System.out.println("Challenges: " + response.challenges());
String credential = Credentials.basic("jesse", "password1");
return response.request().newBuilder()
.header("Authorization", credential)
.build();
}
})
.build();
}
public void run() throws Exception {
Request request = new Request.Builder()
.url("http://publicobject.com/secrets/hellosecret.txt")
.build();
try (Response response = client.newCall(request).execute()) {
if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
System.out.println(response.body().string());
}
}
Authenticator返回null的时候，OkHttp会停止重试。为了避免Authentication不起效时还反复重试, 可以再重试过一次之后，返回null退出执行
if (credential.equals(response.request().header("Authorization"))) {
return null; // If we already failed with these credentials, don't retry.
}
你以可以通过Response.priorResponse()来计数调用了多少次，次数满是退出重试。
if (responseCount(response) >= 3) {
return null; // If we've failed 3 times, give up.
}
private int responseCount(Response response) {
int result = 1;
while ((response = response.priorResponse()) != null) {
result++;
}
return result;
}
15. 设置代理
Proxy proxy = new Proxy(Proxy.Type.HTTP, new InetSocketAddress("127.0.0.1",12345));
OkHttpClient client = new OkHttpClient.Builder().proxy(proxy).build();
Request request = new Request.Builder().url(url).header("Authorization", signature).post(RequestBody.create(MEDIA_JSON, postBody)).build();
Response response = client.newCall(request).execute();