Retrofit A type-safe HTTP client for Android and Java

原文：http://square.github.io/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可以同步或者异步访问远程服务器

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

使用注释来描述HTTP请求：

>支持URL参数替换和参数查询

>对象转换为请求正文（例如，JSON，协议缓冲区）

>多种请求体和文件上传

API声明

接口方法的注释和他的参数表明一个请求是如何处理的。

请求方法

每个方法都必须具有提供请求方法和相对URL的HTTP注释。 有五个内置注释：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("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）

可以指定一个对象用作具有@Body注释的HTTP请求体。

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

该对象也将使用在Retrofit实例上指定的转换器进行转换。 如果没有加入转换器，则只能使用RequestBody。

FORM ENCODED AND MULTIPART

也可以声明方法发送表单编码和多部分数据。

当方法中存在@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来处理自己的序列化。

HEADER MANIPULATION

您可以使用@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);

请注意，标题不会相互覆盖。 所有名称相同的标题都将包含在请求中。

可以使用@Header注释动态更新请求标头。 必须向@Header提供相应的参数。 如果值为null，则头将被省略。 否则，将调用toString的值，并使用结果。

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

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

SYNCHRONOUS VS. ASYNCHRONOUS

调用实例可以同步或异步地执行。 每个实例只能使用一次，但是调用clone（）将创建一个可以使用的新实例。

在Android上，回调将在主线程上执行。 在JVM上，回调将发生在执行HTTP请求的同一个线程上。

Retrofit Configuration

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

CONVERTERS

默认情况下，Retrofit只能将HTTP体反序列化为OkHttp ResponseBody类型，它只能接受@Body的RequestBody类型。

可以添加转换器来支持其他类型。 六个兄弟模块适应流行的序列化库，方便您使用。

• 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类生成使用Gson进行反序列化的GitHub Service接口的实现的示例。

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

CUSTOM CONVERTERS

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

Download

The source code to the Retrofit, its samples, and this website is available on GitHub.