- 介绍
- 使用注解描述HTTP请求
- API声明
- Url 操作
- 请求body
- 编码和Multipart
- Retrofit 配置
- 自定义转换器
介绍
Retrofit是一种封装好的网络请求客户端(android ,java)
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);
每个call都可以向远程Web服务器发出同步或异步HTTP请求。
Call<List<Repo>> repos = service.listRepos("octocat");
使用注解描述HTTP请求:
URL参数替换和查询参数支持
对象转换为请求正文(例如,JSON,协议缓冲区)
Multipart请求body和文件上传
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”) 调用<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)
请求body
@Body注解可以指定一个
使用@Body注解,一个对象可以被指定为一个HTTP请求body
@POST(“users / new”)
调用<User> createUser(@Body User user);
该对象也将使用Retrofit实例上指定的转换器进行转换。
如果没有添加转换器,则只能使用RequestBody。
编码和Multipart
方法上也可以声明为发送表单编码和Multipart数据的注解。 当方法上存在@FormUrlEncoded时,将发送表单编码的数据。每个键值对都使用包含名称的@Field和提供值的对象进行注解。
@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);
当方法上存在@Multipart时,将使用Multipart请求。零件使用@Part注解声明。
@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);
Multipart使用Retrofit的转换器,或者它们可以实现RequestBody来处理自己的序列化。
HEADER 操作
您可以使用@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)
如果每个request都需要添加公共@Header()则使用okHttp中的OkHttp interceptor.进行设置
同步,异步
调用实例可以同步或异步执行。每个实例只能使用一次,但调用clone()将创建一个可以使用的新实例。
在Android上,回调将在主线程上执行。在JVM上,回调将发生在执行HTTP请求的同一线程上
Retrofit 配置
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不支持的内容格式的API进行通信
或者您希望使用不同的库来实现现有的格式
你可以轻松地创建自己的转换器。创建一个扩展Converter.Factory类的类,并在构建适配器时传递实例。
引用:
Retrofit 官网 http://square.github.io/retrofit/#introduction