Retrofit--官网2.1.0

android

Retrofit

• • 介绍
  • API 描述
    • 请求方法
    • URL 处理
    • 请求体
    • 表单的 ENCODED 和 MULTIPART
    • HEADER 处理
    • 同步 VS 异步
  • Retrofit 配置
    • 转换器
    • 自定义转换器
  • 下载
    • 使用 maven
    • 使用 Gradle
  • PROGUARD

介绍

1. public interface GitHubService {

   ---

2. @GET("users/{user}/repos") 
   

   ---

3. Call<List<Repo>> listRepos(@Path("user") String user); 
   

   ---

4. } 
   

   ---

使用 Retrofit 类生成 GitHubService 的实例：

1. Retrofit retrofit = new Retrofit.Builder()

   ---

2. .baseUrl("https://api.github.com/") 
   

   ---

3. .build(); 
   

   ---

4. ---

5. GitHubService service = retrofit.create(GitHubService.class); 
   

   ---

在 GitHubService 实例上的每次调用都会产生一个到远程服务的同步、或异步的 HTTP 的请求：

1. Call<List<Repo>> repos = service.listRepos("octocat");

   ---

使用注解描述 HTTP 请求：

• 支持 URL 参数的占位符，支持请求参数
• 对象和 response body 的转换（例如：JSON 等）
• Multipart 请求体和文件上传

API 描述

请求方法

1. @GET("users/list")

   ---

在 URL 中，也可以指定查询参数：

1. @GET("users/list?sort=desc")

   ---

URL 处理

1. @GET("group/{id}/users")

   ---

2. Call<List<User>> groupList(@Path("id") int groupId); 
   

   ---

当然，也可以添加查询参数：

1. @GET("group/{id}/users")

   ---

2. Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort); 
   

   ---

复杂的查询参数（例如 Map 类型）的示例：

1. @GET("group/{id}/users")

   ---

2. Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options); 
   

   ---

请求体

1. @GET("group/{id}/users")

   ---

2. Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options); 
   

   ---

也可以通过给 Retrofit 的实例指定转换器的方式对对象进行转换。如果没有添加转换器，仅能使用 RequestBody。

表单的 ENCODED 和 MULTIPART

当方法上存在 @FormUrlEncoded 注解时，就会发送 form-encoded 的数据。@Filed 包含了键值对的键名称，后面的对象提供了键值对的值：

1. @FormUrlEncoded

   ---

2. @POST("user/edit") 
   

   ---

3. Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last); 
   

   ---

当方法上存在 @Multipart 注解时，就会发送 multipart 的数据，各部分使用 @Part 注解进行申明：

1. @Multipart

   ---

2. @PUT("user/photo") 
   

   ---

3. Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description); 
   

   ---

multipart 的各部分要么使用 Retrofit 的转换器，要么实现 RequestBody，用这样的方式来实现各自的序列化。

HEADER 处理

1. @Headers("Cache-Control: max-age=640000")

   ---

2. @GET("widget/list") 
   

   ---

3. Call<List<Widget>> widgetList(); 
   

   ---

1. @Headers({

   ---

2. "Accept: application/vnd.github.v3.full+json", 
   

   ---

3. "User-Agent: Retrofit-Sample-App" 
   

   ---

4. }) 
   

   ---

5. @GET("users/{username}") 
   

   ---

6. Call<User> getUser(@Path("username") String username); 
   

   ---

注意：header中的各个部分不能相互覆盖。所有相同名称的header都会被包含在请求中。

也可以使用 @Header 注解对头部内容进行动态的更新。对应的参数必须由 @Header 进行提供。如果值为 null，那么将被忽略。如果不为 null，值将会使用 toString() 方法，最终使用 toString() 方法返回的值：

1. @GET("user")

   ---

2. Call<User> getUser(@Header("Authorization") String authorization) 
   

   ---

如果要给每个请求都添加头部，那么，可以使用 OkHttp interceptor 进行指定。

同步 VS 异步

在 Android 中，回调方法会在主线程中执行。在 JVM 中，回调将和执行 HTTP 请求发生在同一线程。

Retrofit 配置

转换器

要支持其它的类型，可以添加转换器。为了方便起见，为了适配一些流行的序列化库，Retrofit 已经提供了六个模块：

• Gson: com.squareup.retrofit2:converter-gson
• Jackson: com.squareup.retrofit2:converter-jackson
• Moshi: com.squareup.retrofit2:converter-moshi
• Protobuf: com.squareup.retrofit2:converter-protobuf
• Wire: com.squareup.retrofit2:converter-wire
• Simple XML: com.squareup.retrofit2:converter-simplexml
• Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars

下面的示例中，使用 GsonConverterFactory 类来生成 GitHubService 的实现，该实现使用 Gson 作为反序列化的工具：

1. Retrofit retrofit = new Retrofit.Builder()

   ---

2. .baseUrl("https://api.github.com") 
   

   ---

3. .addConverterFactory(GsonConverterFactory.create()) 
   

   ---

4. .build(); 
   

   ---

5. ---

6. GitHubService service = retrofit.create(GitHubService.class); 
   

   ---

自定义转换器

下载

2.1.0版本官方下载

使用 maven

1. <dependency>

   ---

2. <groupId>com.squareup.retrofit2</groupId> 
   

   ---

3. <artifactId>retrofit</artifactId> 
   

   ---

4. <version>2.1.0</version> 
   

   ---

5. </dependency> 
   

   ---

使用 Gradle

1. compile ‘com.squareup.retrofit2:retrofit:2.1.0‘

   ---

注意：Retrofit 需要 Java 7 及以上，Android 2.3 及以上

PROGUARD

1. # Platform calls Class.forName on types which do not exist on Android to determine platform.

   ---

2. -dontnote retrofit2.Platform 
   

   ---

3. # Platform used when running on RoboVM on iOS. Will not be used at runtime. 
   

   ---

4. -dontnote retrofit2.Platform$IOS$MainThreadExecutor 
   

   ---

5. # Platform used when running on Java 8 VMs. Will not be used at runtime. 
   

   ---

6. -dontwarn retrofit2.Platform$Java8 
   

   ---

7. # Retain generic type information for use by reflection by converters and adapters. 
   

   ---

8. -keepattributes Signature 
   

   ---

9. # Retain declared checked exceptions for use by a Proxy instance. 
   

   ---

10. -keepattributes Exceptions 
    

    ---