Retrofit for Java：适用于 Android 和 Java 的类型安全 HTTP 客户端

1. 什么是 Retrofit 以及为什么需要它

Retrofit 是一个强大且优雅的 Java（及 Android）库，它将 HTTP API 转换为 Java 接口。您无需手动编写创建 HTTP 请求、处理响应和解析 JSON 的样板代码，Retrofit 会为您完成所有这些工作。它会自动将您的 Java 对象序列化为 JSON（或其他格式）以发送到服务器，并将服务器响应反序列化回 Java 对象。这使得代码更加整洁、可读且易于维护。

为什么需要它？假设您需要编写一个与 REST API（例如 GitHub API、OpenWeatherMap 或您自己的服务器）通信的应用程序。如果没有 Retrofit，您将不得不使用像 HttpURLConnection 或 HttpClient 这样的低级类，手动构建 URL、设置标头、处理错误代码并解析 JSON。这不仅繁琐，而且容易出错。Retrofit 通过提供声明式 API 描述方式解决了这些问题。您只需创建一个带有方法的接口，并使用注解（例如 @GET、@POST），Retrofit 就会自动生成该接口的实现。

Retrofit 是 Android 和 Java 世界中处理 HTTP 的事实标准。它与 OkHttp（用于高效的网络操作）和 Gson/Moshi（用于 JSON 序列化）紧密集成。该库支持同步和异步请求、文件上传、身份验证、缓存以及许多其他功能。凭借其简单性和灵活性，Retrofit 被全球成千上万的应用程序和服务所使用。

2. 安装

Retrofit 通过 Maven Central 分发。要在您的 Java 项目（例如使用 Maven 或 Gradle）中使用它，请添加相应的依赖项。请注意，您还需要一个用于序列化的转换器（通常是 Gson 或 Moshi）以及 OkHttp 本身（Retrofit 在底层使用它）。

Maven (pom.xml)

<!-- Retrofit -->\n<dependency>\n    <groupId>com.squareup.retrofit2</groupId>\n    <artifactId>retrofit</artifactId>\n    <version>2.9.0</version>\n</dependency>\n\n<!-- Gson 转换器（用于 JSON） -->\n<dependency>\n    <groupId>com.squareup.retrofit2</groupId>\n    <artifactId>converter-gson</artifactId>\n    <version>2.9.0</version>\n</dependency>\n\n<!-- OkHttp（通常会自动引入，但可以显式指定版本） -->\n<dependency>\n    <groupId>com.squareup.okhttp3</groupId>\n    <artifactId>okhttp</artifactId>\n    <version>4.12.0</version>\n</dependency>

Gradle (build.gradle)

dependencies {\n    implementation 'com.squareup.retrofit2:retrofit:2.9.0'\n    implementation 'com.squareup.retrofit2:converter-gson:2.9.0'\n    implementation 'com.squareup.okhttp3:okhttp:4.12.0'\n}

重要提示： 版本可能会过时。请始终在官方网站或 Maven Central 仓库中检查最新版本。如果您使用其他转换器（例如 Moshi 或 Jackson），请将 converter-gson 替换为相应的工件（converter-moshi、converter-jackson）。

3. 快速入门——最小工作示例

让我们编写一个简单的示例，从 JSONPlaceholder（一个测试 REST API）服务器获取用户列表。

步骤 1：创建数据模型 (POJO)

// User.java\npublic class User {\n    private int id;\n    private String name;\n    private String username;\n    private String email;\n\n    // Getter 方法（Gson 必需）\n    public int getId() { return id;