Retrofit

原文链接：http://square.github.io/retrofit/#api-declaration

英文不好，翻译只是为了让自己好好看一遍文章。

--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------

一、简介：

Retrofit把HTTP的API转成java的接口(接口的名称是GitHubService,方法是listRepos)：

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的方法，就相当于一次同步或异步的http请求：

Call<List<Repo>> repos = service.listRepos("octocat"); 上面的例子，使用注释描述http的请求：

1. 支持使用参数替代url的某个字段，支持查询参数。

2. 可以把对象转成http请求的body,如JSON，protocol buffers.

3. 多个请求body，和上传的功能

二、API声明

接口的方法和参数，阐明如何处理http请求。

1. 请求方法

接口的每一个方法都必须要有一个HTTP的注释，提供HTTP的方法和相对的url。有5个内置的HTTP方法的注释：GET, POST, PUT, DELETE 和 HEAD。（）括号里面的是相对url：

@GET("users/list")也可以在相对url中定义查询参数：

@GET("users/list?sort=desc") 2.URL说明 注释中的url可以使用占位符，再使用方法中的参数来代替。占位符的格式是： {name}，方法中，用于替代占位符的参数需要使用@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); 3.请求体body

可以使用类的对象作为请求体，需要添加@Body的注释：

@POST("users/new") Call<User> createUser(@Body User user);类的对象将被Retrofit定义的转换类转换成body参数。如果没有添加转换类，则只能使用RequestBody 4.表单和多个请求体 接口的方法可以发送表单和多个请求体数据。

使用@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来转换。 5.头部说明

可以使用@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);相同名字的头部不会被覆盖。如果两个头部名字相同，那他们都会被传到HTTP的头部中去。 头部也可以使用参数动态的更新。参数必须要有@Header的注释。如果参数为空，则头部被忽略。否则，会调用参数的toString方法，作为头部。 @GET("user") Call<User> getUser(@Header("Authorization") String authorization)

头部如果要加到每个请求中，可以使用OkHttp interceptor

6.同步和异步

Call的实例，可以被同步或异步调用。每个实例只可以被调用一次。但是，调用clone()的方法，又可以创建一个可以被调用的实例。

在android中，回调函数callbacks将会在UI的主线程中执行。在JVM中，回调将会和调用的方法同一个线程。

三、配置Retrofit

通过Retrofit，可以把API的接口转成可以调用的实例。Retrofit会有一个默认的配置，但是你也可以根据你的需要来配置。

1.转换器

默认情况下，Retrofit只能把http的body序列化成OkHttp的ResponseBody类型，并且@body的参数只接受ResponseBody的类型。

添加转换器可以支持其他的类型。下面提供了六个常用的序列号转换器：

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); 2.自定义转换器 如果需要Retrofit不支持的格式，如YAML, txt, 自定义类型等。 或者想用使用不同的库来实现存在的类型，你可以很轻易的创建一个转换器。只需要创建一个类，继承Converter.Factory。并在创建retrofit的时候赋值。