一、概述

1、Retrofit开源项目地址

2、Retrofit项目官网

上官网可能要梯子，大家自备，官网上有它的一系列基本用法，以及他的介绍：A type-safe HTTP client for Android and Java，它和Okhttp一样都是square公司的开源项目。

二、怎么用

1、在讲怎么用之前需要简单了解下RESTful Api：

看下面设计的三个删除评论的 api

http://test.net/?method=comment.del&id=x ①

http://test.net/comment/del/id/x ②

而 RESTful Api 则是：

[DELETE] http://test.net/comments/1 ③

我们对比可以发现①和② URL 中，都有del的动作指示。

SOAP Web API采用RPC风格，它采用面向功能的架构，所以我们在设计SOAP Web API的时候首相考虑的是应高提供怎样的功能（或者操作）。

而 RESTful Api 是面向资源的架构。是查询、新增、修改、删除，都与该资源无关。

RESTful Api 是以 HTTP 协议为强烈依托的，将类似于①和②这种以功能为主导的URL风格舍弃，还原 URL 的本质，它的宗旨就是一个 URL 就应该是一个资源，不能包含任何动作，如下所示：

- [POST]     http://test.net/users   // 新增
- [GET]      http://test.net/users/1 // 查询
- [PATCH]    http://test.net/users/1 // 更新
- [PUT]      http://test.net/users/1 // 覆盖，全部更新
- [DELETE]   http://test.net/users/1 // 删除

2、还要了解下url的简单构成：

构成一般是这样的：[scheme:][//authority][path][?query]

看下面一个url：

http://www.java2s.com:8080/yourpath/fileName.htm?stove=10&path=32&id=4

scheme: http

authority: www.java2s.com:8080

path: /yourpath/fileName.htm

query:在？后的部分为：stove=10&path=32&id=4

又由于authority又一步可以划分为host:port形式，其中host:port用冒号分隔，冒号前的是host，冒号后的是port，所以：

• host:www.java2s.com
• port:8080

这里是url中的参数，除了url中的参数还有两个http协议中常用参数是：header（请求头）和body（常用于post请求中的请求体，有多种封装方法，不暴露在url中）这两个参数。

可以看出整个网络请求中参数主要可以分成：scheme、authority、path、query、header、body这六块，下面主要看下Retrofit怎么配置这六块参数的。

3、参数配置

①scheme和authority

在retrofit中将这两者合体称为baseurl，接口用法如下：

Retrofit retrofit = new Retrofit.Builder()
    .baseUrl("https://api.github.com/")
    .build();

② header

a、静态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);

b、动态header（分为局部动态header和全局动态header）

局部动态header（分为单个键值对header和多个键值对header）：

单个键值对局部动态header：

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

多个键值对局部动态header（retrofit:2.1.0新加的）：

@GET("user")
Call<User> getUser(@HeaderMap Map<String, String> headerMap)

全局动态header（适用于项目中的header规则一致的情况）

这里是用了 OkHttp的interceptor：

private static void initHttpClient() {
        OkHttpClient.Builder httpClientBuilder = new OkHttpClient.Builder();
        if (httpClientBuilder.interceptors() != null) {
            httpClientBuilder.interceptors().clear();
        }
        httpClientBuilder.addInterceptor(new Interceptor() {
            @Override
            public Response intercept(Chain chain) throws IOException {

                //这里可以获取到请求的request所有数据
                Request request = chain.request();
                String path = request.url().encodedPath();
                Log.d("AppClient", path + ">>>path");
                String query = request.url().query();
                if (BuildConfig.DEBUG){
                    Log.d("AppClient", query + ">>>query");
                }
                //这里设置成你的全局header
                Request interRequest = chain.request().newBuilder()
                        .headers(Headers.of(Map yourHeader))
                        .build();
                return chain.proceed(interRequest);
            }
        })
                .connectTimeout(10, TimeUnit.SECONDS)
                .readTimeout(10, TimeUnit.SECONDS);

        mOkHttpClient = httpClientBuilder.build();
    }

③ path（这里只看下GET请求，POST, PUT, DELETE请求一样处理）

这里分为带参数和不带参数两种：

不带参数的：

@GET("widget/list")
Call<List<Widget>> widgetList();

带参数的：

@GET("users/{user}/repos")
Call<List<Repo>> listRepos(@Path("user") String user);

这里是通过@Path(“user”)注解实现参数传递。

④ query

以GET请求为例提供了两种注解方式（单个键值对和多个键值对），如下：

单个键值对：

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

多个键值对：

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

⑤ body

大多用于POST请求中：

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

4、Retrofit请求简单封装，这里我是将其单独封在一个类中（AppClient）

写在前面：Retrofit中网络请求实际上用的还是他自家的OkHttp，所以如果要配置请求的一些全局参数还是得先创建一个OkHttp的实例对象，然后一一配置，上面讲了配置全局header也是这样处理的，所以这里我将其使用分成了三步：

这里首先要配三个库（retrofit库，json转化库，log的截断器库）：

compile 'com.squareup.retrofit2:retrofit:2.1.0'
compile 'com.squareup.retrofit2:converter-gson:2.1.0'
compile 'com.squareup.okhttp3:logging-interceptor:3.4.0-RC1'

① 构建OkHttpClient实例（配置一些请求的全局参数）：

 private static void initHttpClient() {
        OkHttpClient.Builder httpClientBuilder = new OkHttpClient.Builder();
        httpClientBuilder.hostnameVerifier(new HostnameVerifier() {
            @Override
            public boolean verify(String hostname, SSLSession session) {
                return true;
            }
        });
        //处理拦截器，主要是做了个header和连接超时、读取超时设置，我项目里header放了些签名信息，主要是这里能拿到整个请求的所有参数，做任何想做的事，而且是全局动态处理
        if (httpClientBuilder.interceptors() != null) {
            httpClientBuilder.interceptors().clear();
        }
        httpClientBuilder.addInterceptor(new Interceptor() {
            @Override
            public Response intercept(Chain chain) throws IOException {
                Request request = chain.request();
                String path = request.url().encodedPath();
                Log.d("AppClient", path + ">>>path");
                String query = request.url().query();
                if (BuildConfig.DEBUG){
                    Log.d("AppClient", query + ">>>query");
                }
                Map<String, Object> queryParam = null;
                if (query != null){
                    queryParam = new HashMap();
                    String queryEntries[] = query.split("&");
                    for (int i = 0; i < queryEntries.length; i ++){
                        queryParam.put(queryEntries[i].split("=")[0], queryEntries[i].split("=")[1]);
                    }
                }
                if (BuildConfig.DEBUG){
                    Log.d("AppClient", "queryParam:" + queryParam + ">>>queryParam");
                }
                String signature = makeSignature_v3(path, queryParam);

                Request interRequest = chain.request().newBuilder()
                        .headers(Headers.of(getHeaders(signature)))
                        .build();
                return chain.proceed(interRequest);
            }
        })
                .connectTimeout(10, TimeUnit.SECONDS)
                .readTimeout(10, TimeUnit.SECONDS);
         //在debug模式下我使用了一个他家公司的一个log拦截器
        if (BuildConfig.DEBUG) {
            HttpLoggingInterceptor loggingInterceptor = new HttpLoggingInterceptor();
            loggingInterceptor.setLevel(HttpLoggingInterceptor.Level.BODY);
            httpClientBuilder.addInterceptor(loggingInterceptor);
        }
        //通过build模式构建实例
        mOkHttpClient = httpClientBuilder.build();
    }

这里做了四件事：

1、 httpClientBuilder.hostnameVerifier这里是针对我公司的Https证书问题，详情看这里：https证书问题

2、通过拦截器设置header，可以看上面参数设置那里的讲解

3、设置请求超时时间和读取数据时间

.connectTimeout(10, TimeUnit.SECONDS)
.readTimeout(10, TimeUnit.SECONDS);

4、设置log拦截器，这里设置之后可以在logcat中看到每个网络请求的请求参数和返回结果以及请求时长，非常好用，当然先要配置下上面我配置的第三个库；

② 构建retrofit实例：

public static Retrofit retrofit() {
        if (mRetrofit == null) {
            initHttpClient();
            mRetrofit = new Retrofit.Builder()
                    .baseUrl(BASE_URL)
                    .client(mOkHttpClient)
                    .addConverterFactory(GsonConverterFactory.create())                   .addCallAdapterFactory(RxJavaCallAdapterFactory.create())
                    .build();
        }
        return mRetrofit;
    }

这里配置可以看出，Retrofit内部也是封了一个Okhttp的实例，这里做了四件事：

1、设置了baseurl参数，可以看我上面参数配置的讲解；

2、设置了OkHttpClient实例；

3、gson转化工厂：addConverterFactory(GsonConverterFactory.create())，这里Retrofit内部会根据这个转换工厂及返回数据所指定的泛型实现直接转换；

4、网络请求的适配器工厂：addCallAdapterFactory(RxJavaCallAdapterFactory.create())，这个可以忽略暂时，因为我想买里用了RX和Retrofit一起用了，后续我会写一篇MVP+RX+Retrofit的封装使用

③ 构建call，开始网络请求并实现回调：

这里先要配置请求参数，我封了个类专门用来设置请求接口：

public interface ApiStores {
    //POST登录
    String RES_USERS_LOGIN = "users/login";
    //POST注册
    String RES_USERS_REGISTER = "users";

    @POST(RES_USERS_LOGIN)
    Observable<Map> login(@Body Map<String, String> body);

    @POST(RES_USERS_REGISTER)
    Observable<Map> register(@Body Map<String, String> body);

}

构建call实例对象，开始网络请求并实现回调：

public void login(String cityId, final String cityName, final String mobile, String password, final OnLoginListener listener) {
        Map<String, String> body = new HashMap<>();
        body.put("mobile", mobile);
        body.put("password", password);
        body.put("city", cityId);
        body.put("embed", "home");       
        ApiStores apiStores = AppClient.retrofit().create(ApiStores.class);
        //这里通过指定Map泛型集合上面的Gson转换工厂实现返回数据json转换成Map
        Call<Map> call = apiStores.login(body);
        call.enqueue(new Callback<Map>() {
            @Override
            public void onResponse(Call<Map> call, Response<Map> response) {
                //请求成功做的事情，这里两个参数：call是请求时候的call实例，可以拿到请求的request实例，response是服务端返回的参数，里面包含了code和body(这里的body类型是通过call指定的泛型和Gson转换工厂实现的)，message一系列数据。
            }

            @Override
            public void onFailure(Call<Map> call, Throwable t) {
                //请求失败做的事情，call和上面一样，外加一个Throwable
            }
        });

三、小结

Retrofit这个库将ResfulApi的几种请求都通过注解进行了一系列封装，整个请求流程比OkHttp简洁了很多，同时它可以通过设置GSON转换工厂内部实现返回数据的转化，使用过程非常简洁清晰，同时可以配合现在流行的RXjava一起使用，下面我准备搞一篇MVP+RX+Retrofit的封装使用，Okhttp可以换啦！

如有不足之处还请大家多多指正！