一、基础介绍

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

public interface BlueService {
   @GET("book/search")
   Call<BookSearchResponse> 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<BookSearchResponse> call = mBlueService.getSearchBooks("小王子", "", 0, 3);
  • 同步请求
BookSearchResponse response = call.execute().body();
  • 异步请求
call.enqueue(new Callback<BookSearchResponse>() {
    @Override
    public void onResponse(Call<BookSearchResponse> call, Response<BookSearchResponse> response){
        asyncText.setText("异步请求结果: " + response.body().books.get(0).altTitle);
    }

    @Override
    public void onFailure(Call<BookSearchResponse> 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<ResponseBody> 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<ResponseBody> 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<ResponseBody> 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<ResponseBody> create(@Part("pictureName") RequestBody pictureName,   @PartMap Map<String, RequestBody

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);
Map<String, RequestBody> 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, String> 类型，非 String 类型会调用 toString() 方法

~~

Part

表单字段，与 PartMap 配合，适合文件上传情况

~~

PartMap

表单字段，与 Part 配合，适合文件上传情况；默认接受 Map<String, RequestBody> 类型，非 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<ResponseBody> foo(@Query("ids[]") List<Integer> ids);
// 结果
// ids[]=0&ids[]=1&ids=2
  • Headers
    使用 @Headers 注解设置固定的请求头，所有请求头不会相互覆盖，即使名字相同。
@Headers("Cache-Control: max-age=640000")
@GET("widget/list")
Call<List<Widget>> widgetList();

@Headers({ "Accept: application/vnd.github.v3.full+json","User-Agent: Retrofit-Sample-App"})
@GET("users/{username}")Call<User> getUser(@Path("username") String username);
  • Header
    使用 @Header 注解动态更新请求头，匹配的参数必须提供给 @Header ，若参数值为 null ，这个头会被省略，否则，会使用参数值的 toString 方法的返回值。
@GET("user")
Call<User> getUser(@Header("Authorization") String authorization)
  • Body
    使用 @Body 注解，指定一个对象作为 request body 。
@POST("users/new")
Call<User> createUser(@Body User user);

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

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

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

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

    Gson gson=new Gson();
    HashMap<String,String> paramsMap=newHashMap<>();
    paramsMap.put("userId","173");
    String strEntity = gson.toJson(paramsMap);
    body = RequestBody.create(okhttp3.MediaType.parse("application/json;charset=UTF-8"),strEntity);
    Call<BaseResponse> call = api.getService().createCommit(body);
  • Field
    表单提交，如登录
@FormUrlEncoded
 @POST("v1/login")
 Call<ResponseBody> userLogin(@Field("phone") String phone, @Field("password") String password);
  • FieldMap
@FormUrlEncoded
@POST("book/reviews")
Call<String> addReviews(@FieldMap Map<String, String> fields);
  • Part
public interface FileUploadService {  
    // 上传单个文件
    @Multipart
    @POST("upload")
    Call<ResponseBody> uploadFile(
            @Part("description") RequestBody description,
            @Part MultipartBody.Part file);

    // 上传多个文件
    @Multipart
    @POST("upload")
    Call<ResponseBody> uploadMultipleFiles(
            @Part("description") RequestBody description,
            @Part MultipartBody.Part file1,
            @Part MultipartBody.Part file2);
}
  • PartMap
@Multipart
    @POST("cyxx/Feedback/add.do")
    Observable<ResponseBody> getFeedbackResult(
            @PartMap Map<String, RequestBody> params
    );
  • Path
    请求 URL 可以替换模块来动态改变，替换模块是 {}包含的字母数字字符串，替换的参数必须使用 @Path 注解的相同字符串。
// 链接 http://baseurl/blog/id
public interface BlogService{
    @GET("blog/{id}")
    Call<ResponseBody> getBlog(@Path("id") int id);
}
  • Query
    查询参数
// 链接 http://baseurl/blog/id?sort=ShortStr
public interface BlogService{
    @GET("blog/{id}")
    Call<ResponseBody> getBlog(@Path("id") int id, @Query("sort") String sort);
}

//传数组
public interface BlogService{
    @GET("blog/{id}")
    Call<ResponseBody> 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<ResponseBody> getBlog(@Path("id") int id, @QueryMap Map<String, String> options);
}
  • Url
    动态URL设置
    使用Retrofit2一般都是针对于 一一 baseURL，其它接口都是拼接不同的参数，如get/photo,search?name=xiaohong&&sex=female,这样的形式。
    但是一些请求此时又要访问不同的url只能重新生成一个Retrofit2实例，实质上还有一种形式去处理，就是使用@url注解。
public interface UserService {  
    @GET
    public Call<ResponseBody> 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