Retrofit (0)-Getting Started and Create an Android Client

快速了解Retrofit

什么是Retrofit

Retrofit的官方介绍是

A type-safe REST client for Android and Java

一个用于Android和Java的类型安全的REST客户端
你可以通过注解的方式来构建HTTP请求,可置换的URL参数并且支持默认的查询参数.除此之外,它还支持多部分请求体和文件上传.

怎样去定义一个请求

请通过查看在Retrofit官网的API文档来了解怎么构造请求.你就可以找到所有重要的信息.

准备一个安卓项目

好了,现在我们进入实践环节.首先在你的IDE里打开一个安卓项目,我们更喜欢使用Gradle来作为构建系统,当然你也可以是用Maven.

###设置依赖:Gradle or Maven
现在我们设置Retrofit的依赖.选择一个构建系统然后在pom.xml或是build.gradle里设置依赖.当我们运行以下命令来构建我们的代码时,构建系统会自动下载依赖的库.
####Retrofit1.9
pom.xml

<dependency>  
    <groupId>com.squareup.retrofit</groupId>
    <artifactId>retrofit</artifactId>
    <version>1.9.0</version>
</dependency>  
<dependency>  
    <groupId>com.squareup.okhttp</groupId>
    <artifactId>okhttp</artifactId>
    <version>2.7.2</version>
</dependency> 

build.gradle

dependencies {  
    // Retrofit & OkHttp
    compile 'com.squareup.retrofit:retrofit:1.9.0'
    compile 'com.squareup.okhttp:okhttp:2.7.2'
}

####Retrofit2
如果你正在使用Retrofit2,你应该使用下面的依赖配置
pom.xml

<dependency>  
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>retrofit</artifactId>
    <version>2.1.0</version>
</dependency>  
<dependency>  
    <groupId>com.squareup.retrofit2</groupId>
    <artifactId>converter-gson</artifactId>
    <version>2.1.0</version>
</dependency> 

build.gradle

dependencies {  
    // Retrofit & OkHttp
    compile 'com.squareup.retrofit2:retrofit:2.1.0'
    compile 'com.squareup.retrofit2:converter-gson:2.1.0'
}

Retrofit2已经默认使用了OKhttp来作为网络层并且已经集成了OkHttp.你不再需要额外的在你的项目里设置OkHttp的依赖,除非你有特殊版本需求.
至此,你的项目已经做好使用Retrofit的准备了.现在我们开始创建一个持久的安卓API/HTTP客户端.
###可持续的安卓客户端
在研究现有的Retrofit客户端时,我发现了example repository of Bart Kiers.事实上,它只是一个使用Retrofit进行OAuth认证的例子.然而,它具备了构建一个可持续的安卓客户端所需要的基础原理.这就是为什么我们要使用它来作为一个好的的起点,并且我们将会在以后的文章中用更好的认证方式拓展它.

下面这个类定义了我们的安卓客户端的基础:ServiceGenerator.
###Service Generator
Service Generator是我们的API/HTTP客户端的核心.当前的代码只定义了一个方法,用来对给定的类或者接口创建一个基本的REST适配器.
####Retrofit1.9

public class ServiceGenerator {

    public static final String API_BASE_URL = "http://your.api-base.url";

    private static RestAdapter.Builder builder = new RestAdapter.Builder()
                .setEndpoint(API_BASE_URL)
                .setClient(new OkClient(new OkHttpClient()));

    public static <S> S createService(Class<S> serviceClass) {
        RestAdapter adapter = builder.build();
        return adapter.create(serviceClass);
    }
}

####Retrofit2

public class ServiceGenerator {

    public static final String API_BASE_URL = "http://your.api-base.url";

    private static OkHttpClient.Builder httpClient = new OkHttpClient.Builder();

    private static Retrofit.Builder builder =
            new Retrofit.Builder()
                    .baseUrl(API_BASE_URL)
                    .addConverterFactory(GsonConverterFactory.create());

    public static <S> S createService(Class<S> serviceClass) {
        Retrofit retrofit = builder.client(httpClient.build()).build();
        return retrofit.create(serviceClass);
    }
}

ServiceGenerator类使用了Retrofit的RestAdapter构建器来创建一个新的指定了API base url 的REST客户端.比如,Girhub的API base url 是https://api.github.com/.serviceClass为这个API请求定义一个注解类或者是接口.下面将展示一些Retrofit的常见用法和如何定义一个典型的客户端.
###Json Mapping
Retrofit1.9默认使用了谷歌的GSON.你需要做的只是根据响应来构建一个类然后响应就会被自动解析.

如果使用的是Retrofit2,你需要为你的Retrofit对象添加一个指定的转换器.现在要想使用GSON,你就需要把下面的代码添加到build.gradle文件中.

compile 'com.squareup.retrofit2:converter-gson:2.1.0'  

在你的Retrofit对象构建器中使用.addConverterFactory(GsonConverterFactory.create())就可以使用GSON来作为默认的JSON解析器了.

使用Rrtrofit

现在,我们来看一个例子,在这个例子里我们定义了一个REST客户端来向Github请求数据.首先,我们需要创建一个接口和定义需要的方法.
####GitHub Client
下面的代码定义了GitHubClient和一个用来请求一个库的参与者列表的方法.它演示了在Retrofit里使用参数替换的方法(路径中的{owner}和{repo}将会被给定的变量给替换)

Retrofit1.9
public interface GitHubClient {  
    @GET("/repos/{owner}/{repo}/contributors")
    List<Contributor> contributors(
        @Path("owner") String owner,
        @Path("repo") String repo
    );
}

#####Retrofit2

public interface GitHubClient {  
    @GET("/repos/{owner}/{repo}/contributors")
    Call<List<Contributor>> contributors(
        @Path("owner") String owner,
        @Path("repo") String repo
    );
}

下面定义了一个类Contributor.这个类包含了解析响应数据的必须格式.

static class Contributor {  
    String login;
    int contributions;
}

为了对应JSON映射,GitHubClient定义了一个返回List<Contributor>类型的contributors方法.Retrofit确保正确地映射得到的服务器响应,前提是响应内容要和给定的类要匹配.
####API Example Request
下面的代码演示了如何在你的客户端里实例化ServiceGenerator.它是Retrofit github-client example的改进版本.

当你使用这个例子的时候,你需要自己在ServiceGenerator里把base url改成"https://api.github.com".另一选择是创建一个createService方法,使得其可以接受两个参数:客户端类型和base url.
#####Retrofit1.9

public static void main(String... args) {  
    // Create a very simple REST adapter which points the GitHub API endpoint.
    GitHubClient client = ServiceGenerator.createService(GitHubClient.class);

    // Fetch and print a list of the contributors to this library.
    List<Contributor> contributors =
        client.contributors("fs_opensource", "android-boilerplate");

    for (Contributor contributor : contributors) {
        System.out.println(
                contributor.login + " (" + contributor.contributions + ")");
    }
}

#####Retrofit2

public static void main(String... args) {  
    // Create a very simple REST adapter which points the GitHub API endpoint.
    GitHubClient client = ServiceGenerator.createService(GitHubClient.class);

    // Fetch and print a list of the contributors to this library.
    Call<List<Contributor>> call =
        client.contributors("fs_opensource", "android-boilerplate");

    try {
        List<Contributor> contributors = call.execute().body();
    } catch (IOException e) {
        // handle errors
    }

    for (Contributor contributor : contributors) {
        System.out.println(
                contributor.login + " (" + contributor.contributions + ")");
    }
}

参考资料: