Retrofit+rxjava的使用

用法介绍

创建API接口

在retrofit中通过一个Java接口作为http请求的api接口。

//定以接口
public interface GitHubService {
  @GET("users/{user}/repos")
  Call<List<Repo>> listRepos(@Path("user") String user);
}

创建retrofit实例

/**获取实例*/
Retrofit retrofit = new Retrofit.Builder()
    //设置OKHttpClient,如果不设置会提供一个默认的
    .client(new OkHttpClient())
    //设置baseUrl
    .baseUrl("https://api.github.com/")
    //添加Gson转换器
    .addConverterFactory(GsonConverterFactory.create())
    .build();

注： 
1.retrofit2.0后：BaseUrl要以/结尾；@GET 等请求不要以/开头；@Url: 可以定义完整url，不要以 / 开头。 
2.addConverterFactory提供Gson支持，可以添加多种序列化Factory，但是GsonConverterFactory必须放在最后,否则会抛出异常。

调用API接口

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

//同步请求
//https://api.github.com/users/octocat/repos
Call<List<Repo>> call = service.listRepos("octocat");
try {
     Response<List<Repo>> repos  = call.execute();
} catch (IOException e) {
     e.printStackTrace();
}

//不管同步还是异步，call只能执行一次。否则会抛 IllegalStateException
Call<List<Repo>> clone = call.clone();

//异步请求
clone.enqueue(new Callback<List<Repo>>() {
        @Override
        public void onResponse(Response<List<Repo>> response, Retrofit retrofit) {
            // Get result bean from response.body()
            List<Repo> repos = response.body();
            // Get header item from response
            String links = response.headers().get("Link");
            /**
            * 不同于retrofit1 可以同时操作序列化数据javabean和header
            */
        }

        @Override
        public void onFailure(Throwable throwable) {
            showlog(throwable.getCause().toString());   
        }
});

取消请求

我们可以终止一个请求。终止操作是对底层的httpclient执行cancel操作。即使是正在执行的请求，也能够立即终止。

call.cancel();

retrofit注解

• 方法注解，包含@GET、@POST、@PUT、@DELETE、@PATH、@HEAD、@OPTIONS、@HTTP。
• 标记注解，包含@FormUrlEncoded、@Multipart、@Streaming。
• 参数注解，包含@Query、@QueryMap、@Body、@Field，@FieldMap、@Part，@PartMap。
• 其他注解，包含@Path、@Header、@Headers、@Url。

(1)一般的get请求

public interface IWeatherGet {
    @GET("GetMoreWeather?cityCode=101020100&weatherType=0")
    Call<Weather> getWeather();
}

可以看到有一个getWeather(）方法，通过@GET注解标识为get请求，@GET中所填写的value和baseUrl组成完整的路径，baseUrl在构造retrofit对象时给出。

Retrofit retrofit = new Retrofit.Builder()
        /**http://weather.51wnl.com/weatherinfo/GetMoreWeather?cityCode=101020100&weatherType=0*/
        //注意baseurl要以/结尾
                .baseUrl("http://weather.51wnl.com/weatherinfo/")
                .addConverterFactory(GsonConverterFactory.create())
                .build();
IWeatherGet weather = retrofit.create(IWeatherGet.class);
Call<Weather> call = weather.getWeather();
call.enqueue(new Callback<Weather>() {
    @Override
    public void onResponse(Response<Weather> response, Retrofit retrofit) {
        Weather weather = response.body();
        WeatherInfo weatherinfo = weather.weatherinfo;
        showlog("weather="+weatherinfo.toString());
    }

@Override
    public void onFailure(Throwable throwable) {
        showlog(throwable.getCause().toString());       
    }
});

（2）动态url访问@PATH

上面说的@GET注解是将baseUrl和@GET中的value组成完整的路径。有时候我们可以将路径中某个字符串设置为不同的值来请求不同的数据，这时候怎么办呢？ 
譬如：

//用于访问上海天气
http://weather.51wnl.com/weatherinfo/GetMoreWeather?cityCode=101020100&weatherType=0
//用于访问上海人口（这里只是假设，其实这个url并不能返回json）
http://weather.51wnl.com/weatherinfo/GetMorePeople?cityCode=101010100&weatherType=0

即通过不同的请求字符串访问不同的信息，返回数据为json字符串。那么可以通过retrofit提供的@PATH注解非常方便的完成上述需求。

public interface IWeatherPath {
    @GET("{info}?cityCode=101020100&weatherType=0")
    Call<Weather> getWeather(@Path("info") String info);
}

可以看到我们定义了一个getWeather方法，方法接收一个info参数，并且我们的@GET注解中使用{info}?cityCode=101020100&weatherType=0声明了访问路径，这里你可以把{info}当做占位符，而实际运行中会通过@PATH(“info”)所标注的参数进行替换。

Retrofit retrofit = new Retrofit.Builder()
                .baseUrl("http://weather.51wnl.com/weatherinfo/")
                .addConverterFactory(GsonConverterFactory.create())
                .build();
IWeatherPath weather = retrofit.create(IWeatherPath.class);
Call<Weather> call = weather.getWeather("GetMoreWeather");
call.enqueue(new Callback<Weather>() {
    @Override
    public void onResponse(Response<Weather> response, Retrofit retrofit) {
        Weather weather = response.body();
        WeatherInfo weatherinfo = weather.weatherinfo;
        showlog("weather="+weatherinfo.toString());
    }

    @Override
    public void onFailure(Throwable throwable) {
        showlog(throwable.getCause().toString());       
    }
});

（3）查询参数的设置@Query@QueryMap

文章开头提过，retrofit非常适用于restful url的格式，那么例如下面这样的url：

//用于访问上海天气
http://weather.51wnl.com/weatherinfo/GetMoreWeather?cityCode=101020100&weatherType=0
//用于访问北京天气
http://weather.51wnl.com/weatherinfo/GetMoreWeather?cityCode=101010100&weatherType=0

即通过传参方式使用不同的citycode访问不同城市的天气，返回数据为json字符串。我们可以通过@Query注解方便的完成，我们再次在接口中添加一个方法：

public interface IWeatherQuery {
    @GET("GetMoreWeather")
    Call<Weather> getWeather(@Query("cityCode") String cityCode, @Query("weatherType") String weatherType);
}

/**省略retrofit的构建代码*/
Call<Weather> call = weather.getWeather("101020100", "0");
//Call<Weather> call = weather.getWeather("101010100", "0");
/**省略call执行相关代码*/

当我们的参数过多的时候我们可以通过@QueryMap注解和map对象参数来指定每个表单项的Key，value的值，同样是上面的例子，还可以这样写：

public interface IWeatherQueryMap {
    @GET("GetMoreWeather")
    Call<Weather> getWeather(@QueryMap Map<String,String> map);
}

//省略retrofit的构建代码
Map<String, String> map = new HashMap<String, String>();
map.put("cityCode", "101020100");
map.put("weatherType", "0");
Call<Weather> call = weather.getWeather(map);
//省略call执行相关代码

这样我们就完成了参数的指定，当然相同的方式也适用于POST，只需要把注解修改为@POST即可。 
注：对于下面的写法：

@GET("GetMoreWeather?cityCode={citycode}&weatherType=0")
Call<Weather> getWeather(@Path("citycode") String citycode);

乍一看可以啊，实际上运行是不支持的~估计是@Path的定位就是用于url的路径而不是参数，对于参数还是选择通过@Query来设置。

（4）POST请求体方式向服务器传入json字符串@Body

我们app很多时候跟服务器通信，会选择直接使用POST方式将json字符串作为请求体发送到服务器，那么我们看看这个需求使用retrofit该如何实现。

public interface IUser {
 @POST("add")
 Call<List<User>> addUser(@Body User user);
}

/省略retrofit的构建代码
 Call<List<User>> call = user.addUser(new User("watson", "male", "28"));
//省略call执行相关代码

可以看到其实就是使用@Body这个注解标识我们的参数对象即可，那么这里需要考虑一个问题，retrofit是如何将user对象转化为字符串呢？将实例对象根据转换方式转换为对应的json字符串参数，这个转化方式是GsonConverterFactory定义的。

对应okhttp，还有两种requestBody，一个是FormBody，一个是MultipartBody，前者以表单的方式传递简单的键值对，后者以POST表单的方式上传文件可以携带参数，retrofit也二者也有对应的注解，下面继续~

（5）表单的方式传递键值对@FormUrlEncoded + @Field@FieldMap

这里我们模拟一个登录的方法，添加一个方法：

public interface IUser {
    @FormUrlEncoded
    @POST("login")   
    Call<User> login(@Field("username") String username, @Field("password") String password);
}

//省略retrofit的构建代码
Call<User> call = user.login("watson", "123");
//省略call执行相关代码

看起来也很简单，通过@POST指明url，添加FormUrlEncoded，然后通过@Field添加参数即可。 
当我们有很多个表单参数时也可以通过@FieldMap注解和Map对象参数来指定每个表单项的Key，value的值。

public interface IUser {
    @FormUrlEncoded
    @POST("login")   
    Call<User> login(@FieldMap Map<String,String> fieldMap);
}

//省略retrofit的构建代码
Map<String, String> propertity = new HashMap<String, String>();
positories.put("name", "watson");
positories.put("password", "123");
Call<User> call = user.login(propertity);
//省略call执行相关代码

（6）文件上传@Multipart + @Part@PartMap

涉及到操作硬盘文件，首先需要添加权限：

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

1.下面先看一下单文件上传，依然是再次添加个方法：

public interface IUser {
    @Multipart
    @POST("register")
    Call<User> registerUser(@Part MultipartBody.Part photo, @Part("username") RequestBody username, @Part("password") RequestBody password);
}

这里@MultiPart的意思就是允许多个@Part了，我们这里使用了3个@Part，第一个我们准备上传个文件，使用了MultipartBody.Part类型，其余两个均为简单的键值对。

File file = new File(Environment.getExternalStorageDirectory(), "icon.png");
RequestBody photoRequestBody = RequestBody.create(MediaType.parse("image/png"), file);
/**第一个参数name与文件一一对应，如果多文件上传，每个文件name不能一样**/
MultipartBody.Part photo = MultipartBody.Part.createFormData("photos", "icon.png", photoRequestBody);

Call<User> call = user.registerUser(photo, RequestBody.create(null, "abc"), RequestBody.create(null, "123"));

这里感觉略为麻烦。不过还是蛮好理解~~多个@Part，每个Part对应一个RequestBody。

注：这里还有另外一个方案也是可行的：

public interface ApiInterface {
        @Multipart
        @POST ("/api/Accounts/editaccount")
        Call<User> editUser (@Header("Authorization") String authorization, @Part("photos\"; filename=\"icon.png") RequestBody file , @Part("FirstName") RequestBody fname, @Part("Id") RequestBody id);
}

这个value设置的值不用看就会觉得特别奇怪，然而却可以正常执行，原因是什么呢？ 
当上传key-value的时候，实际上对应这样的代码：

builder.addPart(Headers.of("Content-Disposition", "form-data; name=\"" + key + "\""), RequestBody.create(null, params.get(key)));

也就是说，我们的@Part转化为了

Headers.of("Content-Disposition", "form-data; name=\"" + key + "\"")

这么一看，很随意，只要把key放进去就可以了。但是，retrofit2并没有对文件做特殊处理，文件的对应的字符串应该是这样的

Headers.of("Content-Disposition", "form-data; name="photos";filename="icon.png"");

与键值对对应的字符串相比，多了个\”; filename=\”icon.png，就因为retrofit没有做特殊处理，所以你现在看这些hack的做法

@Part("photos\"; filename=\"icon.png")
==> key = photos\"; filename=\"icon.png

form-data; name=\"" + key + "\"
拼接结果：==>
form-data; name="photos"; filename="icon.png"

因为这种方式文件名写死了，我们上文使用的的是@Part MultipartBody.Part file,可以满足文件名动态设置。

2.如果是多文件上传呢？

public interface IUser {
     @Multipart
     @POST("register")
     Call<User> registerUser(@PartMap Map<String, RequestBody> params, @Part("password") RequestBody password);
}

这里使用了一个新的注解@PartMap，这个注解用于标识一个Map，Map的key为String类型，代表上传的键值对的key(与服务器接受的key对应),value即为RequestBody，有点类似@Part的封装版本。

Map<String, RequestBody> map = new HashMap<>(String, RequestBody);
File file = new File(Environment.getExternalStorageDirectory(), "local.png");
RequestBody photo = RequestBody.create(MediaType.parse("image/png", file);
map.put("photo1\"; filename=\"local.png", photo);
File file = new File(Environment.getExternalStorageDirectory(), "local2.png");
RequestBody photo2 = RequestBody.create(MediaType.parse("image/png", file2);
map.put("photo2\"; filename=\"local2.png", photo2);
map.put("username",  RequestBody.create(null, "abc"));

Call<User> call = user.registerUser(map, RequestBody.create(null, "123"));

可以看到，可以在Map中put进一个或多个文件，键值对等，当然你也可以分开，单独的键值对也可以使用@Part，这里又看到设置文件的时候，相对应的key很奇怪，例如上例”photo1\”; filename=\”local.png”,前面的photo1就是与服务器对应的key，后面filename是服务器得到的文件名，ok，参数虽然奇怪，但是也可以动态的设置文件名，不影响使用。

总结一下，上传多文件几种方式： 
（1）

    @Multipart
    @POST(HttpConstant.Upload)
    Single<EditUploadImageResponse> uploadImages(@Part() List<MultipartBody.Part> partList);

    public Single<EditUploadImageResponse> uploadImages(ArrayList<ImageItem> images) {
        List<MultipartBody.Part> partList = new ArrayList<>(images.size());
        for (ImageItem item : images) {
            File file = new File(item.path);
            // 创建RequestBody，用于封装构建RequestBody
            String format = FileUtil.getFileFormat(item.path);
            RequestBody requestBody  = RequestBody.create(MediaType.parse("image/"+format), file);
            /** 创建MultipartBody.Part, 第一个参数name必须与文件一一对应**/
            MultipartBody.Part part = MultipartBody.Part.createFormData(file.getName(), file.getName(), requestBody);
            partList.add(part);
        }
        return getRetrofit(IEditApi.class, HttpConstant.BaseUploadUrl).uploadImages(partList);
    }

（2）

    @Multipart
    @POST(HttpConstant.Upload)
    Single<EditUploadImageResponse> uploadImages(@PartMap Map<String, RequestBody> params);

    public Single<EditUploadImageResponse> uploadImagesWithProgress(ArrayList<ImageItem> images) {
        Map<String, RequestBody> map = new HashMap<>(images.size());
        for (ImageItem item : images) {
            File file = new File(item.path);
            // 创建RequestBody，用于封装构建RequestBody
            String format = FileUtil.getFileFormat(item.path);
            RequestBody requestBody  = RequestBody.create(MediaType.parse("image/"+format), file);
            map.put(file.getName() + "\"; filename=\""+ file.getName(), requestBody);
        }
        return getRetrofit(IEditApi.class, HttpConstant.BaseUploadUrl).uploadImages(map);
    }

（3）

    @POST(HttpConstant.Upload)
    Single<EditUploadImageResponse> uploadImages(@Body MultipartBody multipartBody);

    public Single<EditUploadImageResponse> uploadImageWithMultipartBody(ArrayList<ImageItem> images) {
        MultipartBody.Builder muBuilder = new MultipartBody.Builder();
        for (int i=0; i<images.size(); i++) {
            File file = new File(images.get(i).path);
            String format = FileUtil.getFileFormat(images.get(i).path);
            RequestBody requestBody = RequestBody.create(MediaType.parse("image/"+format), file);
            muBuilder.addFormDataPart(file.getName(),file.getName(), requestBody);
        }
        muBuilder.setType(MultipartBody.FORM);
        MultipartBody multipartBody = muBuilder.build();
        return getRetrofit(IEditApi.class, HttpConstant.BaseUploadUrl).uploadImages(multipartBody);
    }

可以参考文章Retrofit2 multpart多文件上传详解。