retrofit2使用详解之入门

前言

       在本教程中，我们将了解Retrofit 的基础知识以和创建一个android HTTP client请求REST API。
 

1. Retrofit是什么?

Retrofit是一个类型安全的REST客户端，适用于android和Java开发应用。Retrofit可将HTTP 网络接口转换为Java接口。

Retrofit android 版使用非常简单。它本质上允许我们将API调用视为简单的Java方法调用，因此我们只定义要访问的URL和请求/响应参数的类型作为Java类。

整个网络调用+ JSON / XML解析完全由Retrofit处理（例如Gson用于JSON解析）。它允许向远程Web服务器发出同步或异步HTTP请求。

2. Retrofit 安装

我们的项目中要使用Retrofit 2，我们将在构建文件中包含以下依赖项。在本教程中，我们将以JSON格式发送和接收数据，因此我们也添加了converter-gson依赖项。
maven 方式：

$title(pom.xml)
<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>retrofit</artifactId>
    <version>2.6.1</version>
</dependency>
<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>converter-gson</artifactId>
    <version>2.6.1</version>
</dependency>

gradle 方式：

$title(build.gradle)
dependencies { 
    compile 'com.squareup.retrofit2:retrofit:2.6.1'
    compile 'com.squareup.retrofit2:converter-gson:2.6.1'
}

在Android应用程序中，我们必须启用Internet权限，因为Retrofit会对Internet上某个服务器上运行的API执行HTTP请求。

$title(AndroidManifest.xml)
<uses-permission android:name="android.permission.INTERNET"></uses-permission>

3. REST API建模

3.1. REST API 接口

使用Retrofit的下一步是对REST API建模，我们将会在应用程序中使用它。下面举例说明有一个这样的API可以免费使用

HTTP GET https://reqres.in/api/users/2
 
Response:
 
{
    "data": {
        "id": 2,
        "email": "janet.weaver@reqres.in",
        "first_name": "Janet",
        "last_name": "Weaver",
        "avatar": "https://s3.amazonaws.com/uifaces
                /faces/twitter/josephstein/128.jpg"
    }
}

3.2. 业务数据模型

假设我们只需要消费id，姓名和电子邮件字段，而不想使用头像字段。字段数量不匹配，Gson转换器并不会报错，他会解析我们模型中指定的字段。（国内的fastjson也一样效果）

$title(UserApiResponse.java)
public class UserApiResponse
{
    private User data;
 
    //Setters and getters
 
    public String toString() {
        return "UserApiResponse [data=" + data + "]";
    }
}

$title(User.java)
public class User
{
    private long id;
    private String first_name;
    private String last_name;
    private String email;
 
    //Setters and getters
 
    @Override
    public String toString() {
        return "User [id=" + id + ", "
            + "first_name=" + first_name + ", "
            + "last_name=" + last_name + ", "
            + "email=" + email + "]";
    }
}

3.3. 业务接口

现在，我们可以使用Retrofit注解来创建具有所需映射信息和请求/响应类的服务接口。

$title(UserService.java)
import retrofit2.Call;
import retrofit2.http.GET;
import retrofit2.http.Path;
 
public interface UserService {
 
    @GET("/api/users/{id}")
    public Call<UserApiResponse> getUser(@Path("id") long id);
 
}

• 我们可以使用适当的改造注释为每个HTTP方法：@GET，@POST，@PUT，@DELETE，@PATCH或@HEAD。
• 在方法注释中，我们应该指定REST资源的相对端点URL。在这种情况下，它是 - "/api/users/{id}"。
• 在方法声明中，我们必须将服务器所期望的数据返回到一个类型化的Retrofit Call< >类中。
• 在方法参数中，我们可以传递路径和查询参数，并在PUT / POST请求中请求正文。

4. Retrofit 2 实际使用

现在是时候使用create Retrofit REST客户端并进行实际的API调用。
在这个例子中，我们使用流畅的API与Retrofit.Builder和OkHttpClient来创建Retrofit实例。
我们提供API和转换器类型的基本URL。

$title(UserServiceClient.java)
import okhttp3.OkHttpClient;
import retrofit2.Call;
import retrofit2.Response;
import retrofit2.Retrofit;
import retrofit2.converter.gson.GsonConverterFactory;
$title(UserServiceClient.java) 
public class UserServiceClient
{
    public static void main(String[] args)
    {
        OkHttpClient.Builder httpClient = new OkHttpClient.Builder();
         
        Retrofit retrofit = new Retrofit.Builder()
          .baseUrl("https://reqres.in/")
          .addConverterFactory(GsonConverterFactory.create())
          .client(httpClient.build())
          .build();
         
        UserService service = retrofit.create(UserService.class);
         
        // Calling '/api/users/2'
        Call<UserApiResponse> callSync = service.getUser(2);
          
        try {
            Response<UserApiResponse> response = callSync.execute();
            UserApiResponse apiResponse = response.body();
            System.out.println(apiResponse);
        } catch (Exception ex) {
            ex.printStackTrace();
        }
    }
}

运行上面的程序，观察控制台中打印的输出。

$title(out)
UserApiResponse [data=User [
    id=2,
    first_name=Janet,
    last_name=Weaver,
    email=janet.weaver@reqres.in]]

在上面的例子中，我们已经进行了同步请求。我们将在接下来的教程中会讲解异步请求。

总结

在本教程中，我们了解了Retrofit 2并为REST客户端构建了一个使用JSON有效负载的hello world应用程序。我们还了解了Retrofit库的基础知识。

retrofit2

http://blog.xqlee.com/article/664.html