Retrofit 使用

Retrofit 官网

https://square.github.io/retrofit/

导入依赖库

// retrofit
implementation 'com.squareup.retrofit2:retrofit:2.9.0'
// 或
// implementation 'com.squareup.retrofit2:retrofit:(insert latest version)'
// gson 解析数据，直接转换成需要的实体类或其他类型（可以不添加）
implementation 'com.squareup.retrofit2:converter-gson:2.0.2'
// 数据请求
implementation 'com.squareup.retrofit2:adapter-rxjava3:2.9.0'
1
2
3
4
5
6
7
8

请求数据（以 玩Android 为例，官方文档为 github 接口：https://api.github.com/）

• 数据请求前提

  • 数据

    val baseurl = "https://www.wanandroid.com"
    val username = "bin"
    val password = "123456"
    1
    2
    3

  • 创建请求的接口文件 Api.class

    interface Api{
    
    //    登陆
        @FormUrlEncoded
        @POST("/user/login")
        fun login(@Field("username") username:String, @Field("password") password:String) : Call<WanAndroidResponse<WanAndroidUser>>
    
    //    首页文章列表
        @GET("/article/list/{page}/json")
        fun homeArticleList(@Path("page") page:Int) : Call<WanAndroidResponse<ArticleList>>
    }
    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11

  • 创建 Retrofit 对象

    val retrofit: Retrofit = Retrofit.Builder()
                    .baseUrl(baseurl)
                    .addConverterFactory(GsonConverterFactory.create())
                    .build()
    1
    2
    3
    4

  • 创建 Api 对象

    var mApi: Api = retrofit.create(Api::class.java)
    1

• get

  mApi.homeArticleList(0).also {
              it.enqueue(object : Callback<WanAndroidResponse<ArticleList>> {
                  override fun onFailure(
                      call: Call<WanAndroidResponse<ArticleList>>?,
                      t: Throwable?
                  ) {
                      Log.e(TAG, "getHomeArticleList onFailure:\n ${t.toString()}\n${call.toString()}" )
                  }
  
                  override fun onResponse(
                      call: Call<WanAndroidResponse<ArticleList>>?,
                      response: Response<WanAndroidResponse<ArticleList>>?
                  ) {
                      Log.e(TAG, "getHomeArticleList onResponse: ${response!!.body().toString()}" )
                  }
  
              })
          }
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18

• post

  mApi.login(username, password).also {
              it.enqueue(object : Callback<WanAndroidResponse<WanAndroidUser>> {
                  override fun onFailure(call: Call<WanAndroidResponse<WanAndroidUser>>, t: Throwable) {
                      Log.e(TAG, "login onFailure:\n ${t.toString()}\n${call.toString()}" )
                  }
  
                  override fun onResponse(
                      call: Call<WanAndroidResponse<WanAndroidUser>>,
                      response: Response<WanAndroidResponse<WanAndroidUser>>
                  ) {
                      Log.e(TAG, "login onResponse: ${response.body().toString()}" )
                      Log.e(TAG, "onResponse: ${response.headers()}" )
  
                      cookieList = response.headers().values("Set-Cookie")
                      Log.e(TAG, "onResponse: ${response.headers().values("Set-Cookie")}\n${cookieList.size}" )
                  }
  
              })
          }
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19

• 提交图片

  @Multipart
      @POST("home/upload-image")
      Call<PictureBean> setHttpPortrait(@Part MultipartBody.Part part);
  1
  2
  3

  private void setHttpPortrait(final String name, final String strPath) {//name：参数名称；strPath：图片路径
          File file = new File(strPath);
          RequestBody imageBody = RequestBody.create(MediaType.parse("multipart/form-data"), file);
          MultipartBody.Part imageBodyPart = MultipartBody.Part.createFormData(name, file.getName(), imageBody);
          Call<PictureBean> repos = xxx.setHttpPortrait(imageBodyPart);
          repos.enqueue(new Callback<PictureBean>() {
              @Override
              public void onResponse(Call<PictureBean> call, Response<PictureBean> response) {
                  try {
                      if (response.body().isOk()) {//请求成功
                          //返回数据处理
                      } else {
                          //图片上传失败
                      }
                  } catch (Exception e) {
                      //返回数据异常
                  }
              }
   
              @Override
              public void onFailure(Call<PictureBean> call, Throwable t) {
                  //请求异常
              }
          });
      }
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25

  @Multipart
      @POST("home/upload-image")//多张上传图片
      Call<PictureBean> setHttpDataPortrait(@Part List file);
  1
  2
  3

  private void setHttpPortrait(final String name, final List<String> paths) {
          showLoading();
          MultipartBody.Builder builder = new MultipartBody.Builder().setType(MultipartBody.FORM);
          for (String path : paths) {
              File file = new File(path);
              RequestBody requestBody = RequestBody.create(MediaType.parse("text/x-markdown; charset=utf-8"), file);
              builder.addFormDataPart("files", file.getName(), requestBody);
          }
          List parts = builder.build().parts();
   
          Call<PictureBean> repos = xxx.setHttpDataPortrait(parts);
          repos.enqueue(new Callback<PictureBean>() {
              @Override
              public void onResponse(Call<PictureBean> call, Response<PictureBean> response) {
                  try {
                      if (response.body().isOk()) {
                          //返回数据处理
                      } else {
                          //图片上传失败
                      }
                  } catch (Exception e) {
                      //返回数据异常
                  }
              }
   
              @Override
              public void onFailure(Call<PictureBean> call, Throwable t) {
                  //请求异常
              }
          });
      }
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10
  11
  12
  13
  14
  15
  16
  17
  18
  19
  20
  21
  22
  23
  24
  25
  26
  27
  28
  29
  30
  31

• 执行请求，并处理返回结果

  mApi.xxx().enqueue(object : Callback<ResponseBody> {
              override fun onResponse(call: Call<ResponseBody>, response: Response<ResponseBody>) {
                  // 请求成功，进行后续处理
              }
  
              override fun onFailure(call: Call<ResponseBody>, t: Throwable) {
                  // 请求失败，进行后续处理
              }
  
          })
  1
  2
  3
  4
  5
  6
  7
  8
  9
  10

注解的含义及使用

• 请求方法
  • @GET
  • @POST
  • @PUT
  • @DELETE
  • @PATH
  • @HEAD
  • @OPTIONS
  • @HTTP
• 标记类
  • @FormUrlEncoded
    表示请求主体是表单
  • @Multipart
    表示请求主体是支持文件上传的表单
  • @Streaming
    表示返回的数据以流的形式返回。适用于返回数据较大的场景（没使用过）
• 请求参数

  • @Headers
    添加请求头（固定的请求头）

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

    @Headers("Cache-Control: max-age=640000")
    @GET("widget/list")
    Call<List<Widget>> widgetList();
    1
    2
    3

  • @HeaderMap
    添加请求头（不固定的请求头）

    @GET("user")
    Call<User> getUser(@HeaderMap Map<String, String> headers)
    1
    2

  • @Header
    添加单个请求头（不固定的请求头）

    @GET("user")
    Call<User> getUser(@Header("Authorization") String authorization)
    1
    2

  • @Body
    用于非表单请求体（传实体类对象或其他自己需要的类型）

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

    @POST("auth/guest")
    Call<BaseResponse<TokenInfo>> guest(@Body RequestBody requestBody);
    1
    2

  • @Field
    向 post 表单传入键值对

    @FormUrlEncoded
    @POST("user/edit")
    Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);
    1
    2
    3

  • @FieldMap
    向 post 表单传入多个键值对

    @FormUrlEncoded
    @POST("user/edit")
    Call<User> updateUser(@FieldMap Map<String, String> fields);
    1
    2
    3

  • @Part
    向 post 表单传入键值对（需要上传文件的场景）

    @Multipart
     @POST("/")
     Call<ResponseBody> example(
         @Part("description") String description,
         @Part(value = "image", encoding = "8-bit") RequestBody image);
    1
    2
    3
    4
    5

     @Multipart
        @POST("home/upload-image")
        Call<PictureBean> setHttpPortrait(@Part MultipartBody.Part part);
    1
    2
    3

  • @PartMap
    向 post 表单传入多个键值对（需要上传文件的场景）

    @Multipart
     @POST("/upload")
     Call<ResponseBody> upload(
         @Part("file") RequestBody file,
         @PartMap Map<String, RequestBody> params);
    1
    2
    3
    4
    5

    @Multipart
        @POST("home/upload-image")//多张上传图片
        Call<PictureBean> setHttpDataPortrait(@Part List file);
    1
    2
    3

  • @Query
    向 get 请求传入参数及对应的值

    @GET("/friends")
     Call<ResponseBody> friends(@Query("page") int page);
    1
    2

  • @QueryMap
    向 get 请求传入多个参数及对应的值

     @GET("/friends")
     Call<ResponseBody> friends(@QueryMap Map<String, String> filters);
    1
    2

  • @Path
    向 get 请求传入链接的缺省值

    @GET("users/{user}/repos")
    Call<List<Repo>> listRepos(@Path("user") String user);
    1
    2