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请求对象和文件上传支持（请求中包含多种媒体类型，如图片等）

 

二. 请求方法：

支持GET，POST，PUT，DELETE，HEAD

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

2. 特殊的请求：

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

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

 

4. 同步异步和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 配置：可以默认配置也可以自定义

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

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

3. 自定义转换器：去实现Converter接口皆可。
4. 自定义同步请求的错误处理器：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>