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> |
Retrofit:类型安全的REST客户端for 安卓&Java