2016年第一篇blog ,本来准备接着写设计模式系列相关的文章,但是开年之后微博、简书、开发群等众多平台时不时的都会提到这一个框架。刚好以前也大致了解过Retrofit,不过那时候应该是Retrofit1.x,现在Square已经发布了Retrofit2.0。至于1.x与2.0版本的区别,童鞋们可以参考这篇文章:Retrofit 2.0:有史以来最大的改进
本文暂不记录1.x与2.0版本的区别。只记录Retrofit2.0API的用法。后续提到的Retrofit,也是指的Retrofit2.0。
Retrofit是由Square研发。针对于Android和Java平台类型安全的Http客户端,网络服务是基于okhttp(okhttp也是由Square研发)。 简而言之Retrofit能帮开发者们极大简化网络请求和解析响应消息。
关于添加Retrofit等相关依赖?
使用Eclipse的童鞋,可以在maven中搜索“retrofit2”下载jar包,同时Retrofit的Github中也有下载链接https://github.com/square/retrofit
使用as的童鞋可以直接添加如下依赖
compile 'com.squareup.retrofit2:retrofit:2.0.0-beta4'
- 如果需要使用自动将JSON格式数据封装为实体对象的功能,需要添加如下依赖:
compile 'com.squareup.retrofit2:converter-gson:2.+'
- 如果需要支持RxJava,为Retrofit提供RxJava的适配器,需要添加如下依赖:
compile 'com.squareup.retrofit2:adapter-rxjava:2.+'
compile 'io.reactivex:rxandroid:1.1.0' //既然要支持RxJava,那么也需要添加RxJava框架的依赖
- 如果需要打印Retrofit网络请求和返回结果等日志信息,需要添加如下依赖(目前Retrofit2.0必须依靠okhttp提供的日志系统。关于日志,感谢开发群里“有人@我”童鞋提供的信息)
compile 'com.squareup.okhttp3:logging-interceptor:3.1.2'
如何使用Retrofit编写网络请求?
一般当我们Android客户端进行网络请求工作的时候,大部分做的事情无外乎“增删改查”操作,这里我也以这四种请求作为演示示例:
使用Retrofit需要面向接口编程,这里以Inteterface的形式先编写接口:
public interface RestUserApi {
@POST("user.do?action=createUser")
Call<ResponseBody> createUser(@Body RestUser user);
@POST("{module}.do?action=createUser")
Call<ResponseBody> createUser(@Path("module") String module, @Body RestUser user);
@POST("user.do?action=deleteUser")
Call<ResponseBody> deleteUser(@Query("username") String username);
@FormURLEncoded
@POST("user.do?action=updateUser")
Call<RestUser> updateUserVip(@Field("username") String username, @Field("isVip") boolean isVip);
@GET("user.do?action=findUser")
Observable<RestUser> findUser(@Query("username") String username);
@GET("user.do?action=findUserList")
Observable<List<RestUser>> findUserList(@QueryMap Map<String, Object> conditionMap);
}
上面有6个接口,分别是创建用户、修改用户、删除用户、查找用户操作,这6个接口也是用到了Retrofit提供的大部分常用API。
编写上面这些接口,使用了大量注解,下面先简单介绍下,后面会给出每种注解在URL或者服务器后台中接收到到请求时的表现情况:
@POST和@GET,表示网络请求类型,同时还有HEAD、PUT、DELETE、TRACE、CONNECT、OPTIONS5中类型。注解中的参数字符串(上面代码中的action=xxxUser大家可以忽视,因为后台服务器中使用SpringMvc框架)可以填写完整的URL,也可以单单指定URL中的路径部分(如果是这样,那么在构建retrofit对象的时候必须指定baseUrl,下文会讲解)。
@Body 标注的参数表示指定该参数作为Http请求的请求体,该参数(对象)将会被Retroofit实例指定的转换器转换,如果没有添加转换器,默认使用RequestBody。本例中使用GsonConverter
@Path(“str1”) 与“{str2}”符合配合使用。即使用@Path标注的参数用来替换服务器地址中使用“{}”括起来的字符串,同时str1必须与str2字符串相同,“{str2}”就像一个占位符。注意:@Path并不能替换URL路径中的字符串。
下面是一个完整的URL(一个完整的URL包括模式(或称协议)、服务器名称(或IP地址)、路径) http://www.hitomis.com/user.do?action=findUser&username="zuck" @Path 只能替换http://www.hitomis.com/user.do服务器名称中的内容,而并不能替换action=findUser&username="zuck"路径中的内容
@Query 表示查询参数,很简单,不多说
@QueryMap 表示组合在一起的查询参数作为一个Map集合对象
@FormURLEncoded和@Field一起使用,表示发送form-encoded数据,提交一个表单数据给服务器。众所周知,表单数据都是以键值对的形式存在。所以:@Field注解中的参数字符串为“键”而被@Field标注的参数值为 “值”
ok,现在定义了接口,那么如何通过Retrofit使用这些接口呢? 这里先创建retrofit对象。
public abstract class BaseService {
protected abstract String getBaseUrl();
protected Retrofit baseRetrofit() {
HttpLoggingInterceptor httpLoggingInterceptor = new HttpLoggingInterceptor();
httpLoggingInterceptor.setLevel(HttpLoggingInterceptor.Level.BODY);
OkHttpClient okHttpClient = new OkHttpClient.Builder()
.addInterceptor(httpLoggingInterceptor)
.build();
Retrofit retrofit = new Retrofit.Builder()
.baseUrl(getBaseUrl())
.client(okHttpClient)
.addConverterFactory(GsonConverterFactory.create())
.addCallAdapterFactory(RxJavaCallAdapterFactory.create())
.build();
return retrofit;
}
}
public class RestService extends BaseService{
private static final String BASE_REST_URL = "http://136.158.27.24:8080/";
@Override
protected String getBaseUrl() {
return BASE_REST_URL;
}
public RestUserApi createRestApi() {
return baseRetrofit().create(RestUserApi.class);
}
}
使用 Builder模式 去构造了一个retrofit对象,在构造的时候添加了java/Json转换器工厂,以及支持RxJava的适配器工厂和网络请求的客户端实例(这里只单纯需要OkHttp的输出日志功能),同时指定了baseUrl即“协议+服务器名称”。
有了retrofit对象,就可以使用retrofit去完成一些网络请求工作了
public class RestFragment extends Fragment implements View.OnClickListener{
//省略一些定义、初始化控件的代码
private RestUserApi restApi = new RestService().createRestApi();
@Override
public void onClick(View v) {
switch(v.getId()) {
case R.id.btn_create:
createUser();
break;
case R.id.btn_create_action:
createUserAction();
break;
case R.id.btn_delete:
deleteUser();
break;
case R.id.btn_update:
updateUser();
break;
case R.id.btn_find:
findUser();
break;
case R.id.btn_find_list:
findUserList();
break;
}
}
private void createUser() {
RestUser user = new RestUser();
user.setUsername("Hitomis");
user.setPassword("123456");
user.setAge(18);
user.setIsVip(false);
prompt(restApi.createUser(user));
}
private void createUserAction() {
RestUser user = new RestUser();
user.setUsername("Hitomis");
user.setPassword("123456");
user.setAge(18);
user.setIsVip(false);
prompt(restApi.createUser("user", user));
}
private void deleteUser() {
prompt(restApi.deleteUser("Hitmois"));
}
private void updateUser() {
Call<RestUser> call = restApi.updateUserVip("Hitomis", true);
call.enqueue(new Callback<RestUser>() {
@Override
public void onResponse(Call<RestUser> call, Response<RestUser> response) {
Log.d(tag, response.raw().request().url().url().toString());
Log.d(tag, response.body().toString());
}
@Override
public void onFailure(Call<RestUser> call, Throwable t) {
}
});
}
private void findUser() {
restApi.findUser("Hitomis")
.subscribeOn(Schedulers.newThread())
.observeOn(AndroidSchedulers.mainThread())
.subscribe(new Subscriber<RestUser>() {
@Override
public void onCompleted() {
}
@Override
public void onError(Throwable e) {
Log.d(tag, e.toString());
}
@Override
public void onNext(RestUser user) {
Log.d(tag, user.toString());
}
});
}
private void findUserList() {
Map<String, Object> conditions = new HashMap<>();
conditions.put("age", 18);
conditions.put("isVip", true);
restApi.findUserList(conditions)
.subscribeOn(Schedulers.newThread())
.observeOn(AndroidSchedulers.mainThread())
.flatMap((restUsers) -> Observable.from(restUsers))
.subscribe(new Subscriber<RestUser>() {
@Override
public void onCompleted() {
}
@Override
public void onError(Throwable e) {
Log.d(tag, e.toString());
}
@Override
public void onNext(RestUser user) {
Log.d(tag, user.toString());
}
});
}
private void prompt(Call<ResponseBody> call) {
call.enqueue(new Callback<ResponseBody>() {
@Override
public void onResponse(Call<ResponseBody> call, Response<ResponseBody> response) {
try {
Log.d(tag, response.raw().request().url().url().toString());
Log.d(tag, response.body().string());
} catch (IOException e) {
e.printStackTrace();
}
}
@Override
public void onFailure(Call<ResponseBody> call, Throwable t) {
Log.d(tag, t.toString());
}
});
}
}
从上面的代码中,可以看到,使用Retroift发起网络请求非常的简洁。
createUser()
只需传递一个User对象即可,符合面向对象的编程思维。接口中接受该User对象的参数使用了@Body去注解,那么在服务器后台中,怎么去获取该参数呢?
public void createUser(HttpServletRequest request, HttpServletResponse response) throws IOException {
System.out.println(readInputStream(request.getInputStream()));
JSONObject jsonObject = new JSONObject();
jsonObject.put("code", 100);
writeJSONObject(response, jsonObject);
}
/**
* 从文件输入流中读取字符串
*
* @param is
* @return
*/
public String readInputStream(InputStream is) {
try {
ByteArrayOutputStream baos = new ByteArrayOutputStream();
int len = 0;
byte[] buffer = new byte[1024];
while ((len = is.read(buffer)) != -1) {
baos.write(buffer, 0, len);
}
is.close();
baos.close();
byte[] result = baos.toByteArray();
// 解析result里面的字符串
return new String(result);
} catch (Exception e) {
e.printStackTrace();
return null;
}
}
通过@Body注解的参数,会将Java对象序列化到Http请求的请求体中,在后台通过request.getInputStream()方法可以获取请求的body流,通过读取该body流,即可获取客户端Retrofit传递过来的参数。
下面依次是客户端和服务器的日志
客户端
D/OkHttp: Content-Type: application/json; charset=UTF-8
D/OkHttp: Content-Length: 65
D/OkHttp: {"username":"Hitomis","password":"123456","isVip":false,"age":18}
D/OkHttp: <-- 200 OK http://136.158.27.24:8080/user.do?action=createUser (34ms)
D/OkHttp: {"code":100}
服务器端
{"username":"Hitomis","password":"123456","isVip":false,"age":18}
createUserAction()
与createUser()不同的是多了一个@Path注解的参数。这里看一下客户端日志就能明白@Path的作用了.
D/OkHttp: Content-Type: application/json; charset=UTF-8
D/OkHttp: Content-Length: 65
D/OkHttp: {"username":"Hitomis","password":"123456","isVip":false,"age":18}
D/OkHttp: <-- 200 OK http://136.158.27.24:8080/user.do?action=createUser (29ms)
D/OkHttp: {"code":100}
@POST("{module}.do?action=createUser")
Call<ResponseBody> createUser(@Path("module") String module, @Body RestUser user);
在第二个接口中,使用了“{module}”占位符,在使用该接口的时候传递了”user”字符串去替换了URL中的“{module}”。
服务器端日志同createUser()
deleteUser()
接口一个被@Query注解的参数,非常简单,给出客户端日志就能明白怎么回事
D/OkHttp: Content-Length: 0
D/OkHttp: <-- 200 OK http://136.158.27.24:8080/user.do?action=deleteUser&username=Hitmois (48ms)
D/OkHttp: {"code":100}
URL路径中明显发现拼接了“&username=Hitmois”这样一串字符串。在服务器端,使用
request.getParameter("username");
即可获取参数,这里说明下,只有通过@Body注解的参数,在后台需要通过request.getInputStream()去解析获取参数(原因已说明,这里不再赘述),其余的方式,都是通过request.getParameter(“paramsName”);获取,为节省文章篇幅,后面就不在赘述了。
updateUser()
该接口使用了@FormUrlEncoded和@Field
客户端日志
D/OkHttp: Content-Type: application/x-www-form-urlencoded
D/OkHttp: Content-Length: 27
D/OkHttp: username=Hitomis&isVip=true
D/OkHttp: <-- 200 OK http://136.158.27.24:8080/user.do?action=updateUser (18ms)
D/OkHttp: {"username":"Hitomis","password":"123456","age":18,"isVip":true}
从客户端日志当中可以发现请求的Content-Type为application/x-www-form-urlencoded,即表单请求类型。
findUser()
该接口支持了RxJava。对于玩转RxJava的童鞋,这无疑是一个好消息啊。通过RxJava可以非常方便的控制线程切换,以及组合多个REST调用,例如在创建用户的同时还需要上传用户照片,使用RxJava + Retrofit将变得so easy~
客户端日志
D/OkHttp: <-- 200 OK http://136.158.27.24:8080/user.do?action=findUser&username=Hitomis (26ms)
D/OkHttp: {"username":"Hitomis","password":"123456","age":18,"isVip":true}
*注意*
在使用RxJava + Retrofit时,添加观察者subscribe不推荐使用Action1匿名内部类。
private void findUser() {
restApi.findUser("Hitomis")
.subscribeOn(Schedulers.newThread())
.observeOn(AndroidSchedulers.mainThread())
.subscribe(new Action1<RestUser>() {
@Override
public void call(RestUser user) {
Log.d(tag, user.toString());
}
});
}
也就是上面的写法不推荐,因为忽视了OnError()回调,在通信异常比如服务器内部问题或者挂掉的时候,app会直接crash。
findUserList()
使用了@QueryMap,这个也很简单,直接给出客户端日志,就能明白
D/OkHttp: <-- 200 OK http://136.158.27.24:8080/user.do?action=findUserList&isVip=true&age=18 (91ms)
D/OkHttp: [{"username":"Hitomis","password":"123456","age":18,"isVip":true},{"username":"zuck","password":"654321","age":20,"isVip":false}]
在URL后面,将@QueryMap注解的参数集合对象中每个元素都拼接在了URL路径当中,好吧,@QueryMap就是这么简单。
以上是关于Retroift2.0Api使用的解析,因为目前自己也是处于不断摸索学习中。有什么纰漏还希望大家不吝指出。
关于使用Retrofit上传文件,由于时间问题还没有尝试。有过这方面经验的童鞋,快告诉我啊。