Retrofit API 中文

Retrofit API 中文

简介
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创建的每个Call，都可以同步或异步HTTP请求到远程网络服务器。

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

使用注释来描述HTTP请求:

• 支持URL参数替换和查询参数
• 请求主体(如对象转换。JSON 协议缓冲区)
• Multipart请求和文件上传

API声明
注解接口方法及其参数详解

请求方法
每个URL请求须有一个HTTP请求注解方法与之对应。五个注解:GET、POST、PUT、DELETE和HEAD。

@GET("users/list")

指定URL的查询参数

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

使用

URL使用字符串和参数可以替换。需要替代的字符串使用{ and }。相应的参数必须与@ path注释字符串相同。

@GET("group/{id}/users")Call<List<User>> groupList(@Path("id") int groupId);

参数添加

@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);

对象作为HTTP请求体

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

对象可以通过Retrofit实例转换，如果没有添加,只能使用RequestBody。

Retrofit可以发送表单和多部分数据。
表单发送使用@FormUrlEncoded方法。键-值 注解使用@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’s构造，也可以通过RequestBody序列化实现。

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);

注意,Header信息不会覆盖。具有相同名称的所有文件都包括在请求Header中。
请求Header使用@Header动态更新。@Header必须提供相应的参数。如果值为null,Header就会被忽略掉。否则就会调用toString值。

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

Header需要添加到每个请求可以使用一个指定OkHttp拦截器。

实例调用可以同步或异步，每个实例只能使用一次,但是调用clone()将创建一个新的实例。
Android回调函数将在主线程上执行。JVM回调函数会发生在同一线程执行HTTP请求。

Retrofit是把API接口转化为可调用对象。Retrofit会设置默认情况下,,但它允许定制。
默认情况下,Retrofit只能反序列化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
• 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);

自定义转换器

如果需要内容格式(例如YAML,txt、自定义格式)的API，或使用一个不同的库来实现现有的格式,可以创建自己的转换器。创建一个类继承转换器，工厂类,构建自己适配器实例。