Retrofit用法详解

一、基础介绍

1、定义Java形式的HTTP API接口

public interface BlueService {
   @GET("book/search")
   Call getSearchBooks(@Query("q") String name, 
        @Query("tag") String tag, @Query("start") int start, 
        @Query("count") int count);
}

2、实现GitHubService接口

Retrofit retrofit = new Retrofit.Builder()
   .baseUrl("https://api.douban.com/v2/")
   .addConverterFactory(GsonConverterFactory.create())
   .build();

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

3、请求

Call call = mBlueService.getSearchBooks("小王子", "", 0, 3);

• 同步请求

BookSearchResponse response = call.execute().body();

• 异步请求

call.enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response){
        asyncText.setText("异步请求结果: " + response.body().books.get(0).altTitle);
    }

    @Override
    public void onFailure(Call call, Throwable t) {

    }
});

---

二、引入相关包

compile 'com.squareup.retrofit2:retrofit:2.1.0'
compile 'com.squareup.retrofit2:converter-gson:2.1.0'
compile 'com.squareup.retrofit2:adapter-rxjava:2.1.0'

---

三、注解

Retrofit 共22个注解，根据功能大概分为三类：

• 请求方法类
• 标记类
• 参数类

1、请求方法类

序号	名称
1	GET
2	POST
3	PUT
4	DELETE
5	PATCH
6	HEAD
7	OPTIONS
8	HTTP

• 序号 1 ~ 7

  分别对应 HTTP 的请求方法；
  接收一个字符串表示接口 path ，与 baseUrl 组成完整的 Url；
  可以不指定，结合 @Url 注解使用；
  url 中可以使用变量，如 {id} ，并使用 @Path(“id”) 注解为 {id} 提供值。

举个例子

public interface BlogService{
    @GET("blog/{id}")
    Call getBlog(@Path("id") int id);
}

• 序号 8

  可用于替代以上 7 个，及其他扩展方法；
  有 3 个属性：method、path、hasBody、

举个例子

public interface BlogService{
    /**
    * Cmethod  请求方法，不区分大小写
    * path    路径
    * hasBody 是否有请求体
    */
    @HTTP(method = "get", path = "blog/{id}", hasBody = false)
    Call getBlog(@Path("id") int id);
}

---

2、标记类

分类	名称	备注
表单请求	FormUrlEncoded	请求体是 From 表单
~~	Multipart	请求体是支持文件上传的 From 表单
标记	Streaming	响应体的数据用流的形式返回

• FormUrlEncoded
  登录页面使用：Content-Type:application/x-www-form-urlencoded

• Multipart
  上传文件使用：Content-Type:multipart/form-data

//传单个文件
@Multipart
@POST("v1/create")
Call create(@Part("pictureName") RequestBody pictureName,  @Part MultipartBody.Part picture

RequestBody pictureNameBody = RequestBody.create(MediaType.parse(AppConstants.CONTENT_TYPE_FILE), "pictureName");
File picture= new File(path);
RequestBody requestFile = RequestBody.create(MediaType.parse(AppConstants.CONTENT_TYPE_FILE), picture);
// MultipartBody.Part is used to send also the actual file name
MultipartBody.Part picturePart = MultipartBody.Part.createFormData("picture", picture.getName(), requestFile);
//调接口
create(pictureNameBody, picturePart);

//传多个文件
@Multipart
@POST("v1/create")
Call create(@Part("pictureName") RequestBody pictureName,   @PartMap Map.create(MediaType.parse(AppConstants.CONTENT_TYPE_FILE), "pictureName");
File picture= new File(path);
RequestBody requestFile = RequestBody.create(MediaType.parse(AppConstants.CONTENT_TYPE_FILE), picture);
Map params = new HashMap<>();
params.put("picture\"; filename=\"" + picture.getName() + "", requestFile);
//调接口
create(pictureNameBody, params);

• Streaming
  作用于方法，当返回的数据较大时，需要使用该注解。
  

  ---

3、参数类

分类	名称	备注
作用于方法	Headers	添加请求头
作用于方法参数(形参)	Header	添加不固定的 Header
~~	Body	非表单请求体
~~	Field	表单字段，与 FieldMap、FormUrlEncoded 配合
~~	FieldMap	表单字段，与 Field、FormUrlEncoded 配合；接受 Map 类型，非 String 类型会调用 toString() 方法
~~	Part	表单字段，与 PartMap 配合，适合文件上传情况
~~	PartMap	表单字段，与 Part 配合，适合文件上传情况；默认接受 Map 类型，非 RequestBody 会通过 Converter 转换
~~	Path	用于URL
~~	Query	用于URL
~~	QueryMap	用于URL
~~	Url	用于URL

注意：

1、Map 用来组合复杂的参数；

2、Query、QueryMap 与 Field、FieldMap 功能一样，生成的数据形式一样；
Query、QueryMap 的数据体现在 Url 上；
Field、FieldMap 的数据是请求体；

3、{占位符}和 PATH 尽量只用在URL的 path 部分，url 中的参数使用 Query、QueryMap 代替，保证接口的简洁；

4、Query、Field、Part 支持数组和实现了 Iterable 接口的类型， 如 List、Set等，方便向后台传递数组，示例如下：

Call foo(@Query("ids[]") List ids);
// 结果
// ids[]=0&ids[]=1&ids=2

• Headers
  使用 @Headers 注解设置固定的请求头，所有请求头不会相互覆盖，即使名字相同。

@Headers("Cache-Control: max-age=640000")
@GET("widget/list")
Call> widgetList();

@Headers({ "Accept: application/vnd.github.v3.full+json","User-Agent: Retrofit-Sample-App"})
@GET("users/{username}")Call getUser(@Path("username") String username);

• Header
  使用 @Header 注解动态更新请求头，匹配的参数必须提供给 @Header ，若参数值为 null ，这个头会被省略，否则，会使用参数值的 toString 方法的返回值。

@GET("user")
Call getUser(@Header("Authorization") String authorization)

• Body
  使用 @Body 注解，指定一个对象作为 request body 。

@POST("users/new")
Call<User> createUser(@Body User user);

对象会被 Retrofit 实例中指定的转换器转换，若未添加转换器，只能使用 RequestBody ，如下：

@POST("users/new")
Call createUser(@Body User user);

--------------------------------------------------------------

@Headers({"Content-type:application/json;charset=UTF-8"})
@POST("/api/v1/trade/HasAccount.json")
Call createCommit(@Body RequestBody route);

    Gson gson=new Gson();
    HashMap paramsMap=newHashMap<>();
    paramsMap.put("userId","173");
    String strEntity = gson.toJson(paramsMap);
    body = RequestBody.create(okhttp3.MediaType.parse("application/json;charset=UTF-8"),strEntity);
    Call call = api.getService().createCommit(body);

• Field
  表单提交，如登录

 @FormUrlEncoded
 @POST("v1/login")
 Call userLogin(@Field("phone") String phone, @Field("password") String password);

• FieldMap

@FormUrlEncoded
@POST("book/reviews")
Call addReviews(@FieldMap Map fields);

• Part

public interface FileUploadService {  
    // 上传单个文件
    @Multipart
    @POST("upload")
    Call uploadFile(
            @Part("description") RequestBody description,
            @Part MultipartBody.Part file);

    // 上传多个文件
    @Multipart
    @POST("upload")
    Call uploadMultipleFiles(
            @Part("description") RequestBody description,
            @Part MultipartBody.Part file1,
            @Part MultipartBody.Part file2);
}

• PartMap

    @Multipart
    @POST("cyxx/Feedback/add.do")
    Observable getFeedbackResult(
            @PartMap Map params
    );

• Path
  请求 URL 可以替换模块来动态改变，替换模块是 {}包含的字母数字字符串，替换的参数必须使用 @Path 注解的相同字符串。

// 链接 http://baseurl/blog/id
public interface BlogService{
    @GET("blog/{id}")
    Call getBlog(@Path("id") int id);
}

• Query
  查询参数

// 链接 http://baseurl/blog/id?sort=ShortStr
public interface BlogService{
    @GET("blog/{id}")
    Call getBlog(@Path("id") int id, @Query("sort") String sort);
}

//传数组
public interface BlogService{
    @GET("blog/{id}")
    Call getBlog(@Path("id") int id, @Query("linked[]") String... linked);
}

• QueryMap
  复杂的查询参数

// 链接 http://baseurl/blog/id?param1=Param1¶m2=Param2...
public interface BlogService{
    @GET("blog/{id}")
    Call getBlog(@Path("id") int id, @QueryMap Map options);
}

• Url
  动态URL设置
  使用Retrofit2一般都是针对于 一一 baseURL，其它接口都是拼接不同的参数，如get/photo,search?name=xiaohong&&sex=female,这样的形式。
  但是一些请求此时又要访问不同的url只能重新生成一个Retrofit2实例，实质上还有一种形式去处理，就是使用@url注解。

public interface UserService {  
    @GET
    public Call profilePicture(@Url String url);
}

上面的@url 可以接收https://s3.amazon.com/profile-picture/path，使用如下

Retrofit retrofit = Retrofit.Builder()  
    .baseUrl("https://your.api.url/");
    .build();

UserService service = retrofit.create(UserService.class);  
service.profilePicture("https://s3.amazon.com/profile-picture/path");

// request url results in:
// https://s3.amazon.com/profile-picture/path

参考：
1、http://www.jianshu.com/p/bf884248cb37
2、http://blog.csdn.net/ysmintor_/article/details/70271680
3、http://blog.csdn.net/fanatic_/article/details/53066938
4、http://blog.csdn.net/itachi85/article/details/53007262
5、http://www.jianshu.com/p/308f3c54abdd
6、http://square.github.io/retrofit/
7、http://blog.csdn.net/duanyy1990/article/details/52139294
8、http://www.jianshu.com/p/32bfd5fd8b48