# RESTFUL 网路请求框架 Retrofit

Retrofit 是一个高质量高效率的 HTTP 请求库,和 OkHttp 同样出自 Square 公司。Retrofit 内部依赖于 OkHttp,它将 OKHttp 底层的代码和细节都封装了起来,功能上做了更多的扩展,比如返回结果的自动解析,网络引擎的切换,拦截器......

有了 Retrofit 之后对于一些请求我们就只需要一行代码或者一个注解、大大简化了网络请求的代码量。

# 注解

retrofit 注解驱动型上层网络请求框架,使用注解来简化请求,大体分为以下几类:

  • 用于标注网络请求方式的注解
  • 标记网络请求参数的注解
  • 用于标记网络请求和响应格式的注解

使用示例:

interface ApiService{
    @GET("user/query")
    Call<User> queryUser(@Query("userId") String userId);
}
val mApi = retrofit.create(ApiService.class);
val response = mApi.queryUser("100086").execute()

retrofit注解

# 请求方法注解

注解说明
@GETget 请求
@POSTpost 请求
@PUTput 请求
@DELETEdelete 请求
@PATCHpatch 请求,该请求是对 put 请求的补充,用于更新局部资源
@HEADhead 请求
@OPTIONSoption 请求
@HTTP通用注解,可以替换以上所有的注解,其拥有三个属性:method,path,hasBody

# 请求头注解

注解说明
@Headers用于添加固定请求头,可以同时添加多个。通过该注解添加的请求头不会相互覆盖,而是共同存在
@Header作为方法的参数传入,用于添加不固定值的 Header,该注解会更新已有的请求头

# 请求参数注解

名称说明
@Body多用于 post 请求发送非表单数据,比如想要以 post 方式传递 json 格式数据
@Filed多用于 post 请求中表单字段,Filed 和 FieldMap 需要 FormUrlEncoded 结合使用
@FiledMap和 @Filed 作用一致,用于不确定表单参数
@Part用于表单字段,Part 和 PartMap 与 Multipart 注解结合使用,适合文件上传的情况
@PartMap用于表单字段,默认接受的类型是 Map,可用于实现多文件上传
@Path用于 url 中的占位符
@Query用于 Get 中指定参数
@QueryMap和 Query 使用类似
@Url指定请求路径

# 请求和响应格式注解

名称说明
@FormUrlEncoded表示请求发送编码表单数据,每个键值对需要使用 @Field 注解
@Multipart表示请求发送 multipart 数据,需要配合使用 @Part
@Streaming表示响应用字节流的形式返回。如果没使用该注解,默认会把数据全部载入到内存中。该注解在在下载大文件的特别有用

# 请求方法定义

public interface ApiService {
    @GET("user/query")
    Call<User> queryUser(@Query("userId") String userId);
    // 使用 @Headers 添加多个请求头
    @Headers({"User-Agent:android", "apikey:123456789", })
    @GET("user/query")
    Call<User> queryUser(@Query("userId") String userId);
    // 多个参数的情况下可以使用 @QueryMap,但只能用在 GET 请求上
    @GET("user/query"")
    Call<User> queryUser(@QueryMap Map<String, String> params);
    /**
     * 很多情况下,我们需要上传 json 格式的数据。当我们注册新用户的时候,因为用户注册时的数据相对较多
     * 并可能以后会变化,这时候,服务端可能要求我们上传 json 格式的数据。此时就要 @Body 注解来实现。
     * 直接传入实体,它会自行转化成 Json, @Body 只能用在 POST 请求上
     *
     * 字符串提交
     */
    @POST("user/update")
    Call<User> update(@Body News post);
    /**
    * 表单提交(键值对提交)
    */
    @POST()
    @FormUrlEncoded  
    Call<User> executePost(@FieldMap Map<String, Object> maps);
    /**
     * 表单上传文件(键值对提交、同时上传文件)
     */
    @Multipart
    @POST("upload/upload")
    Call<> register(@Filed String openId, @PartMap Map<String, MultipartBody.Part> map);
}

# 开始使用

# 添加依赖

在 Android Studio 中使用,先添加依赖:

compile 'com.squareup.retrofit2:retrofit:2.3.0'
compile 'com.squareup.retrofit2:converter-gson:2.3.0' //json 转换

# 初始化

val retrofit = new Retrofit.Builder()
                .client(okhttpClient)
                .baseUrl("http://123.56.232.18:8080/serverdemo/")
                .addConverterFactory(GSONConverterFactory.create())
                .build();
val mApi = retrofit.create(ApiService.class);