OkHttp 使用示例教程

Five_B

已于 2025-03-04 15:26:31 修改

阅读量1k

点赞数 20

分类专栏： OkHttp 使用文章标签： java spring boot

于 2025-02-27 16:21:47 首次发布

本文链接：https://blog.youkuaiyun.com/qq_36178841/article/details/145905392

版权

OkHttp 使用专栏收录该内容

1 篇文章

订阅专栏

OkHttp 使用示例教程

同步获取

下载一个文件，打印其头部信息，并将响应体打印为字符串。

string() 方法对于小文档来说既方便又高效。但是，如果响应体较大（大于 1 MiB），请避免使用 string()，因为它会将整个文档加载到内存中。在这种情况下，建议将响应体作为流进行处理。

private final OkHttpClient client = new OkHttpClient();

  public void run() throws Exception {
    Request request = new Request.Builder()
        .url("https://publicobject.com/helloworld.txt")
        .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());
    }
  }

异步获取

在工作线程上下载一个文件，并在响应可读取时进行回调。回调是在响应头部准备好之后执行的。读取响应体仍然可能会阻塞。OkHttp 当前没有提供异步 API 来分段接收响应体。

private final OkHttpClient client = new OkHttpClient();

  public void run() throws Exception {
    Request request = new Request.Builder()
        .url("http://publicobject.com/helloworld.txt")
        .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());
        }
      }
    });
  }

访问头部

通常，HTTP 头部像一个 Map<String, String>：每个字段只有一个值或没有值。但有些头部允许多个值，就像 Guava 的 Multimap。例如，HTTP 响应提供多个 Vary 头部是合法且常见的。OkHttp 的 API 尝试使这两种情况都变得方便。

在写请求头时，使用 header(name, value) 设置 name 的唯一值为 value。如果已有值，它们将在添加新值之前被移除。使用 addHeader(name, value) 可以添加一个头部，而不移除已存在的头部。

在读取响应头时，使用 header(name) 返回该字段的最后一个值。通常，这也是唯一的值！如果没有值，header(name) 将返回 null。要将字段的所有值作为列表读取，使用 headers(name)。

要访问所有头部，使用 Headers 类，它支持按索引访问。

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"));
    }
  }

POST 方式发送字符串

使用 HTTP POST 将请求体发送到服务。此示例将一个 markdown 文档通过 POST 发送到一个将 markdown 渲染为 HTML 的 Web 服务。由于整个请求体会同时加载到内存中，因此避免使用此 API 发送大于 1 MiB 的文档。

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 = ""
        + "Releases\n"
        + "--------\n"
        + "\n"
        + " * _1.0_ May 6, 2013\n"
        + " * _1.1_ June 15, 2013\n"
        + " * _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());
    }
  }

后端流式传输

在这里，我们将请求体作为流进行 POST。请求体的内容在写入时逐步生成。这个示例直接流式传输到 Okio 的缓冲输出流。您的程序可能更喜欢使用 OutputStream，可以通过 BufferedSink.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, factor(i)));
        }
      }

      private String factor(int n) {
        for (int i = 2; i < n; i++) {
          int x = n / i;
          if (x * i == n) return factor(x) + " × " + i;
        }
        return Integer.toString(n);
      }
    };

    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());
    }
  }

上传文件

使用文件作为请求体非常简单。

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());
    }
  }

上传表单参数

使用 FormBody.Builder 来构建一个类似 HTML 标签的请求体。名称和值将使用与 HTML 兼容的表单 URL 编码进行编码。

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());
    }
  }

上传多部分请求

MultipartBody.Builder 可以构建与 HTML 文件上传表单兼容的复杂请求体。多部分请求体的每一部分本身都是一个请求体，并且可以定义自己的头部。如果存在，这些头部应该描述该部分的主体，例如它的 Content-Disposition。如果可用，Content-Length 和 Content-Type 头部会自动添加。

/**
   * 用于 OkHttp 示例的 imgur 客户端 ID。如果您将 imgur 用于其他用途，请申请您自己的客户端 ID！
   * https://api.imgur.com/oauth2
   */
  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 {
    // 使用 imgur 图像上传 API，详细文档请见 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());
    }
  }

使用 Moshi 解析 JSON 响应

Moshi 是一个方便的 API，用于在 JSON 和 Java 对象之间转换。在这里，我们使用它来解码来自 GitHub API 的 JSON 响应。

注意：ResponseBody.charStream() 使用 Content-Type 响应头来选择在解码响应体时使用的字符集。如果没有指定字符集，它默认使用 UTF-8。

  private final OkHttpClient client = new OkHttpClient();
  private final Moshi moshi = new Moshi.Builder().build();
  private final JsonAdapter<Gist> 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<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;
  }

响应缓存

为了缓存响应，您需要一个可以读写的缓存目录，并对缓存的大小设置限制。缓存目录应该是私有的，不可信的应用程序不应能够读取其内容！

同时让多个缓存访问同一个缓存目录是错误的。大多数应用程序应该只调用一次 new OkHttpClient()，配置它的缓存，并在整个应用中使用同一个实例。否则，两个缓存实例会互相冲突，损坏响应缓存，并可能导致程序崩溃。

响应缓存使用 HTTP 头部进行所有配置。您可以添加像 Cache-Control: max-stale=3600 这样的请求头，OkHttp 的缓存会遵守它们。您的 web 服务器通过自己的响应头（如 Cache-Control: max-age=9600）来配置响应缓存的时间。还有一些缓存头部用于强制使用缓存响应、强制使用网络响应，或强制使用条件 GET 来验证网络响应。

  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));
  }

取消 Call

使用 Call.cancel() 立即停止正在进行的 Call。如果线程正在写入请求或读取响应，它将收到一个 IOException。使用此方法可以在 Call 不再需要时节省网络资源；例如，当用户离开应用程序时。同步和异步的 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") // 此 URL 具有 2 秒的延迟。
        .build();

    final long startNanos = System.nanoTime();
    final Call call = client.newCall(request);

    // 创建一个任务，在 1 秒后取消呼叫。
    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);
    }
  }

超时

使用超时来在 Call 的对端无法访问时使 Call 失败。网络分区可能是由于客户端连接问题、服务器可用性问题或两者之间的任何原因。OkHttp 支持连接、写入、读取和完整 Call 超时。

  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") // 此 URL 的响应有 2 秒的延迟。
        .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println("Response completed: " + response);
    }
  }

Per-call 配置

所有的 HTTP 客户端配置都包含在 OkHttpClient 中，包括代理设置、超时和缓存。当你需要更改单个调用的配置时，调用 OkHttpClient.newBuilder()。这将返回一个构建器，它与原始客户端共享相同的连接池、调度器和配置。在下面的示例中，我们使用 500 毫秒超时发起一个请求，使用 3000 毫秒超时发起另一个请求。

  private final OkHttpClient client = new OkHttpClient();

  public void run() throws Exception {
    Request request = new Request.Builder()
        .url("http://httpbin.org/delay/1") // 此 URL 的响应有 1 秒的延迟。
        .build();

    // 复制以自定义 OkHttp 以适应此请求。
    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);
    }

    // 复制以自定义 OkHttp 以适应此请求。
    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);
    }
  }

处理认证

OkHttp 可以自动重试未认证的请求。当响应为 401 未授权时，系统会要求 Authenticator 提供凭证。实现应该构建一个新的请求，其中包含缺失的凭证。如果没有凭证可用，返回 null 以跳过重试。

使用 Response.challenges() 获取任何认证挑战的方案和领域。在满足基本认证挑战时，使用 Credentials.basic(username, password) 来编码请求头。

  private val client = OkHttpClient.Builder()
    .authenticator(object : Authenticator {
      @Throws(IOException::class)
      override fun authenticate(route: Route?, response: Response): Request? {
        if (response.request.header("Authorization") != null) {
          return null // 放弃，我们已经尝试过认证。
        }

        println("正在为响应进行认证: $response")
        println("挑战: ${response.challenges()}")
        val credential = Credentials.basic("jesse", "password1")
        return response.request.newBuilder()
            .header("Authorization", credential)
            .build()
      }
    })
    .build()

fun run() {
  val request = Request.Builder()
      .url("http://publicobject.com/secrets/hellosecret.txt")
      .build()
}

为了避免在认证失败时进行多次重试，你可以返回 null 来放弃。例如，当这些凭证已经尝试过时，你可能希望跳过重试：

if (credential == response.request.header("Authorization")) {
  return null // 如果我们已经使用这些凭证失败过，就不要重试。
}

你也可以在达到应用程序定义的尝试限制时跳过重试：

if (response.responseCount >= 3) {
  return null // 如果我们失败了 3 次，就放弃。
}

上面的代码依赖于这个 responseCount 扩展值：

val Response.responseCount: Int
  get() = generateSequence(this) { it.priorResponse }.count()