Android Retrofit框架解析

随着Google对HttpClient的摒弃,和Volley的逐渐没落,OkHttp开始异军突起,而Retrofit则对okHttp进行了强制依赖。Retrofit也是Square公司开发的一款针对Android网络请求的框架，其实质就是对okHttp的封装，使用面向接口的方式进行网络请求，利用动态生成的代理类封装了网络接口。retrofit非常适合于RESTful url格式的请求，更多使用注解的方式提供功能。

既然是RESTful架构,那么我们就来看一下什么是REST吧。
REST(REpresentational State Transfer)是一组架构约束条件和原则。RESTful架构都满足以下规则：
（1）每一个URI代表一种资源；
（2）客户端和服务器之间，传递这种资源的某种表现层；
（3）客户端通过四个HTTP动词（GET，POST，PUT，DELETE），对服务器端资源进行操作，实现”表现层状态转化”。
更多关于REST的介绍

使用Retrofit2.0

Eclipse的用户，添加Jar包和网络访问权限
下载最新的jar：我将整理的所有jar包已上传
注意：
1.Retrofit必须使用okhttp请求了，如果项目中没有okhttp的依赖的话，肯定会出错 。
2.okhttp内部依赖okio所以也要添加。

<uses-permission android:name="android.permission.INTERNET"/>

用法介绍

创建API接口

在retrofit中通过一个Java接口作为http请求的api接口。

//定以接口
public interface GitHubService {
  @GET("users/{user}/repos")
  Call> listRepos(@Path("user") String user);
}

创建retrofit实例

/**获取实例*/
Retrofit retrofit = new Retrofit.Builder()
    //设置OKHttpClient,如果不设置会提供一个默认的
    .client(new OkHttpClient())
    //设置baseUrl
    .baseUrl("https://api.github.com/")
    //添加Gson转换器
    .addConverterFactory(GsonConverterFactory.create())
    .build();

注：
1.retrofit2.0后：BaseUrl要以/结尾；@GET 等请求不要以/开头；@Url: 可以定义完整url，不要以 / 开头。
2.addConverterFactory提供Gson支持，可以添加多种序列化Factory，但是GsonConverterFactory必须放在最后,否则会抛出异常。

调用API接口

GitHubService service = retrofit.create(GitHubService.class);

//同步请求
//https://api.github.com/users/octocat/repos
Call> call = service.listRepos("octocat");
try {
     Response> repos  = call.execute();
} catch (IOException e) {
     e.printStackTrace();
}

//不管同步还是异步，call只能执行一次。否则会抛 IllegalStateException
Call> clone = call.clone();

//异步请求
clone.enqueue(new Callback>() {
        @Override
        public void onResponse(Response> response, Retrofit retrofit) {
            // Get result bean from response.body()
            List repos = response.body();
            // Get header item from response
            String links = response.headers().get("Link");
            /**
            * 不同于retrofit1 可以同时操作序列化数据javabean和header
            */
        }

        @Override
        public void onFailure(Throwable throwable) {
            showlog(throwable.getCause().toString());   
        }
});

取消请求

我们可以终止一个请求。终止操作是对底层的httpclient执行cancel操作。即使是正在执行的请求，也能够立即终止。

call.cancel();

retrofit注解

• 方法注解，包含@GET、@POST、@PUT、@DELETE、@PATH、@HEAD、@OPTIONS、@HTTP。
• 标记注解，包含@FormUrlEncoded、@Multipart、@Streaming。
• 参数注解，包含@Query、@QueryMap、@Body、@Field，@FieldMap、@Part，@PartMap。
• 其他注解，包含@Path、@Header、@Headers、@Url。

(1)一般的get请求

public interface IWeatherGet {
    @GET("GetMoreWeather?cityCode=101020100&weatherType=0")
    Call getWeather();
}

可以看到有一个getWeather(）方法，通过@GET注解标识为get请求，@GET中所填写的value和baseUrl组成完整的路径，baseUrl在构造retrofit对象时给出。

Retrofit retrofit = new Retrofit.Builder()
        /**http://weather.51wnl.com/weatherinfo/GetMoreWeather?cityCode=101020100&weatherType=0*/
        //注意baseurl要以/结尾
                .baseUrl("http://weather.51wnl.com/weatherinfo/")
                .addConverterFactory(GsonConverterFactory.create())
                .build();
IWeatherGet weather = retrofit.create(IWeatherGet.class);
Call call = weather.getWeather();
call.enqueue(new Callback() {
    @Override
    public void onResponse(Response response, Retrofit retrofit) {
        Weather weather = response.body();
        WeatherInfo weatherinfo = weather.weatherinfo;
        showlog("weather="+weatherinfo.toString());
    }

@Override
    public void onFailure(Throwable throwable) {
        showlog(throwable.getCause().toString());       
    }
});

（2）动态url访问@PATH

上面说的@GET注解是将baseUrl和@GET中的value组成完整的路径。有时候我们可以将路径中某个字符串设置为不同的值来请求不同的数据，这时候怎么办呢？
譬如：

//用于访问上海天气
http://weather.51wnl.com/weatherinfo/GetMoreWeather?cityCode=101020100&weatherType=0
//用于访问上海人口（这里只是假设，其实这个url并不能返回json）
http://weather.51wnl.com/weatherinfo/GetMorePeople?cityCode=101010100&weatherType=0

即通过不同的请求字符串访问不同的信息，返回数据为json字符串。那么可以通过retrofit提供的@PATH注解非常方便的完成上述需求。

public interface IWeatherPath {
    @GET("{info}?cityCode=101020100&weatherType=0")
    Call getWeather(@Path("info") String info);
}

可以看到我们定义了一个getWeather方法，方法接收一个info参数，并且我们的@GET注解中使用{info}?cityCode=101020100&weatherType=0声明了访问路径，这里你可以把{info}当做占位符，而实际运行中会通过@PATH(“info”)所标注的参数进行替换。

Retrofit retrofit = new Retrofit.Builder()
                .baseUrl("http://weather.51wnl.com/weatherinfo/")
                .addConverterFactory(GsonConverterFactory.create())
                .build();
IWeatherPath weather = retrofit.create(IWeatherPath.class);
Call call = weather.getWeather("GetMoreWeather");
call.enqueue(new Callback() {
    @Override
    public void onResponse(Response response, Retrofit retrofit) {
        Weather weather = response.body();
        WeatherInfo weatherinfo = weather.weatherinfo;
        showlog("weather="+weatherinfo.toString());
    }

    @Override
    public void onFailure(Throwable throwable) {
        showlog(throwable.getCause().toString());       
    }
});

（3）查询参数的设置@Query@QueryMap

文章开头提过，retrofit非常适用于restful url的格式，那么例如下面这样的url：

//用于访问上海天气
http://weather.51wnl.com/weatherinfo/GetMoreWeather?cityCode=101020100&weatherType=0
//用于访问北京天气
http://weather.51wnl.com/weatherinfo/GetMoreWeather?cityCode=101010100&weatherType=0

即通过传参方式使用不同的citycode访问不同城市的天气，返回数据为json字符串。我们可以通过@Query注解方便的完成，我们再次在接口中添加一个方法：

public interface IWeatherQuery {
    @GET("GetMoreWeather")
    Call getWeather(@Query("cityCode") String cityCode, @Query("weatherType") String weatherType);
}

/**省略retrofit的构建代码*/
Call call = weather.getWeather("101020100", "0");
//Call call = weather.getWeather("101010100", "0");
/**省略call执行相关代码*/

当我们的参数过多的时候我们可以通过@QueryMap注解和map对象参数来指定每个表单项的Key，value的值，同样是上面的例子，还可以这样写：

public interface IWeatherQueryMap {
    @GET("GetMoreWeather")
    Call getWeather(@QueryMap Map map);
}

//省略retrofit的构建代码
Map<String, String> map = new HashMap<String, String>();
map.put("cityCode", "101020100");
map.put("weatherType", "0");
Call<Weather> call = weather.getWeather(map);
//省略call执行相关代码

这样我们就完成了参数的指定，当然相同的方式也适用于POST，只需要把注解修改为@POST即可。
注：对于下面的写法：

@GET("GetMoreWeather?cityCode={citycode}&weatherType=0")
Call getWeather(@Path("citycode") String citycode);

乍一看可以啊，实际上运行是不支持的~估计是@Path的定位就是用于url的路径而不是参数，对于参数还是选择通过@Query来设置。

（4）POST请求体方式向服务器传入json字符串@Body

我们app很多时候跟服务器通信，会选择直接使用POST方式将json字符串作为请求体发送到服务器，那么我们看看这个需求使用retrofit该如何实现。

public interface IUser {
 @POST("add")
 Call> addUser(@Body User user);
}

/省略retrofit的构建代码
 CallUser>> call = user.addUser(new User("watson", "male", "28"));
//省略call执行相关代码

可以看到其实就是使用@Body这个注解标识我们的参数对象即可，那么这里需要考虑一个问题，retrofit是如何将user对象转化为字符串呢？将实例对象根据转换方式转换为对应的json字符串参数，这个转化方式是GsonConverterFactory定义的。

对应okhttp，还有两种requestBody，一个是FormBody，一个是MultipartBody，前者以表单的方式传递简单的键值对，后者以POST表单的方式上传文件可以携带参数，retrofit也二者也有对应的注解，下面继续~

（5）表单的方式传递键值对@FormUrlEncoded + @Field@FieldMap

这里我们模拟一个登录的方法，添加一个方法：

public interface IUser {
    @FormUrlEncoded
    @POST("login")   
    Call login(@Field("username") String username, @Field("password") String password);
}

//省略retrofit的构建代码
Call<User> call = user.login("watson", "123");
//省略call执行相关代码

看起来也很简单，通过@POST指明url，添加FormUrlEncoded，然后通过@Field添加参数即可。
当我们有很多个表单参数时也可以通过@FieldMap注解和Map对象参数来指定每个表单项的Key，value的值。

public interface IUser {
    @FormUrlEncoded
    @POST("login")   
    Call login(@FieldMap Map fieldMap);
}

//省略retrofit的构建代码
Map<String, String> propertity = new HashMap<String, String>();
positories.put("name", "watson");
positories.put("password", "123");
Call<User> call = user.login(propertity);
//省略call执行相关代码

（6）文件上传@Multipart + @Part@PartMap

涉及到操作硬盘文件，首先需要添加权限：

<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

1.下面先看一下单文件上传，依然是再次添加个方法：

public interface IUser {
    @Multipart
    @POST("register")
    Call registerUser(@Part MultipartBody.Part photo, @Part("username") RequestBody username, @Part("password") RequestBody password);
}

这里@MultiPart的意思就是允许多个@Part了，我们这里使用了3个@Part，第一个我们准备上传个文件，使用了MultipartBody.Part类型，其余两个均为简单的键值对。

File file = new File(Environment.getExternalStorageDirectory(), "icon.png");
RequestBody photoRequestBody = RequestBody.create(MediaType.parse("image/png"), file);
/**第一个参数name与文件一一对应，如果多文件上传，每个文件name不能一样**/
MultipartBody.Part photo = MultipartBody.Part.createFormData("photos", "icon.png", photoRequestBody);

Call call = user.registerUser(photo, RequestBody.create(null, "abc"), RequestBody.create(null, "123"));

这里感觉略为麻烦。不过还是蛮好理解~~多个@Part，每个Part对应一个RequestBody。

注：这里还有另外一个方案也是可行的：

public interface ApiInterface {
        @Multipart
        @POST ("/api/Accounts/editaccount")
        Call editUser (@Header("Authorization") String authorization, @Part("photos\"; filename=\"icon.png") RequestBody file , @Part("FirstName") RequestBody fname, @Part("Id") RequestBody id);
}

这个value设置的值不用看就会觉得特别奇怪，然而却可以正常执行，原因是什么呢？
当上传key-value的时候，实际上对应这样的代码：

builder.addPart(Headers.of("Content-Disposition", "form-data; name=\"" + key + "\""), RequestBody.create(null, params.get(key)));

也就是说，我们的@Part转化为了

Headers.of("Content-Disposition", "form-data; name=\"" + key + "\"")

这么一看，很随意，只要把key放进去就可以了。但是，retrofit2并没有对文件做特殊处理，文件的对应的字符串应该是这样的

Headers.of("Content-Disposition", "form-data; name="photos";filename="icon.png"");

与键值对对应的字符串相比，多了个\”; filename=\”icon.png，就因为retrofit没有做特殊处理，所以你现在看这些hack的做法

@Part("photos\"; filename=\"icon.png")
==> key = photos\"; filename=\"icon.png

form-data; name=\"" + key + "\"
拼接结果：==>
form-data; name="photos"; filename="icon.png"

因为这种方式文件名写死了，我们上文使用的的是@Part MultipartBody.Part file,可以满足文件名动态设置。

2.如果是多文件上传呢？

public interface IUser {
     @Multipart
     @POST("register")
     Call registerUser(@PartMap Map params, @Part("password") RequestBody password);
}

这里使用了一个新的注解@PartMap，这个注解用于标识一个Map，Map的key为String类型，代表上传的键值对的key(与服务器接受的key对应),value即为RequestBody，有点类似@Part的封装版本。

Map<String, RequestBody> map = new HashMap<>(String, RequestBody);
File file = new File(Environment.getExternalStorageDirectory(), "local.png");
RequestBody photo = RequestBody.create(MediaType.parse("image/png", file);
map.put("photo1\"; filename=\"local.png", photo);
File file = new File(Environment.getExternalStorageDirectory(), "local2.png");
RequestBody photo2 = RequestBody.create(MediaType.parse("image/png", file2);
map.put("photo2\"; filename=\"local2.png", photo2);
map.put("username",  RequestBody.create(null, "abc"));

Call call = user.registerUser(map, RequestBody.create(null, "123"));

可以看到，可以在Map中put进一个或多个文件，键值对等，当然你也可以分开，单独的键值对也可以使用@Part，这里又看到设置文件的时候，相对应的key很奇怪，例如上例”photo1\”; filename=\”local.png”,前面的photo1就是与服务器对应的key，后面filename是服务器得到的文件名，ok，参数虽然奇怪，但是也可以动态的设置文件名，不影响使用。

总结一下，上传多文件几种方式：
（1）

    @Multipart
    @POST(HttpConstant.Upload)
    Single uploadImages(@Part() List partList);

    public Single uploadImages(ArrayList images) {
        List partList = new ArrayList<>(images.size());
        for (ImageItem item : images) {
            File file = new File(item.path);
            // 创建RequestBody，用于封装构建RequestBody
            String format = FileUtil.getFileFormat(item.path);
            RequestBody requestBody  = RequestBody.create(MediaType.parse("image/"+format), file);
            /** 创建MultipartBody.Part, 第一个参数name必须与文件一一对应**/
            MultipartBody.Part part = MultipartBody.Part.createFormData(file.getName(), file.getName(), requestBody);
            partList.add(part);
        }
        return getRetrofit(IEditApi.class, HttpConstant.BaseUploadUrl).uploadImages(partList);
    }

（2）

    @Multipart
    @POST(HttpConstant.Upload)
    Single uploadImages(@PartMap Map params);

    public Single uploadImagesWithProgress(ArrayList images) {
        Map map = new HashMap<>(images.size());
        for (ImageItem item : images) {
            File file = new File(item.path);
            // 创建RequestBody，用于封装构建RequestBody
            String format = FileUtil.getFileFormat(item.path);
            RequestBody requestBody  = RequestBody.create(MediaType.parse("image/"+format), file);
            map.put(file.getName() + "\"; filename=\""+ file.getName(), requestBody);
        }
        return getRetrofit(IEditApi.class, HttpConstant.BaseUploadUrl).uploadImages(map);
    }

（3）

    @POST(HttpConstant.Upload)
    Single uploadImages(@Body MultipartBody multipartBody);

    public Single uploadImageWithMultipartBody(ArrayList images) {
        MultipartBody.Builder muBuilder = new MultipartBody.Builder();
        for (int i=0; i
            File file = new File(images.get(i).path);
            String format = FileUtil.getFileFormat(images.get(i).path);
            RequestBody requestBody = RequestBody.create(MediaType.parse("image/"+format), file);
            muBuilder.addFormDataPart(file.getName(),file.getName(), requestBody);
        }
        muBuilder.setType(MultipartBody.FORM);
        MultipartBody multipartBody = muBuilder.build();
        return getRetrofit(IEditApi.class, HttpConstant.BaseUploadUrl).uploadImages(multipartBody);
    }

可以参考文章Retrofit2 multpart多文件上传详解。

还有最后一个问题，如何实现带进度的上传呢？
可以参考文章retrofit2 上传进度回调2中方法。

（7）下载文件

下载文件还是推荐OkHttp方式，这里对retrofit下载也进行说明一下

@GET("download")
Call downloadTest();

Call call = user.downloadTest();
call.enqueue(new Callback() {
    @Override
    public void onResponse(Call call, Response response) {
        InputStream is = response.body().byteStream();
        //save file
    }

    @Override
    public void onFailure(Call call, Throwable t){}
});

可以看到这种方式下载非常鸡肋，onReponse回调虽然在UI线程，但是你还是要处理io操作，也就是说你在这里还要另外开线程操作，或者你可以考虑同步的方式下载。所以还是建议使用okhttp去下载。

（8）添加请求头@Header@Headers

@Header：header处理，不能被互相覆盖，所有具有相同名字的header将会被包含到请求中。

//静态设置Header值
@Headers("Authorization: authorization")
@GET("widget/list")
Call getUser()

@Headers 用于修饰方法,用于设置多个Header值。

@Headers({
    "Accept: application/vnd.github.v3.full+json",
    "User-Agent: Retrofit-Sample-App"
})
@GET("users/{username}")
Call getUser(@Path("username") String username);

还可以使用@Header注解动态的更新一个请求的header。必须给@Header提供相应的参数，如果参数的值为空header将会被忽略，否则就调用参数值的toString()方法并使用返回结果。

//动态设置Header值
@GET("user")
Call getUser(@Header("Authorization") String authorization)

配置OkHttpClient

很多时候，比如你使用retrofit需要统一的log管理，缓存管理，给每个请求添加统一的header等，这些都应该通过okhttpclient去操作。Retrofit 2.0 底层依赖于okHttp，所以需要使用okHttp的Interceptors来对所有请求进行拦截。

OkHttpClient client = new OkHttpClient();
client.networkInterceptors().add(new Interceptor() {
    @Override
    public com.squareup.okhttp.Response intercept(Chain chain) throws IOException {
        com.squareup.okhttp.Response response = chain.proceed(chain.request());

        // Do anything with response here

        return response;
    }
});
Retrofit retrofit = new Retrofit.Builder()
        .baseUrl(BASE_URL)
        ...
        .client(client) //传入自己定义的client
        .build();

或许你需要更多的配置，你可以单独写一个OkhttpClient的单例生成类，在这个里面完成你所需的所有的配置，然后将OkhttpClient实例通过方法公布出来，设置给retrofit。

Retrofit retrofit = new Retrofit.Builder()
    .callFactory(OkHttpUtils.getClient())
    .build();

callFactory方法接受一个okhttp3.Call.Factory对象，OkHttpClient即为一个实现类。

转换器Converter

在上面的例子中通过获取ResponseBody后，我们自己使用Gson来解析接收到的Json格式数据。在Retrofit中当创建一个Retrofit实例的时候可以为其添加一个Json转换器，这样就会自动将Json格式的响应体转换为所需要的Java对象。

Retrofit retrofit = new Retrofit.Builder()
        .baseUrl(BASE_URL)
        .addConverterFactory(GsonConverterFactory.create()) //转换器
        .build();

默认转换器

默认情况下，Retrofit只能够反序列化Http体为OkHttp的ResponseBody类型，并且只能够接受ResponseBody类型的参数作为@body。
添加转换器可以支持其他的类型，为了方便的适应流行的序列化库，Retrofit提供了六个兄弟模块：

• Gson : com.squareup.retrofit:converter-gson
• Jackson: com.squareup.retrofit:converter-jackson
• Moshi: com.squareup.retrofit:converter-moshi
• Protobuf: com.squareup.retrofit:converter-protobuf
• Wire: com.squareup.retrofit:converter-wire
• Simple XML: com.squareup.retrofit:converter-simplexml

自定义转换器

关于Converter.Factory，肯定是通过addConverterFactory设置的

Retrofit retrofit = new Retrofit.Builder()
        .addConverterFactory(GsonConverterFactory.create())
        .build();

该方法接受的是一个Converter.Factory factory对象，该对象是一个抽象类，内部包含3个方法：

abstract class Factory {

    public Converter responseBodyConverter(Type type, Annotation[] annotations, Retrofit retrofit) {
      return null;
    }

    public Converter requestBodyConverter(Type type, Annotation[] parameterAnnotations, Annotation[] methodAnnotations, Retrofit retrofit) {
      return null;
    }

    public Converter stringConverter(Type type, Annotation[] annotations, Retrofit retrofit) {
      return null;
    }
  }

可以看到呢，3个方法都是空方法而不是抽象的方法，也就表明了我们可以选择去实现其中的1个或多个方法，一般只需要关注requestBodyConverter和responseBodyConverter就可以了。

（1）responseBodyConverter
实现responseBodyConverter方法，看这个名字很好理解，就是将responseBody进行转化就可以了。
假设我们这里去掉retrofit构造时的GsonConverterFactory.create，自己实现一个Converter.Factory来做数据的转化工作。首先我们解决responseBodyConverter，那么代码很简单，我们可以这么写：

public class UserConverterFactory extends Converter.Factory
{
    @Override
    public Converter?> responseBodyConverter(Type type, Annotation[] annotations, Retrofit retrofit)
    {
        //根据type判断是否是自己能处理的类型，不能的话，return null ,交给后面的Converter.Factory
        return new UserResponseConverter(type);
    }

}

public class UserResponseConverter<T> implements Converter<ResponseBody, T>
{
    private Type type;
    Gson gson = new Gson();

    public UserResponseConverter(Type type)
    {
        this.type = type;
    }

    @Override
    public T convert(ResponseBody responseBody) throws IOException
    {
        String result = responseBody.string();
        T users = gson.fromJson(result, type);
        return users;
    }
}

使用自定义UserConverterFactory

Retrofit retrofit = new Retrofit.Builder()
     .callFactory(new OkHttpClient())
     .baseUrl("http://example/springmvc_users/user/")
     .addConverterFactory(new UserConverterFactory())
     .build();

这样的话，就可以完成我们的ReponseBody到List<\User>或者User的转化了。
可以看出，我们这里用的依然是Gson，那么有些同学肯定不希望使用Gson就能实现，如果不使用Gson的话，一般需要针对具体的返回类型，比如我们针对返回List<\User>或者User

public class UserResponseConverter implements Converter {
    private Type type;
    Gson gson = new Gson();

    public UserResponseConverter(Type type) {
        this.type = type;
    }

    @Override
    public T convert(ResponseBody responseBody) throws IOException {
        String result = responseBody.string();

        if (result.startsWith("[")) {
            return (T) parseUsers(result);
        } else {
            return (T) parseUser(result);
        }
    }

    private User parseUser(String result) {
        JSONObject jsonObject = null;
        try {
            jsonObject = new JSONObject(result);
            User u = new User();
            u.setUsername(jsonObject.getString("username"));
            return u;
        } catch (JSONException e) {
            e.printStackTrace();
        }
        return null;
    }

    private List parseUsers(String result) {
        List users = new ArrayList<>();
        try {
            JSONArray jsonArray = new JSONArray(result);
            User u = null;
            for (int i = 0; i < jsonArray.length(); i++) {
                JSONObject jsonObject = jsonArray.getJSONObject(i);
                u = new User();
                u.setUsername(jsonObject.getString("username"));
                users.add(u);
            }
        } catch (JSONException e) {
            e.printStackTrace();
        }
        return users;
    }
}

这里简单读取了一个属性，大家肯定能看懂，这样就能实现我们的ReponseBody到List<\User>或者User的转化了。
这里郑重提醒：如果你针对特定的类型去写Converter，一定要在UserConverterFactory#responseBodyConverter中对类型进行检查，发现不能处理的类型return null，这样的话，可以交给后面的Converter.Factory处理，比如本例我们可以按照下列方式检查:

public class UserConverterFactory extends Converter.Factory {
    @Override
    public Converter responseBodyConverter(Type type, Annotation[] annotations, Retrofit retrofit) {
        //根据type判断是否是自己能处理的类型，不能的话，return null ,交给后面的Converter.Factory
        if (type == User.class)//支持返回值是User
        {
            return new UserResponseConverter(type);
        }

        if (type instanceof ParameterizedType)//支持返回值是List
        {
            Type rawType = ((ParameterizedType) type).getRawType();
            Type actualType = ((ParameterizedType) type).getActualTypeArguments()[0];
            if (rawType == List.class && actualType == User.class) {
                return new UserResponseConverter(type);
            }
        }
        return null;
    }
}

（2）requestBodyConverter
上面接口一大串方法呢，使用了我们的Converter之后，有个方法我们现在还是不支持的。

@POST("add")
CallUser>> addUser(@Body User user);

这个@Body需要用到这个方法，叫做requestBodyConverter，根据参数转化为RequestBody，下面看下我们如何提供支持。

public class UserRequestBodyConverter<T> implements Converter<T, RequestBody> {
    private Gson mGson = new Gson();
    @Override
    public RequestBody convert(T value) throws IOException {
        String string = mGson.toJson(value);
        return RequestBody.create(MediaType.parse("application/json; charset=UTF-8"),string);
    }
}

然后在UserConverterFactory中复写requestBodyConverter方法，返回即可：

public class UserConverterFactory extends Converter.Factory
{

    @Override
    public Converter requestBodyConverter(Type type, Annotation[] parameterAnnotations, Annotation[] methodAnnotations, Retrofit retrofit) {
        return new UserRequestBodyConverter<>();
    }
}

ok,到这里，我相信如果你看的细致，相信已经学会了如何自定义Converter.Factory，但是我还是要总结下：
1. responseBodyConverter：主要完成ResponseBody到实际的返回类型的转化，这个类型对应Call<\XXX>里面的泛型XXX。
2. requestBodyConverter：完成对象到RequestBody的构造。主要是对应@Body注解，其实@Part等注解也会需要requestBodyConverter，只不过我们的参数类型都是RequestBody，由默认的converter处理了。
3. 一定要注意，检查type如果不是自己能处理的类型，记得return null （因为可以添加多个，你不能处理return null ,还会去遍历后面的converter）.

Retrofit2.0源码分析

接下来我们对retrofit的源码做简单的分析，首先我们看retrofit如何为我们的接口实现实例；然后看整体的执行流程；最后再看详细的细节；
（1）retrofit如何为我们的接口实现实例
使用retrofit需要去定义一个接口，然后可以通过调用retrofit.create(IUser.class);方法，得到一个接口的实例，最后通过该实例执行我们的操作，那么retrofit如何实现我们指定接口的实例呢？
其实原理是：动态代理。但是不要被动态代理这几个词吓唬到，Java中已经提供了非常简单的API帮助我们来实现动态代理。
看源码前先看一个例子：

public interface ITest
{
    @GET("/heiheihei")
    public void add(int a, int b);

}
public static void main(String[] args)
{
    ITest iTest = (ITest) Proxy.newProxyInstance(ITest.class.getClassLoader(), new Class[]{ITest.class}, new InvocationHandler()
    {
        @Override
        public Object invoke(Object proxy, Method method, Object[] args) throws Throwable
        {
            Integer a = (Integer) args[0];
            Integer b = (Integer) args[1];
            System.out.println("方法名：" + method.getName());
            System.out.println("参数：" + a + " , " + b);

            GET get = method.getAnnotation(GET.class);
            System.out.println("注解：" + get.value());
            return null;
        }
    });
    iTest.add(3, 5);
}

输出结果为：

方法名：add
参数：3 , 5
注解：/heiheihei

可以看到我们通过Proxy.newProxyInstance产生的代理类，当调用接口的任何方法时，都会调用InvocationHandler#invoke方法，在这个方法中可以拿到传入的参数，注解等。
其实retrofit也可以通过同样的方式，在invoke方法里面，拿到所有的参数，注解信息然后就可以去构造RequestBody，再去构建Request，得到Call对象封装后返回。
下面看retrofit#create的源码：

public  T create(final Class service) {
    return (T) Proxy.newProxyInstance(service.getClassLoader(), new Class[] { service },
        new InvocationHandler() {
            @Override 
            public Object invoke(Object proxy, Method method, Object... args) throws Throwable {
       });
  }

和上面对应。到这里，你应该明白retrofit为我们接口生成实例对象并不神奇，仅仅是使用了Proxy这个类的API而已，然后在invoke方法里面拿到足够的信息去构建最终返回的Call而已。

（2）retrofit整体实现流程
Retrofit的构建：这里依然是通过构造者模式进行构建retrofit对象，好在其内部的成员变量比较少，我们直接看build()方法。

public Builder() {
    this(Platform.get());
}

public Retrofit build() {
  if (baseUrl == null) {
    throw new IllegalStateException("Base URL required.");
  }

  okhttp3.Call.Factory callFactory = this.callFactory;
  if (callFactory == null) {
    callFactory = new OkHttpClient();
  }

  Executor callbackExecutor = this.callbackExecutor;
  if (callbackExecutor == null) {
    callbackExecutor = platform.defaultCallbackExecutor();
  }

  // Make a defensive copy of the adapters and add the default Call adapter.
  List adapterFactories = new ArrayList<>(this.adapterFactories);
  adapterFactories.add(platform.defaultCallAdapterFactory(callbackExecutor));

  // Make a defensive copy of the converters.
  List converterFactories = new ArrayList<>(this.converterFactories);

  return new Retrofit(callFactory, baseUrl, converterFactories, adapterFactories,
      callbackExecutor, validateEagerly);
}

baseUrl必须指定，这个是理所当然的；
然后可以看到如果不着急设置callFactory，则默认直接new OkHttpClient()，可见如果你需要对okhttpclient进行详细的设置，需要构建OkHttpClient对象，然后传入；
接下来是callbackExecutor，这个想一想大概是用来将回调传递到UI线程了，当然这里设计的比较巧妙，利用platform对象，对平台进行判断，判断主要是利用Class.forName(“”)进行查找，如果是Android平台，会自定义一个Executor对象，并且利用Looper.getMainLooper()实例化一个handler对象，在Executor内部通过handler.post(runnable)，ok，整理凭大脑应该能构思出来，暂不贴代码了。
接下来是adapterFactories，这个对象主要用于对Call进行转化，基本上不需要我们自己去自定义。
最后是converterFactories，该对象用于转化数据，例如将返回的responseBody转化为对象等；当然不仅仅是针对返回的数据，还能用于一般备注解的参数的转化例如@Body标识的对象做一些操作，后面遇到源码详细再描述。

具体Call构建流程：我们构造完成retrofit，就可以利用retrofit.create方法去构建接口的实例了，上面我们已经分析了这个环节利用了动态代理，而且我们也分析了具体的Call的构建流程在invoke方法中，下面看代码：

public <T> T create(final Class<T> service) {
    Utils.validateServiceInterface(service);
    //...
    return (T) Proxy.newProxyInstance(service.getClassLoader(), new Class[] { service },
        new InvocationHandler() {
           @Override 
          public Object invoke(Object proxy, Method method, Object... args){
            //...
            ServiceMethod serviceMethod = loadServiceMethod(method);
            OkHttpCall okHttpCall = new OkHttpCall<>(serviceMethod, args);
            return serviceMethod.callAdapter.adapt(okHttpCall);
          }
        });
}

主要也就三行代码，第一行是根据我们的method将其包装成ServiceMethod，第二行是通过ServiceMethod和方法的参数构造retrofit2.OkHttpCall对象，第三行是通过serviceMethod.callAdapter.adapt()方法，将OkHttpCall进行代理包装；
下面一个一个介绍：

ServiceMethod应该是最复杂的一个类了，包含了将一个method转化为Call的所有的信息。

ServiceMethod loadServiceMethod(Method method) {
    ServiceMethod result;
    synchronized (serviceMethodCache) {
      result = serviceMethodCache.get(method);
      if (result == null) {
        result = new ServiceMethod.Builder(this, method).build();
        serviceMethodCache.put(method, result);
      }
    }
    return result;
  }

#ServiceMethod
public ServiceMethod build() {
      callAdapter = createCallAdapter();
      responseType = callAdapter.responseType();
      if (responseType == Response.class || responseType == okhttp3.Response.class) {
        throw methodError("'"
            + Utils.getRawType(responseType).getName()
            + "' is not a valid response body type. Did you mean ResponseBody?");
      }
      responseConverter = createResponseConverter();

      for (Annotation annotation : methodAnnotations) {
        parseMethodAnnotation(annotation);
      }

      int parameterCount = parameterAnnotationsArray.length;
      parameterHandlers = new ParameterHandler[parameterCount];
      for (int p = 0; p < parameterCount; p++) {
        Type parameterType = parameterTypes[p];
        if (Utils.hasUnresolvableType(parameterType)) {
          throw parameterError(p, "Parameter type must not include a type variable or wildcard: %s",
              parameterType);
        }

        Annotation[] parameterAnnotations = parameterAnnotationsArray[p];
        if (parameterAnnotations == null) {
          throw parameterError(p, "No Retrofit annotation found.");
        }

        parameterHandlers[p] = parseParameter(p, parameterType, parameterAnnotations);
      }

      return new ServiceMethod<>(this);
    }

直接看build方法，首先拿到这个callAdapter最终拿到的是我们在构建retrofit里面时adapterFactories时添加的，即为：new ExecutorCallbackCall<>(callbackExecutor, call)，该ExecutorCallbackCall唯一做的事情就是将原本call的回调转发至UI线程。
接下来通过callAdapter.responseType()返回的是我们方法的实际类型，例如:Call<\User>,则返回User类型，然后对该类型进行判断。
接下来是createResponseConverter拿到responseConverter对象，其当然也是根据我们构建retrofit时,addConverterFactory添加的ConverterFactory对象来寻找一个合适的返回，寻找的依据主要看该converter能否处理你编写方法的返回值类型，默认实现为BuiltInConverters，仅仅支持返回值的实际类型为ResponseBody和Void，也就说明了默认情况下，是不支持Call<\User>这类类型的。
接下来就是对注解进行解析了，主要是对方法上的注解进行解析，那么可以拿到httpMethod以及初步的url（包含占位符）。
后面是对方法中参数中的注解进行解析，这一步会拿到很多的ParameterHandler对象，该对象在toRequest()构造Request的时候调用其apply方法。
这里我们并没有去一行一行查看代码，其实意义也不太大，只要知道ServiceMethod主要用于将我们接口中的方法转化为一个Request对象，于是根据我们的接口返回值确定了responseConverter,解析我们方法上的注解拿到初步的url,解析我们参数上的注解拿到构建RequestBody所需的各种信息，最终调用toRequest的方法完成Request的构建。

接下来看OkHttpCall的构建，构造函数仅仅是简单的赋值

OkHttpCall(ServiceMethod serviceMethod, Object[] args) {
    this.serviceMethod = serviceMethod;
    this.args = args;
  }

最后一步是serviceMethod.callAdapter.adapt(okHttpCall)，我们已经确定这个callAdapter是ExecutorCallAdapterFactory.get()对应代码为：

final class ExecutorCallAdapterFactory extends CallAdapter.Factory {
  final Executor callbackExecutor;

  ExecutorCallAdapterFactory(Executor callbackExecutor) {
    this.callbackExecutor = callbackExecutor;
  }

  @Override
  public CallAdapter>> get(Type returnType, Annotation[] annotations, Retrofit retrofit) {
    if (getRawType(returnType) != Call.class) {
      return null;
    }
    final Type responseType = Utils.getCallResponseType(returnType);
    return new CallAdapter>>() {
      @Override public Type responseType() {
        return responseType;
      }

      @Override public  Call adapt(Call call) {
        return new ExecutorCallbackCall<>(callbackExecutor, call);
      }
    };
  }

可以看到adapt返回的是ExecutorCallbackCall对象，继续往下看：

static final class ExecutorCallbackCall implements Call {
    final Executor callbackExecutor;
    final Call delegate;

    ExecutorCallbackCall(Executor callbackExecutor, Call delegate) {
      this.callbackExecutor = callbackExecutor;
      this.delegate = delegate;
    }

    @Override public void enqueue(final Callback callback) {
      if (callback == null) throw new NullPointerException("callback == null");

      delegate.enqueue(new Callback() {
        @Override public void onResponse(Call call, final Response response) {
          callbackExecutor.execute(new Runnable() {
            @Override public void run() {
              if (delegate.isCanceled()) {
                // Emulate OkHttp's behavior of throwing/delivering an IOException on cancellation.
                callback.onFailure(ExecutorCallbackCall.this, new IOException("Canceled"));
              } else {
                callback.onResponse(ExecutorCallbackCall.this, response);
              }
            }
          });
        }

        @Override public void onFailure(Call call, final Throwable t) {
          callbackExecutor.execute(new Runnable() {
            @Override public void run() {
              callback.onFailure(ExecutorCallbackCall.this, t);
            }
          });
        }
      });
    }
    @Override public Response execute() throws IOException {
      return delegate.execute();
    }
  }

可以看出ExecutorCallbackCall仅仅是对Call对象进行封装，类似装饰者模式，只不过将其执行时的回调通过callbackExecutor进行回调到UI线程中去了。

执行Call：我们已经拿到了经过封装的ExecutorCallbackCall类型的call对象，实际上就是我们实际在写代码时拿到的call对象，那么我们一般会执行enqueue方法，看看源码是怎么做的，首先是ExecutorCallbackCall.enqueue方法，代码见上面，可以看到除了将onResponse和onFailure回调到UI线程，主要的操作还是delegate完成的，这个delegate实际上就是OkHttpCall对象，我们看它的enqueue方法

public void enqueue(final Callback callback)
{
    okhttp3.Call call;
    Throwable failure;

    synchronized (this)
    {
        if (executed) throw new IllegalStateException("Already executed.");
        executed = true;

        try
        {
            call = rawCall = createRawCall();
        } catch (Throwable t)
        {
            failure = creationFailure = t;
        }
    }

    if (failure != null)
    {
        callback.onFailure(this, failure);
        return;
    }

    if (canceled)
    {
        call.cancel();
    }

    call.enqueue(new okhttp3.Callback()
    {
        @Override
        public void onResponse(okhttp3.Call call, okhttp3.Response rawResponse)
                throws IOException
        {
            Response response;
            try
            {
                response = parseResponse(rawResponse);
            } catch (Throwable e)
            {
                callFailure(e);
                return;
            }
            callSuccess(response);
        }

        @Override
        public void onFailure(okhttp3.Call call, IOException e)
        {
            try
            {
                callback.onFailure(OkHttpCall.this, e);
            } catch (Throwable t)
            {
                t.printStackTrace();
            }
        }

        private void callFailure(Throwable e)
        {
            try
            {
                callback.onFailure(OkHttpCall.this, e);
            } catch (Throwable t)
            {
                t.printStackTrace();
            }
        }

        private void callSuccess(Response response)
        {
            try
            {
                callback.onResponse(OkHttpCall.this, response);
            } catch (Throwable t)
            {
                t.printStackTrace();
            }
        }
    });
}

内部实际上就是okhttp的Call对象，也是调用okhttp3.Call.enqueue方法。中间对于okhttp3.Call的创建代码为：

private okhttp3.Call createRawCall() throws IOException
{
    Request request = serviceMethod.toRequest(args);
    okhttp3.Call call = serviceMethod.callFactory.newCall(request);
    if (call == null)
    {
        throw new NullPointerException("Call.Factory returned null.");
    }
    return call;
}

可以看到，通过serviceMethod.toRequest完成对request的构建，通过request去构造call对象，然后返回.
中间还涉及一个parseResponse方法，如果顺利的话，执行的代码如下：

Response parseResponse(okhttp3.Response rawResponse) throws IOException
{
    ResponseBody rawBody = rawResponse.body();
    ExceptionCatchingRequestBody catchingBody = new ExceptionCatchingRequestBody(rawBody);

    T body = serviceMethod.toResponse(catchingBody);
    return Response.success(body, rawResponse);
}

通过serviceMethod对ResponseBody进行转化，然后返回，转化实际上就是通过responseConverter的convert方法。

T toResponse(ResponseBody body) throws IOException {
    return responseConverter.convert(body);
  }

到这里，我们整个源码的流程分析就差不多了，目的就掌握一个大体的原理和执行流程，了解下几个核心的类。

总结一下：

• 首先构造retrofit，几个核心的参数呢，主要就是baseurl,callFactory(默认okhttpclient),converterFactories,adapterFactories,excallbackExecutor。
• 然后通过create方法拿到接口的实现类，这里利用Java的Proxy类完成动态代理的相关代理
• 在invoke方法内部，拿到我们所声明的注解以及实参等，构造ServiceMethod，ServiceMethod中解析了大量的信息，最终可以通过toRequest构造出okhttp3.Request对象。有了okhttp3.Request对象就可以很自然的构建出okhttp3.call，最后calladapter对Call进行装饰返回。
• 拿到Call就可以执行enqueue或者execute方法了

Demo下载地址