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实例。

这个实例每次调用create方法都会创建一个同步或异步的远程网络服务。

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

使用注解来描述这个HTTP请求：

支持URL参数与数组参数。

支持request body添加Object参数（比如JSON,protocol buffers）

支持Multipart requeset body与文件上传。

注意：这一部分还在2.0 AIPs 后不断拓展。

声明

接口方法的注释与参数表明了该请求应如何处理。

请求方式

每一个请求都必须有描述请求方式及请求地址的HTTP注释。

@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("group/{id}/users")
Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);

 

复杂的数组参数可以通过Map组合实现。

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

 

REQUEST BODY

一个object对象可以通过 @Body 注释 来被指定为 request body。

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

 

这个object将会被Retrofit实例指定的的转换器所转换。如果Retrofit实例没有添加转换器，就只能使用 RequestBody。

 

FORM ENCODED AND MULTIPART

方法也可声明发送 form-encoded 和 multipart data。

当在方法中出现@FormUrlEncoded时会发送form-encoded data。每一个键值对通过 @Field 注释来提供name与object的值。

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

 

Multipart 部分使用Retrofit的一个转换器或者通过实现RequestBody去实现他们自己的序列化。

 

HEADER MANIPULATION

你可以通过使用@Headers注释为一个方法设置统一的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注释提供对应的参数。如果参数值为null，这个header将会被忽略。反之，将会使用参数的toString方法的输出作为参数的值。

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


使用 OkHttp interceptor为每一个请求添加相同的headers。

 

同步与异步

每一个请求的实例都可以同步或异步执行。每一个实例都只能被执行一次，但是可以通过执行clone()方法创建一个新的可使用的实例。

在Android里，回调将会主线程中执行。在jvm，回调将在执行http请求的线程中被执行。

 

Retrofit 是一个通过你的API接口转变成可调用对象的类。默认的，retrofit将会给你一个稳健的默认实现但也允许你进行定制。

 

转换器

默认的，Retrofit只能反序列化HTTP bodies到OkHttp's 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

这里有一个使用 GsonConvertreFactory 类去生成一个使用Gson进行反序列化的GitHubService实现类的例子。

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

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

 

自定义转换器

如果你需要与一个Retrofit不支持且使用content-format的API通信（如 YAML,txt,自定义格式）或者你希望同一个不同的库来实现已存在的格式，又可以简单的创建你自己的转换器。创建一个继承与 Converter.Factory的类并在创建适配器是将其实例传入。