Retrofit官方使用文档

介绍

Retrofit 将你的HTTP API转化为一个Java接口

public interface GitHubService {
  @GET("users/{user}/repos")
  Call<List<Repo>> listRepos(@Path("user") String user);
}

Retrofit 类会生成GitHubService接口的实现

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .build();

GitHubService service = retrofit.create(GitHubService.class);

生成的GitHubService能够通过 call 发送同步或一部的HTTP请求到远程的服务器上

Call<List<Repo>> repos = service.listRepos("octocat");

可以使用注解去描述一个HTTP请求:

  • URL参数替换与查询参数支持
  • 将对象转换为请求报文体(例如,JSON,protocol buffers)
  • 多媒体支持和文件上传

API声明

接口上的注解与其参数表明如何处理请求

请求方法

每一个方法必须有一个HTTP注解,这个注解需要提供请求方法和URL的相对路径。
有五种内置的注解,分别为:GET, POST, PUT, DELETE与HEAD。请求的相对URL也是在注解中指定的。

@GET("users/list")

你可以在URL中指定查询参数

@GET("users/list?sort=desc")

URL的操作

我们可以在方法中使用替换块或参数来动态更新请求URL。替换块是一个被{与}包围着的字母或数字组成的字符串。相应的参数必须使用 @Path 与相同的字符串注释起来。

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId);

GET中的查询参数也应该这样添加

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);

更复杂的GET查询参数可以使用Map进行添加

@GET("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);

请求体

可以使用 加了 @Body 注解的对象作为一个HTTP请求的请求体

@POST("users/new")
Call<User> createUser(@Body User user);

如果你在创建Retrofit对象时指定了转换器,则会使用该转换器转换对象为相应的请求体。如果没有指定转换器,则只能使用 RequestBody。

表单与多媒体数据

可以申明方法为发送表单数据或多媒体数据

可以在方法上使用 @FormUrlEncoded 注解来发送表单数据。表单中要提交的键值对数据可以通过该方法参数中的 @Field 注解指定。

@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);

可以在方法上使用 @Multipart 注解来发送多媒体数据。要提交的数据可以通过方法参数中的 @Part 注解指定。

@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

多媒体数据使用的转换器也是Retrofit转换器中的一个,当然,我们也可以自己实现RequestBody来处理数据的序列化。

请求头的操作

你可以通过使用 @Headers 注解来指定静态的请求头

@Headers("Cache-Control: max-age=640000")
@GET("widget/list")
Call<List<Widget>> widgetList();
@Headers({
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
})
@GET("users/{username}")
Call<User> getUser(@Path("username") String username);

注意:headers中的项不能被重写覆盖,所有拥有相同名字的headers都会被包含在请求中。

一个请求的header可以使用 @Header 注解进行动态的更新,当然,相关的参数也应该在 @Header 中提供。如果值为空的话,那个这个header就会被忽略。因此,值的 toString() 方法将会被调用,并且作为其header的值。

@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)

与查询参数类似,Map也可以被用在header中,用来指定复杂的header组合。

@GET("user")
Call<User> getUser(@HeaderMap Map<String, String> headers)

可以使用OkHttp拦截器指定需要添加到每个请求的请求头。

同步请求 VS 异步请求

Call 实例可以通过同步或异步的方式执行。每个实例本来应当只能被调用一次,但调用 clone() 方法则会创建一个新的可用的实例。
在Android中,回调函数将会通过主线程执行。但在JVM中,回调函数将会在调用HTTP请求的同一个线程中执行。

Retrofit配置

Retrofit是将API接口转换为可调用对象的类。默认情况下,Retrofit将为您的平台提供合理的默认值,但它允许自定义。

转换器

默认情况下,Retrofit只能将HTTP主体反序列化为OkHttp的ResponseBody类型,并且只能接受其RequestBody类型 @Body
当然,也可以体检其他类型的转换器。这里提供几个可用作转换器的比较流行序列化库

  • Gson: com.squareup.retrofit2:converter-gson
  • Jackson: com.squareup.retrofit2:converter-jackson
  • Moshi: com.squareup.retrofit2:converter-moshi
  • Protobuf: com.squareup.retrofit2:converter-protobuf
  • Wire: com.squareup.retrofit2:converter-wire
  • Simple XML: com.squareup.retrofit2:converter-simplexml
  • Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars

下面是使用GsonConverterFactory该类生成GitHubService接口实现的示例,该接口使用Gson进行反序列化。

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com")
    .addConverterFactory(GsonConverterFactory.create())
    .build();

GitHubService service = retrofit.create(GitHubService.class);

定制转换器

如果您需要与使用 Retrofit 不支持开箱即用的内容格式的API(例如YAML,txt,自定义格式)进行通信,或者您希望使用其他库来实现现有格式,则可以轻松创建你自己的转换器。创建一个扩展 Converter.Factory 的类,并在构建适配器时传入实例。

下载

MAVEN

<dependency>
  <groupId>com.squareup.retrofit2</groupId>
  <artifactId>retrofit</artifactId>
  <version>(insert latest version)</version>
</dependency>

GRADLE

implementation 'com.squareup.retrofit2:retrofit:(insert latest version)'
阅读更多

扫码向博主提问

somehow1002

非学,无以致疑;非问,无以广识
  • 擅长领域:
  • PHP
  • Java
  • MySQL
去开通我的Chat快问
换一批

没有更多推荐了,返回首页