Retrofit 介绍

A type-safe REST client for Android and Java

Introduction

Retrofit将 REST API 转到 Java接口。

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

该RestAdapter类生成的GitHubService接口的实现。

RestAdapter restAdapter = new RestAdapter.Builder()
    .setEndpoint("https://api.github.com")
    .build();

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

对生成的GitHubService每个呼叫发出一个HTTP请求到远程Web服务器。

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

使用注解来形容HTTP请求：

• URL参数替代和查询参数的支持
• 对象转换请求体（例如，JSON，协议缓冲区）
• 多部分请求主体和文件上传

API Declaration

在接口方法和参数注释指示如何请求将被处理。

请求方法：

每个方法必须有一个HTTP标注，提供了请求方法和相对URL。有五个内置注解：GET，POST，PUT，DELETE和HEAD。中指定注释的资源的相对URL。

@GET("/users/list")

您也可以在URL中指定的查询参数。

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

URL处理:

请求的URL可以动态使用的方法替换块和参数进行更新。替换块是由{and}包围的字母数字字符串。相应的参数必须注明使用相同的字符串@Path。

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

查询参数也可以加入。

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

对于复杂的查询参数组合的Map都可以使用。

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

请求主体:

对象可以用作HTTP请求体与@Body注解来指定。

@POST("/users/new")
void createUser(@Body User user, Callback<User> cb);

对象也将使用RestAdapter的转换器进行转换。

FORM编码并MULTIPART:

方法也可以声明为发送形式编码的和多部分数据。
当@FormUrlEncoded存在于该方法的形式编码的数据被发送。每个key - value 对被注解为@Field包含名称和对象提供的值。

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

多部分请求时，使用@Multipart上存在的方法。部分使用的是@part注解来声明。

@Multipart
@PUT("/user/photo")
User updateUser(@Part("photo") TypedFile photo, @Part("description") TypedString description);

Multipart parts 使用RestAdapter的转换器，也可以实现TypedOutput处理自己的序列化。

处理HEADER:

您可以设置静态的头文件使用@Headers注释的方法。

@Headers("Cache-Control: max-age=640000")
@GET("/widget/list")
List<Widget> widgetList();

@Headers({
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
})
@GET("/users/{username}")
User getUser(@Path("username") String username);

请注意，headers 不互相覆盖。所有 headers 具有相同名称的将被包括在请求中。
请求头可以动态使用@Header注释进行更新。相应的参数必须提供给@Header。如果该值是空值，则首标将被省略。否则，的toString将被称为上的值，并将结果用。

@GET("/user")
void getUser(@Header("Authorization") String authorization, Callback<User> callback)

可使用RequestInterceptor指定需要被添加到每个请求头。下面的代码创建一个RequestInterceptor，将增加一个User-Agent头到每个请求。

RequestInterceptor requestInterceptor = new RequestInterceptor() {
  @Override
  public void intercept(RequestFacade request) {
    request.addHeader("User-Agent", "Retrofit-Sample-App");
  }
};

RestAdapter restAdapter = new RestAdapter.Builder()
  .setEndpoint("https://api.github.com")
  .setRequestInterceptor(requestInterceptor)
  .build();

同步VS.异步VS.可观测:

方法可为同步或异步执行声明。有返回类型的方法将同步执行。

@GET("/user/{id}/photo")
Photo getUserPhoto(@Path("id") int id);

异步执行需要的方法的最后一个参数是一个 Callback。

@GET("/user/{id}/photo")
void getUserPhoto(@Path("id") int id, Callback<Photo> cb);

在Android上，回调将在主线程上执行。对于桌面应用程序的回调将发生在该执行HTTP请求同一个线程。

Retrofit 还集成RxJava支持与rx.Observable的返回类型的方法

@GET("/user/{id}/photo")
Observable<Photo> getUserPhoto(@Path("id") int id);

Observable 请求是异步订阅和关于执行HTTP请求同一个线程观察。为了观察不同的线程（如Android的主线程）调用observeOn（Scheduler）对返回的Observable。

响应对象类型:

HTTP响应被自动转换为使用RestAdapter的转换器，它默认为JSON指定的类型。所需的类型被声明为方法返回类型或使用 Callback 或 Observable。

@GET("/users/list")
List<User> userList();

@GET("/users/list")
void userList(Callback<List<User>> cb);

@GET("/users/list")
Observable<List<User>> userList();

为了访问原始HTTP响应使用的响应类型。

@GET("/users/list")
Response userList();

@GET("/users/list")
void userList(Callback<Response> cb);

@GET("/users/list")
Observable<Response> userList();

RestAdapter配置

RestAdapter是通过您的API接口都变成可调用对象的类。默认情况下，改造会给你明智的默认平台，但它允许定制。

JSON的转换:

改造使用GSON默认为HTTP机构转换为从JSON。如果你想指定行为是GSON的默认值不同（如命名策略，日期格式，自定义类型），建设一个RestAdapter时，提供了新的实例GSON与你所期望的行为。请参阅GSON文档上定制的更多细节。

CUSTOM GSON转换器实例:

下面的代码创建一个新的GSON实例，将所有字段转换小写用下划线骆驼情况，反之亦然。它还会注册一个类型的适配器为Date类。这DateTypeAdapter将随时使用GSON遇到一个日期字段。

该gson实例作为参数传递给GsonConverter，这是一个包装类类型转换。

Gson gson = new GsonBuilder()
    .setFieldNamingPolicy(FieldNamingPolicy.LOWER_CASE_WITH_UNDERSCORES)
    .registerTypeAdapter(Date.class, new DateTypeAdapter())
    .create();

RestAdapter restAdapter = new RestAdapter.Builder()
    .setEndpoint("https://api.github.com")
    .setConverter(new GsonConverter(gson))
    .build();

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

对生成的GithubService每个调用将返回对象使用提供给RestAdapter的GSON实现转换。

内容格式AGNOSTIC:

除了JSON，改造可被构造为使用其他的内容格式。改造提供备用转换器的XML（使用simple）和Protocol Buffers的（使用的protobuf或Wire）。请参阅 retrofit-converters的完整列表改造转换器的目录。

下面的代码演示了如何使用SimpleXMLConverter与使用XML的API进行通信

RestAdapter restAdapter = new RestAdapter.Builder()
    .setEndpoint("https://api.soundcloud.com")
    .setConverter(new SimpleXMLConverter())
    .build();

SoundCloudService service = restAdapter.create(SoundCloudService.class);

自定义转换:

如果你需要使用一个内容格式，改造不支持开箱即用（如YAML，TXT，自定义格式）的API进行通信，或者你想使用一个不同的库来实现现有的格式，您可以轻松地创建你自己的转换器。创建实现转换器接口的类和构建适配器时传递一个实例。

自定义错误处理:

如果你需要自定义错误处理的请求，您可以提供自己的ErrorHandler。下面的代码演示了如何当一个响应返回一个HTTP 401状态码抛出一个自定义异常

class MyErrorHandler implements ErrorHandler {
  @Override public Throwable handleError(RetrofitError cause) {
    Response r = cause.getResponse();
    if (r != null && r.getStatus() == 401) {
      return new UnauthorizedException(cause);
    }
    return cause;
  }
}

RestAdapter restAdapter = new RestAdapter.Builder()
    .setEndpoint("https://api.github.com")
    .setErrorHandler(new MyErrorHandler())
    .build();

注意，如果返回的异常检查，它必须在界面方法中声明。我们建议您通过提供RetrofitError作为事业的任何新的异常你扔。

LOGGING:

如果您需要仔细看看在请求和响应，你可以轻松地添加日志记录级别与的LogLevel属性RestAdapter。可能的日志记录级别是BASIC, FULL, HEADERS, 和NONE。

下面的代码显示了添加的，将记录头，身，和元数据请求和响应一个完整的日志级别。

RestAdapter restAdapter = new RestAdapter.Builder()
    .setLogLevel(RestAdapter.LogLevel.FULL)
    .setEndpoint("https://api.github.com")
    .build();

这个记录可以通过调用相同.setLogLevel()方法，并提供不同的LogLevel值增加或在RestAdapter生命周期的任何一点变化。

下载

MAVEN：

<dependency>
  <groupId>com.squareup.retrofit</groupId>
  <artifactId>retrofit</artifactId>
  <version>1.9.0</version>
</dependency>

GRADLE：

compile 'com.squareup.retrofit:retrofit:1.9.0'

Retrofit至少需要Java 6中或Android 2.3。

与OKHTTP一体化：

当使用起来与改造OkHttp，OkHttp（1.6.0或更新版本）和OkHttp-的URLConnection现在需要。

MAVEN：

<dependency>
  <groupId>com.squareup.okhttp</groupId>
  <artifactId>okhttp</artifactId>
  <version>2.0.0</version>
</dependency>
<dependency>
  <groupId>com.squareup.okhttp</groupId>
  <artifactId>okhttp-urlconnection</artifactId>
  <version>2.0.0</version>
</dependency>

GRADLE：

compile 'com.squareup.okhttp:okhttp-urlconnection:2.0.0'
compile 'com.squareup.okhttp:okhttp:2.0.0'