Retrofit注解使用大全

一、简介

二、注解

两张图片均来自简书，https://www.jianshu.com/p/a3e162261ab6

GET请求使用

public interface ApiService {
    /**
     * 最简单的GET请求，无参数
     */
    @GET("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo1();


    /**
     * GET请求，带请求参数
     * 请求参数用@Query注解，其中注解里的名字表示追加到URL后的参数名字，
     * URL后的参数值即为我们传进来的类型String name/int age
     * 所以该请求完整的地址是host/api/fetch/guesslike?name=name&mAge=age
     */
    @GET("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo2(@Query("name") String name, @Query("mAge") int age);


    /**
     * GET请求，带请求参数
     * 对getInfo2的改进，多个参数可以用@ueryMap标记，都放到一个Map里
     */
    @GET("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo3(@QueryMap Map<String, String> paramsMap);


    /**
     * GET请求，@Path标记的作用就是使用传进来的值动态替换URL里的字段{id}
     */
    @GET("api/fetch/{id}/guesslike")
    Call<GuessLikeEntity> getInfo4(@Path("id") String id);
}

POST请求使用

public interface ApiService {
    /**
     * POST请求
     * 其中@FormUrlEncoded的含义是发送已编码的Form表单
     * 加这个注解后，请求的Content-Type会是application/x-www-form-urlencoded;
     * 加这个注解后，发送的参数必须是@Field标记的表单键值对
     */
    @FormUrlEncoded
    @POST("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo5(@Field("sid") String id);


    /**
     * POST请求
     * 和getInfo5没区别，@FieldMap仅仅表示多个请求参数可以放到一个Map里方便传递而已
     */
    @FormUrlEncoded
    @POST("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo6(@FieldMap Map<String, String> map);


    /**
     * POST请求，但是没有使用Form表单的形式，即没有@FormUrlEncoded
     * 那么请求的Content-Type默认会是application/json;
     * 不添加@FormUrlEncoded，那么就不能用@Field进行传递参数了，只有一种形式就是@Body，它就是用于非表单的请求体
     * retrofit会把请求的实体序列化成一个json发送出去
     */
    @POST("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo7(@Body CMMEntity requestEntity);


    /**
     * 和getInfo7一样，只是请求参数是官方的RequestBody
     * 这样做的好处是，我们自己构建的RequestBody可以修改其Media-Type
     */
    @POST("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo8(@Body RequestBody requestBody);
    // 生成RequestBody
    RequestBody getRequestBodyForParams(Map<String, String> paramsMap) {
        MediaType mediaType = MediaType.parse("application/json; charset=utf-8");
        JSONObject jo = new JSONObject();
        if (paramsMap != null) {
            for (String key : paramsMap.keySet()) {
                try {
                    jo.put(key, paramsMap.get(key));
                } catch (JSONException e) {
                }
            }
        }
        return RequestBody.create(mediaType, jo.toString());
    }
}

HTTP/URL/Streaming标签使用

public interface ApiService {
    /**
     * 下面定义了一个Delete请求，其实@HTTP标签是可以替代所有的请求标签，包括GET/POST/PUT/DELETE等，
     * 都可以通过@HTTP标签来实现。hasBody表示是否有请求体，有就用参数@Body带上
     */
    @HTTP(method = "DELETE", path = "api/fetch/guesslike/{id}", hasBody = true)
    Call<GuessLikeEntity> getInfo9(@Path("id") String id, @Body CMMEntity requestEntity);


	/**
     * 当有@URL注解时，@GET传入的URL就可以省略
     */
    @GET
    Call<GuessLikeEntity> getInfo16(@Url String url);


    /**
     * 其中@Streaming注解表示返回的数据以流的形式返回，适用于大文件的下载操作。
     * 如果没有该注解，会默认把数据全部载入到内存里，即将将body()转换为byte[]，就有可能引起OOM了
     */
    @Streaming
    @GET
    Call<ResponseBody> getInfo17(@Url String url);
    // 获取返回的数据处理
    ResponseBody body = response.body();
    long fileSize = body.contentLength();
    InputStream inputStream = body.byteStream();
}

Header标签使用

public interface ApiService {
    /**
     * GET请求，@Headers的作用是添加单个固定的请求头
     */
    @Headers("Cache-Control: max-age=640000")
    @GET("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo10();


    /**
     * GET请求，@Headers添加了多个固定的请求头
     */
    @Headers({"Cache-Control: max-age=640000", "Accept-Charset: UTF-8"})
    @GET("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo11();


    /**
     * GET请求，@Header是用在参数上，添加单个不固定的请求头，值由外部传进来
     */
    @GET("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo12(@Header("Accept-Charset") String charset);


    /**
     * GET请求，@HeaderMap是用在参数上，添加多个不固定的请求头，键和值都是由外部传进来
     */
    @GET("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo13(@HeaderMap Map<String, String> headerMap);
}

Multipart/Part标签使用

public interface ApiService {
    /**
     * POST请求
     * 其中@Multipart表示请求体是分为多个部分的，配合参数@Part使用。
     * 如果@Part的参数类型是RequestBody，表示请求参数，那么其Key，也就是"name"和"age"是不能隐藏的，必须显式指明Key
     * 如果@Part的参数类型是MultipartBody.Part，即表示请求的上传文件，内容会直接被使用，那么是不需要Key的
     */
    @Multipart
    @POST("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo14(@Part("name") RequestBody name, @Part("age") RequestBody age,
                                    @Part MultipartBody.Part file);


    /**
     * POST请求，getInfo14的改良版。多个请求参数可以封装在@PartMap标记对应的Map里
     */
    @Multipart
    @POST("api/fetch/guesslike")
    Call<GuessLikeEntity> getInfo15(@PartMap Map<String, RequestBody> paramsMap ,
                                    @Part MultipartBody.Part file);
}