Retrofit框架的使用

Retrofit使用

写个笔记以后回顾,嘿嘿….

Retrofit作用就是方便的把数据自动封装成JAVA对象,把REST API返回的数据转化成JAVA对象.

背景:Square公司框架之一,内置okhttp框架

开源框架地址:https://github.com/square/retrofit 
英文文档官网:http://square.github.io/retrofit/ (英文好的童鞋可以直接看这个就OK,o(╯□╰)o); 
相关框架: 
RxJava:https://github.com/ReactiveX/RxJava 
(注:使用方法先参考http://blog.csdn.net/lzyzsd/article/details/41833541 这个是翻译的文章还可以) 
okhttp:https://github.com/square/okhttp 
(注:后续文章介绍)

---

好的进入正题:

Retrofit框架是用来请求数据的所以说主要分为两部分:1.发送请求 2.接收数据

使用的三个步骤:

1. 使用注解方式标注请求模板接口.
2. RestAdapter实例化请求接口(接口当然不能直接被实例化,这里内部是反射实现的代理).
3. 最后调用请求模板接口的方法获取数据.

下面贴上快速上手使用的代码:

//1.使用注解方式标注请求模板接口.
public interface GitHubService {
  @GET("/users/{user}/repos")//URL相对路径
  List<Repo> listRepos(@Path("user") String user);//Repo是JSON封装成的JAVA对象
}

//2.RestAdapter实例化(使用了建造者模式)
RestAdapter restAdapter = new RestAdapter.Builder()
    .setEndpoint("https://api.github.com")//URL域名
    .build();

GitHubService service = restAdapter.create(GitHubService.class);

//3.最后调用请求模板接口的方法.
List<Repo> repos = service.listRepos("octocat");//List<Repo>就是返回的已封装好的请求数据
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

注:上面使用了github API,直接返回的就是JSON数据,参考网站:

是不是感觉使用起来很简洁.结合RxAndroid使用效果更好.

下面说下详细使用:

一.请求部分:

这个框架的请求方式是采用的注解方式指明请求相对路径框架,然后参数指明具体内容 
请求方法有:GET, POST, PUT, DELETE, and HEAD(GET,POST最常用)

URL操作

{}中的表示待定参数,路径中的参数使用@Path(“XXX”)

@GET("/group/{id}/users")
List<User> groupList(@Path("id") int groupId);
 
 
1
2

@Query用于查询参数如同”?”作用

@GET("/group/{id}/users")
List<User> groupList(@Path("id") int groupId, @Query("sort") String sort);
 
 
1
2

@QueryMap用于有多个查询参数

@GET("/group/{id}/users")
List<User> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);
 
 
1
2

请求体(主要是用于@POST方式)

@POST("/users/new")
void createUser(@Body User user, Callback<User> cb);//Callback参数下面讲解
 
 
1
2

表单提交

@FormUrlEncoded注明是表单提交 
@Field注明表单中的键,方法的参数就是值了噻.

@FormUrlEncoded
@POST("/user/edit")
User updateUser(@Field("first_name") String first, @Field("last_name") String last);
 
 
1
2
3

---

下面部分不太常用可以跳过 
多部分提交 
@Multipart 多部分 
@PUT(“XXX”) 提交相对路径

@Multipart
@PUT("/user/photo")
User updateUser(@Part("photo") TypedFile photo, @Part("description") TypedString description);
 
 
1
2
3

请求头

@Headers(“”)请求头设置

@Headers("Cache-Control: max-age=640000")
@GET("/widget/list")
List<Widget> widgetList();
 
 
1
2
3

注:所有头都不会覆盖,同名的会一并提交 
若请求头要被添加到每一个请求,可以通过RequestInterceptor对象指定,如下:

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
2
3
4
5
6
7
8
9
10
11

---

Retrofit支持RxAndroid(RxJava家族中一员),可以优化异步操作.后续文章介绍

二:接收数据部分

有两种方式处理数据的方式 
方式一:操作框架已经转换好的数据 
1. 返回值为封装好的数据 
2. 无返回值,有Callback类型的回调参数 
3. 返回RxAndroid Observable对象

@GET("/users/list")
List<User> userList();

@GET("/users/list")
void userList(Callback<List<User>> cb);

@GET("/users/list")
Observable<List<User>> userList();

@GET("/users/list")
Response userList();
 
 
1
2
3
4
5
6
7
8
9
10
11

Callback使用说明

//List<GithubClient.Contributor>是请求返回的数据
  callback = new Callback<List<GithubClient.Contributor>>() {
            @Override
            public void success(List<GithubClient.Contributor> contributors, Response response) {
                Logger.d(GithubActivity.this.getClass().getCanonicalName(), contributors.size());
            }
            @Override
            public void failure(RetrofitError error) {
                Logger.d("Activity", error.getMessage());
            }
        };
        GithubClient.getContributors(callback);
 
 
1
2
3
4
5
6
7
8
9
10
11
12

方式二:直接操作原始HTTP 响应数据

@GET("/users/list")
Response userList();

@GET("/users/list")
void userList(Callback<Response> cb);

@GET("/users/list")
Observable<Response> userList();
 
 
1
2
3
4
5
6
7
8

RestAdapter配置

json转换器 
Retrofit默认使用GSON转换JSON数据 
若想自定义GSON转换器请参考:https://sites.google.com/site/gson/gson-user-guide 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
2
3
4
5
6
7
8
9
10
11

其实自定义个GSON转换器都不太常用,可能我们更加需要XML转换器 
框架源码里面示例实现了个SimpleXML转换器:github地址 
使用了Simple框架 
替换转换器代码

RestAdapter restAdapter = new RestAdapter.Builder()
    .setEndpoint("https://api.soundcloud.com")
    .setConverter(new SimpleXMLConverter())
    .build();

SoundCloudService service = restAdapter.create(SoundCloudService.class);
 
 
1
2
3
4
5
6

框架实现的转换器列表地址

自定义错误处理器 
需要实现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();
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14

注:被检测的错误,必须被声明在接口中,最好如同上面代码做的那样传递cause对象.

日志 
为了更详细查看请求和响应,你可以直接在RestAdapter调用日志级别方法,四个等级 
BASIC, FULL, HEADERS, and NONE.代码如下:

RestAdapter restAdapter = new RestAdapter.Builder()
    .setLogLevel(RestAdapter.LogLevel.FULL)
    .setEndpoint("https://api.github.com")
    .build();
 
 
1
2
3
4

注:这当然是调试阶段使用,后面记得删了.

JAR下载:地址 
Maven:

<dependency>
 <groupId>com.squareup.retrofit
 </groupId>
  <artifactId>retrofit</artifactId>
  <version>(insert latest version)</version>
</dependency>
 
 
1
2
3
4
5
6

Gradle

compile 'com.squareup.retrofit:retrofit:(insert latest version)'
 
 
1

自动使用okhttp框架 
maven

<dependency>
  <groupId>com.squareup.okhttp</groupId>
  <artifactId>okhttp</artifactId>
  <version>2.0.0</version>
</dependency>
 
 
1
2
3
4
5

gradle

compile 'com.squareup.okhttp:okhttp-urlconnection:2.0.0'
compile 'com.squareup.okhttp:okhttp:2.0.0'