介绍
将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的每个回调都可以向远程webserver发出同步或异步HTTP请求
Call<List<Repo>> repos = service.listRepos("octocat");
使用注释来描述HTTP请求:
- URL参数替换和查询参数支持
- 对象转换到请求体(例如:、JSON、协议缓冲区)
- 多部分请求主体和文件上传
API声明
接口方法及其参数的注释说明了如何处理请求
请求方法
每个方法都必须有一个HTTP注释,它提供了请求方法和相对URL。有五个内置的注释: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);
请求体
可以将对象指定为使用@Body
注释的HTTP请求体
@POST("users/new")
Call<User> createUser(@Body User user);
该对象还将使用在改进实例上指定的转换器进行转换。如果没有添加转换器,则只能使用RequestBody
FORM ENCODED 和 MULTIPART
在方法上还可以声明发送form-encoded
和multipart
在方法上注释@FormUrlEncoded
时发送Form-encoded
数据。每个键值对都带有@Field
,其中包含名称和提供值的对象
@FormUrlEncoded @POST("user/edit") Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);
当@Multipart
出现在方法上时,将使用Multipart
请求。part
使用@Part
注释声明
@Multipart @PUT("user/photo") Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);
Multipart
使用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
注释动态更新请求报头。必须向@Header
提供相应的参数。如果该值为空,则将省略头。否则,将调用toString
值,并使用结果
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
需要添加到每个请求的头可以使用OkHttp
拦截器指定
同步 vs 异步
Call实例可以同步或异步执行。每个实例只能使用一次,但是调用clone()将创建一个可以使用的新实例。
在Android上,回调将在主线程上执行。在JVM上,回调将发生在执行HTTP请求的同一线程上
Retrofit配置
Retrofit是通过将API接口转化为可调用对象的类。默认情况下,Retrofit将使您的平台有正常的默认值,但它允许定制
Converter
默认情况下,Retrofit
只能将HTTP主体反序列化为OkHttp
的ResponseBody
类型,它只能接受@Body
的请求体类型可以添加转换器以支持其他类型。六个兄弟模块为您的方便调整流行的序列化库
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);
如果您在项目中使用ProGuard,请在配置中添加以下几行
# Platform calls Class.forName on types which do not exist on Android to determine platform. -dontnote retrofit2.Platform # 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