Retrofit：类型安全的REST客户端for 安卓&Java
2014年5月5日 星期一
21:11
官网： http://square.github.io/retrofit/
GitHub地址： https://github.com/square/retrofit
JavaDocs地址： http://square.github.io/retrofit/javadoc/index.html
本随笔是对官网教程的一个翻译，放出来供大家参考！
大纲
@GET,@POST,@PUT,@DELETE,@HEAD
@Path :{id}
@Query :name=value
@QueryMap
@Body ：传对象
@FormUrlEncoded,@Field
@Multipart,@Part :TypedFile 发送文件
@Headers ,@Header
RequestInterceptor ：通过拦截器添加Header
Callback(void返回)，Observable：异步
返回Response
setConverter：配置Gson，自动以转换器
setErrorHandler：设置错误处理
概览：将你的请求API定义在一个Java 接口中：
|
public interface GitHubService { @GET("/users/{user}/repos") List<Repo> listRepos(@Path("user") String user); } |
然后通过RestAdapter类来生成一个该接口的实现。
|
RestAdapter restAdapter = new RestAdapter.Builder() .setEndpoint("https://api.github.com") .build();
GitHubService service = restAdapter.create(GitHubService.class); |
然后就可以调用了：
|
List<Repo> repos = service.listRepos("octocat"); |
一. 通过注解来进行HTTP请求：
- URL参数替换和query参数支持（就是?name=value&…的意思）
- 自定进行POJO类转换（自动将响应转换成POJO类，GSON）
- Multipart请求对象和文件上传支持（请求中包含多种媒体类型，如图片等）
二. 请求方法：
支持GET，POST，PUT，DELETE，HEAD
- 正常的请求：
|
//请求方法：通过注解进行请求 //普通请求 @GET("/users/list") //请求中可以直接加query parameter：sort=desc @GET("/users/list?sort=desc") //可以通过@Path注解和{name}语法替换参数:id @GET("/group/{id}/users") List<User> groupList(@Path("id") int groupId); //可以通过@Query添加请求参数:sort @GET("/group/{id}/users") List<User> groupList(@Path("id") int groupId, @Query("sort") String sort); //可以通过@QueryMap批量添加请求参数：options @GET("/group/{id}/users") List<User> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options); |
- 特殊的请求：
|
//通过@Body可以直接发送一个对象，通过RestAdapter进行转换 @POST("/users/new") void createUser(@Body User user, Callback<User> cb); //通过@FormUrlEncoded和@Field注解发送form-encoded data？TODO @FormUrlEncoded @POST("/user/edit") User updateUser(@Field("first_name") String first, @Field("last_name") String last); //Multipart请求通过@Multipart和@Part注解 @Multipart @PUT("/user/photo") User updateUser(@Part("photo") TypedFile photo, @Part("description") TypedString description); |
- 添加Header
|
//静态添加方式 //添加单个头部 @Headers("Cache-Control: max-age=640000") @GET("/widget/list") List<Widget> widgetList(); //@Headers多个头部信息：可以有重复的名字 @Headers({ "Accept: application/vnd.github.v3.full+json", "User-Agent: Retrofit-Sample-App" }) @GET("/users/{username}") User getUser(@Path("username") String username); //动态添加头部 //动态添加头部:authorization @GET("/user") void getUser(@Header("Authorization") String authorization, Callback<User> callback)
//添加所有信息 //如果想将头部加到所有的请求上，可以通过RequestIntercepter类。 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(); |
- 同步异步和rx.Observable
|
//有返回的方法是同步方法 @GET("/user/{id}/photo") Photo getUserPhoto(@Path("id") int id); //最后一个方法是Callback<T>的话就是异步请求（T是要返回的数据） @GET("/user/{id}/photo") void getUserPhoto(@Path("id") int id, Callback<Photo> cb); //Retrofit同时集成了R小Java去支持返回一个rx.Observable来支持异步请求 @GET("/user/{id}/photo") Observable<Photo> getUserPhoto(@Path("id") int id); |
三. 返回对象类型：可以通过函数返回类型，Callback，Observable得到
|
//通过返回对象 @GET("/users/list") List<User> userList(); //通过Callback @GET("/users/list") void userList(Callback<List<User>> cb); //通过Observable @GET("/users/list") Observable<List<User>> userList(); |
可以返回原生的Http Response：通过返回Response
|
@GET("/users/list") Response userList();
@GET("/users/list") void userList(Callback<Response> cb);
@GET("/users/list") Observable<Response> userList(); |
四. RestAdapter 配置：可以默认配置也可以自定义
- 配置Gson：自定义GSON实例的例子
|
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); |
- 返回数据类型的配置(可以支持XML)：默认是JSON，也可以定义Convertor去支持xml等其他返回数据格式（如默认还有一个SimpleXMLConverter）
|
RestAdapter restAdapter = new RestAdapter.Builder() .setEndpoint("https://api.soundcloud.com") .setConverter(new SimpleXMLConverter()) .build();
SoundCloudService service = restAdapter.create(SoundCloudService.class); |
- 自定义转换器：去实现Converter接口皆可。
- 自定义同步请求的错误处理器：ErrorHandler
|
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(); |
Maven集成：
|
<dependency> <groupId>com.squareup.retrofit</groupId> <artifactId>retrofit</artifactId> <version>1.5.0</version> </dependency> |