retrofit入门教程_retriofit 入门-CSDN博客

Retrofit

A type-safe HTTP client for Android and Java

简介

Retrofit把Http API 当成一个interface
public interface GitHubService {
    @Get("users/{user]/repos")
    Call<List<Repo>> listRepos(@Path("user") String user);
}

然后Retrofit通过create获得一个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");

使用java的注解去描述HTTP请求：
- Url参数可替换，查询参数支持
- 对象也已转化成请求体（例如JSON，协议缓冲）
- 多块请求体，文件上传

API声明

接口方法和它的参数的注解表明了将如何处理http请求

请求方法

每个方法都必须有个提供请求方法的HTTP注解和相关的URL，总共有五个内置的注解（GET,POST,PUT,DELETE,HEAD）

@GET("users/list")

你也可以制定查询参数在URL中

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

-URL的使用
可以使用替代块和参数动态更新请求的url，替换块是{}包围的字符数字字符串。相应的参数必须使用相同的字符串用@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的请求体，只是不要忘了添加@Body注解。

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

该对象也将使用Retrofit实例上指定的转换器进行转换。如果没有添加转换器，则只能使用RequestBody。

当方法上存在@FormUrlEncoded时，将发送表单编码的数据。每个键值对都使用包含名称的@Field和提供值的对象进行注释。

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

当@Multipart出现在方法上时，将使用多部分请求。每一部分都要使用@Part注释声明。

@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);

多部分请求时使用Retrofit的转换器，或者也可以实现RequestBody来处理自己的序列化。

头部请求

您可以使用@Headers注释为方法设置头部。
@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必须提供相应的参数。如果该值为null,头就会被忽略掉。否则,toString将被调用在头上,并使用该值。

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

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

同步和异步

调用实例可以同步或异步执行。每个实例只能使用一次，但调用clone（）将创建一个可以使用的新实例。

在Android上，回调将在主线程上执行。在JVM上，回调将发生在执行HTTP请求的同一线程上。

Retrfit配置

Retrofit是将API接口转换为可调用对象的类。默认情况下，Retrofit将为您的平台提供正常默认值，但允许自定义。

转换器

默认情况下，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
* 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);

自定义转换器

如果您需要与使用Retrofit不支持开箱即用的内容格式（例如YAML，txt，自定义格式）的API进行通信，或者希望使用其他库来实现现有格式，则可以轻松创建你自己的转换器。创建一个扩展Converter.Factory类的类，并在构建适配器时传递实例。

下载

Retrofit的源码和样例可以在GitHub上下载，[点击下载源码](http://github.com/square/retrofit)

MAVEN

<dependency>
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>retrofit</artifactId>
    <version>(insert latest version)</version>
</dependency>

GRADLE

compile 'com.squareup.retrofit2:retrofit:(insert latest version)'

Retrofit需要至少Java 7或Android 2.3。

代码混淆

如果在项目中使用Proguard，请在配置中添加以下行：
# Platform calls Class.forName on types which do not exist on Android to determine platform.
-dontnote retrofit2.Platform
# Platform used when running on RoboVM on iOS. Will not be used at runtime.
-dontnote retrofit2.Platform$IOS$MainThreadExecutor
# Platform used when running on Java 8 VMs. Will not be used at runtime.
-dontwarn retrofit2.Platform$Java8
# Retain generic type information for use by reflection by converters and adapters.
-keepattributes Signature
# Retain declared checked exceptions for use by a Proxy instance.
-keepattributes Exceptions