今天接触到了Retrofit，来了解下它的主要功能。这是一个适用于Android和Java的类型安全的HTTP客户端。
1. 简介
Retrofit将HTTP API转换为Java接口，示例如下：
public interface GitHubService { @GET("users/{user}/repos") Call<List<Repo>> listRepos(@Path("user") String user); }
Retrofit类生成GitHubService接口的实现。
Retrofit retrofit = new Retrofit.Builder() .baseUrl("https://api.github.com/") .build(); GitHubService service = retrofit.create(GitHubService.class);
创建GitHubService的每个调用都可以向远程Web服务器发出同步或异步HTTP请求。
Call<List<Repo>> repos = service.listRepos("octocat");
使用注解描述HTTP请求：
- URL参数替换和查询参数支持
- 将对象转换为请求主体（例如JSON，协议缓冲区）
- 将请求体正文和文件分多部分上传
2. API的声明
通过接口方法及其参数上的注解说明如何处理请求。
2.1 request方法
每个方法必须具有提供请求方法和相对URL的HTTP注解。共有八种内置注解：HTTP，GET，POST，PUT，PATCH，DELETE，OPTIONS和HEAD。资源的相对URL在注解中指定，示例如下：
@GET("users/list") //http注解和URL
也可以在URL中指定查询参数。
@GET("users/list?sort=desc")
2.2 URL操作
可以使用方法上的替换块和参数来动态更新请求URL。替换块是由{}包围的字符串。必须使用相同的字符串在@Path处注解一个对应的参数，如下所示：
@GET("group/{id}/users") Call<List<User>> groupList(@Path("id") int groupId); //两个id名字需一致
也可以添加查询参数：
@GET("group/{id}/users") Call<List<User>> groupList(@Path("id") int groupId, @Query("sort") String sort);
对于复杂的查询参数组合，可以使用Map。
@GET("group/{id}/users") Call<List<User>> groupList(@Path("id") int groupId, @QueryMap Map<String, String> options);
2.3 请求体
可以使用@Body注解将对象指定为HTTP请求正文。
@POST("users/new") Call<User> createUser(@Body User user);
该对象还将使用Retrofit实例上指定的转换器进行转换。如果未添加转换器，则只能使用RequestBody。
2.4 Form-encoded和Multipart
可以声明方法以发送Form-encoded的和Multipart数据。
当方法上存在@FormUrlEncoded时，将发送form-encoded的数据。每个键/值对都用@Field注释，其中包含名称和提供该值的对象。
@FormUrlEncoded @POST("user/edit") Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);
当方法上存在@Multipart时，将使用multipart请求。使用@Part注解声明每部分请求。
@Multipart @PUT("user/photo") Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);
Multipart请求使用Retrofit的转换器，或者它们可以实现RequestBody来处理自己的序列化。
2.5 header操作
可以使用@Headers注解为方法设置静态header。
@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);
注意，headers不会相互覆盖。具有相同名称的所有headers都将包含在请求中。
可以使用@Header注解动态更新请求header。必须为@Header提供相应的参数。如果该值为null，则header将被省略。对header的值调用toString处理，并使用结果。
@GET("user") Call<User> getUser(@Header("Authorization") String authorization)
与查询参数类似，对于复杂的headers组合，可以使用Map。
@GET("user") Call<User> getUser(@HeaderMap Map<String, String> headers)
可以使用OkHttp拦截器指定需要添加到每个请求的header。
2.6 同步和异步
调用实例可以同步或异步执行。每个实例只能使用一次，但是调用clone（）将创建一个可以使用的新实例。
在Android上，回调将在主线程上执行。 在JVM上，回调将在执行HTTP请求的同一线程上发生。
3. 配置相关
Retrofit是将API接口转换为可调用对象的类。默认情况下，Retrofit提供合理的默认设置，也允许自定义。
3.1 转换器
默认情况下，Retrofit只能将HTTP正文反序列化为OkHttp的ResponseBody类型，并且只能接受@Body的RequestBody类型。可以添加转换器以支持其他类型。以下是一些流行的序列化库：
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 JAXB: com.squareup.retrofit2:converter-jaxb Scalars (primitives, boxed, and String): com.squareup.retrofit2:converter-scalars
下面是一个使用GsonConverterFactory类生成GitHubService接口的实现的示例，该接口使用Gson进行反序列化。
Retrofit retrofit = new Retrofit.Builder() .baseUrl("https://api.github.com/") .addConverterFactory(GsonConverterFactory.create()) .build(); GitHubService service = retrofit.create(GitHubService.class);
3.2 自定义转换器
如果需要与使用Retrofit不支持的现成格式（例如YAML，txt，自定义格式等）的API通信，或者希望使用其他库来实现现有格式，则可以创建自己的转换器。创建一个扩展Converter.Factory类的类，并在构建适配器时传入一个实例。
今天就到这里啦，欢迎关注交流～
