开始在Android上使用Retrofit并创建Http请求客户

什么是Retrofit

官方对Retrofit的定义是：一个在Android和Java中类型安全的REST客户端
你可以使用注解去描述HTTP请求，URL 参数替换和查询参数这些都默认的得到完整的支持。此外，它还提供了自定义请求头、多种类型请求体、文件上传和下载、模拟相应和其他更多的功能。接下来我们将会看到这些具体是实现详细。

先准备你的安卓项目

在android studio上用Gradle构建你的新项目。当然也可以选择在IDE上用Maven构建项目。

定义依赖库：Gradle or Maven

首先你的项目需要依赖Retrofit。在你所选的编译系统中，在文件build.gradle 或 pom.xml 中导入你所以依赖的指定Retrofit版本，当运行去编译代码的时候，这个编译系统会下载和提供制定的依赖库到你的项目中。

Retrofit2

build.gradle

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

##Android网络权限
用Retrofit进行网络请求需要在AndroidManifest.xml中添加网络权限
```Java
<uses-permission android:name="android.permission.INTERNET" />  ```

##如何描述API端点
首先你需要定义接口和对应的请求方法

##GitHub Client
以下demo定义了GitHubClient接口和reposForUser方法去请求一组仓库贡献者列表数据。其中@GET注解描述了这个请求用了HTTP GET方法。这段demo也阐明了Retrofit路径参数替换的功能用法。这个定义的方法中的｛user｝路径将会被调用reposForUser方法中的变量值所替换。
```Java
public interface GitHubClient {  
    @GET("/users/{user}/repos")
    Call<List<GitHubRepo>> reposForUser(
        @Path("user") String user
    );
}```
GitHubRepo类定义。这个类包含的必须属性和响应数据一一对应。
```Java
public class GitHubRepo {  
    private int id;
    private String name;

    public GitHubRepo() {
    }

    public int getId() {
        return id;
    }

    public String getName() {
        return name;
    }
}```

关于先前提到的JSON映射：GitHubClient接口定义的返回类型为List<GitHubRepo>的方法。Retrofit 可以确保服务器响应
的数据映射的正确性。（就是返回的响应数据会和被给的类GitHubRepo的数据相对应）
##Retrofit REST 客户端
描述完了API接口和对象模型之后，我们就可以进行真正的请求了。Retrofit的所有请求都是基于1.9或2.0+版本。这两个版本你都可以很流畅的创建和配置API。最后，你可以使用builder来对所有请求设置一些设置一些常用的选项，比如：url或者转换器。

####Retrofit 2
```Java
String API_BASE_URL = "https://api.github.com/";

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

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

Retrofit retrofit =  
    builder
        .client(
            httpClient.build()
        )
        .build();

GitHubClient client =  retrofit.create(GitHubClient.class); 
}```
上面的demo片段使用了最简单的设置选项，还有更多的设置选项让你去控制请求。但是这已经足够我们用来作为第一个请求的列子了。
##JSON 映射
大多数情况下，请求服务器和服务器响应返回数据，都不是用java对象。更多的是用像JSON这种格式的语言来传。
当使用Retrofit 2，你需要向Retrofit对象添加一个转换器，将返回的JSON数据转成对应给的类对象。在build.gradle文件中添加一行下面这个代码，引进Gson转换器给Retrofit 2用。
```Java
compile 'com.squareup.retrofit2:converter-gson:2.1.0'```
当然你也用转换器来转换xml等其他格式的数据,请参考：
[转换器转换其他格式](https://futurestud.io/tutorials/retrofit-2-introduction-to-multiple-converters "")
##Retrofit 的使用
在大量的准备工作之后，现在可以很简便的请求。只用几行demo就可以进行请求
#### Retrofit 2
使用client去获取call对象。只要你用获取的call对象调用.enqueue，请求将会被Retrofit处理。
```Java
// Create a very simple REST adapter which points the GitHub API endpoint.
GitHubClient client =  retrofit.create(GitHubClient.class);

// Fetch a list of the Github repositories.
Call<List<GitHubRepo>> call =  
    client.reposForUser("fs-opensource");

// Execute the call asynchronously. Get a positive or negative callback.
call.enqueue(new Callback<List<GitHubRepo>>() {  
    @Override
    public void onResponse(Call<List<GitHubRepo>> call, Response<List<GitHubRepo>> response) {
        // The network call was a success and we got a response
        // TODO: use the repository list and display it
    }

    @Override
    public void onFailure(Call<List<GitHubRepo>> call, Throwable t) {
        // the network call was a failure
        // TODO: handle error
    }
});```
当调用成功之后，Retrofit 会返回一个方便的List<GitHubRepo>,你可以使用它显示在你的app上。
译至：
[https://futurestud.io/tutorials/retrofit-getting-started-and-android-client](https://futurestud.io/tutorials/retrofit-getting-started-and-android-client"")