Retrofit
A type-safe HTTP client for Android and Java
简介
Retrofit把Http API 当成一个interface
public interface GitHubService {
@Get("users/{user]/repos")
Call<List<Repo>> listRepos(@Path("user") String user);
}
然后Retrofit通过create获得一个GitHubService接口的一个示例。
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com")
.build();
GitHubService service = retrofit.create(GitHubService.class);
来自创建的GitHubService的每个调用都可以向远程Web服务器发出同步或异步HTTP请求。
Call<List<Repo>> repos = service.listRepos("octocat");
使用java的注解去描述HTTP请求:
- Url参数可替换,查询参数支持
- 对象也已转化成请求体(例如JSON,协议缓冲)
- 多块请求体,文件上传
API声明
接口方法和它的参数的注解表明了将如何处理http请求
请求方法
每个方法都必须有个提供请求方法的HTTP注解和相关的URL,总共有五个内置的注解(GET,POST,PUT,DELETE,HEAD)
@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);
请求体
可以指定一个对象作为HTTP的请求体,只是不要忘了添加@Body注解。
@POST("users/new")
Call<User> createUser(@Body User user);
该对象也将使用Retrofit实例上指定的转换器进行转换。如果没有添加转换器,则只能使用RequestBody。
当方法上存在@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来处理自己的序列化。
头部请求
您可以使用@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拦截器指定。
同步和异步
调用实例可以同步或异步执行。每个实例只能使用一次,但调用clone()将创建一个可以使用的新实例。
在Android上,回调将在主线程上执行。在JVM上,回调将发生在执行HTTP请求的同一线程上。
Retrfit配置
Retrofit是将API接口转换为可调用对象的类。默认情况下,Retrofit将为您的平台提供正常默认值,但允许自定义。
转换器
默认情况下,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类来生成GitHubService接口的实现的示例,该接口使用Gson进行反序列化
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com")
.addConverterFactory(GsonConverterFactory.create())
.build();
GitHubService service = retrofit.create(GitHubService.class);
自定义转换器
如果您需要与使用Retrofit不支持开箱即用的内容格式(例如YAML,txt,自定义格式)的API进行通信,或者希望使用其他库来实现现有格式,则可以轻松创建你自己的转换器。创建一个扩展Converter.Factory类的类,并在构建适配器时传递实例。
下载
Retrofit的源码和样例可以在GitHub上下载,[点击下载源码](http://github.com/square/retrofit)
MAVEN
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>retrofit</artifactId>
<version>(insert latest version)</version>
</dependency>
GRADLE
compile 'com.squareup.retrofit2:retrofit:(insert latest version)'
Retrofit需要至少Java 7或Android 2.3。
代码混淆
如果在项目中使用Proguard,请在配置中添加以下行:
# Platform calls Class.forName on types which do not exist on Android to determine platform.
-dontnote retrofit2.Platform
# Platform used when running on RoboVM on iOS. Will not be used at runtime.
-dontnote retrofit2.Platform$IOS$MainThreadExecutor
# Platform used when running on Java 8 VMs. Will not be used at runtime.
-dontwarn retrofit2.Platform$Java8
# Retain generic type information for use by reflection by converters and adapters.
-keepattributes Signature
# Retain declared checked exceptions for use by a Proxy instance.
-keepattributes Exceptions