Retrofit:类型安全的REST客户端for 安卓&Java

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请求:

  1. URL参数替换和query参数支持(就是?name=value&的意思)
  2. 自定进行POJO类转换(自动将响应转换成POJO类,GSON
  3. Multipart请求对象和文件上传支持(请求中包含多种媒体类型,如图片等)

 

. 请求方法:

支持GETPOSTPUTDELETEHEAD

  1. 正常的请求:

//请求方法:通过注解进行请求

//普通请求

@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);

  1. 特殊的请求:

//通过@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);

  1. 添加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();

 

  1. 同步异步和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);

. 返回对象类型:可以通过函数返回类型,CallbackObservable得到

//通过返回对象

@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 配置:可以默认配置也可以自定义

  1. 配置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);

  1. 返回数据类型的配置(可以支持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);

  1. 自定义转换器:去实现Converter接口皆可。
  2. 自定义同步请求的错误处理器: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,,5-wow.com

郑重声明:本站内容如果来自互联网及其他传播媒体,其版权均属原媒体及文章作者所有。转载目的在于传递更多信息及用于网络分享,并不代表本站赞同其观点和对其真实性负责,也不构成任何其他建议。