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'