retrofit介绍
retrofit是一个http访问客户端,类似okhttp、apache httpclient,不过retrofit是类型安全的,也就是定义一个强类型的http客户端接口使用,而不是 请求url返回一个string的结果,再拿string去解析字段,这样开发时更加安全,能帮助开发者省去请求参数结果转换的繁琐重复工作,它的思想类似Mybatis、spring data等。
使用
添加maven依赖
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>retrofit</artifactId>
<version>2.9.0</version>
</dependency>
<dependency>
<groupId>com.squareup.retrofit2</groupId>
<artifactId>converter-jackson</artifactId>
<version>2.9.0</version>
</dependency>
定义http接口
Repo是这个接口的返回结果字段对应的model类。
接口方法中的@Get注解表示当前使用Get请求,注解中的参数是请求的uri,支持使用 {user}
这样的占位符,接口方法中提供 @Path("user")
注解可以占位符的参数。
public interface GitHubService {
@GET("users/{user}/repos")
Call<List<Repo>> listRepos(@Path("user") String user);
}
通过@Query或@QueryMap定义url参数
@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);
如果想使用Post方法可以使用@Post注解
@FormUrlEncoded
@POST("user/edit")
Call<User> updateUser(@Field("first_name") String first, @Field("last_name") String last);
通过FieldMap传递Map参数
@FormUrlEncoded
@POST("/things")
Call<ResponseBody> things(@FieldMap Map<String, String> fields);
通过@Body传入对象参数,如果我们使用jackson converter 会转成请求中的json request body
@POST("users/new")
Call<User> createUser(@Body User user);
可以通过@Header注解控制request header
@Headers("Cache-Control: max-age=640000")
@GET("widget/list")
Call<List<Widget>> widgetList();
可以通过@Multipart和@Part进行文件上传
@Multipart
@PUT("user/photo")
Call<User> updateUser(@Part("photo") RequestBody photo, @Part("description") RequestBody description);
使用定义好的http接口
我们的请求返回要支持json编解码,需要传入一个converterFactory,这里选择 JacksonConverterFactory
,并且提供一个定制参数的jackson的 ObjectMapper
baseUrl定义接口的url前缀,和http接口中的@Get@Post注解中的uri联合起来就是请求的完整url。
base
ObjectMapper objectMapper = new ObjectMapper()
.disable(DeserializationFeature.FAIL_ON_UNKNOWN_PROPERTIES);
Retrofit retrofit = new Retrofit.Builder()
.baseUrl("https://api.github.com/")
.addConverterFactory(JacksonConverterFactory.create(objectMapper))
.build();
GitHubService service = retrofit.create(GitHubService.class);
try {
Call<List<Repo>> test = GitHubService.getInstance().listRepos("test");
Response<List<Repo>> execute = test.execute();
List<Repo> githubRepos = execute.body();
/// 使用返回的结果...
} catch (IOException e) {
e.printStackTrace();
}
实现原理
看到接口,我们可以联想到jdk里的Proxy代理技术,我们之前的一篇设计和分析Java动态代理的技术实现文章中就降到了Java动态代理的设计思路和具体的实现,感兴趣的朋友可以查看这篇文章。
我们创建http接口时使用的 Retrofit.create(final Class<T> service)
方法,是通过Jdk的Proxy获取Http接口的运行时代理实现,这个实现的方法会调用代理创建时传入的InvocationHandler。InvocationHandler中对Object里方法、default方法做了特殊处理,详细可以查看注释备注。
public <T> T create(final Class<T> service) {
Utils.validateServiceInterface(service);
if (validateEagerly) {
eagerlyValidateMethods(service);
}
return (T) Proxy.newProxyInstance(service.getClassLoader(), new Class<?>[] { service },
new InvocationHandler() {
private final Platform platform = Platform.get();
private final Object[] emptyArgs = new Object[0];
@Override public @Nullable Object invoke(Object proxy, Method method,
@Nullable Object[] args) throws Throwable {
// 如果是调用Object类里的方法,比如toString、equals、hashCode这些,直接使用生成的代理对象里的默认实现,也就是Object.class里的实现。
// If the method is a method from Object then defer to normal invocation.
if (method.getDeclaringClass() == Object.class) {
return method.invoke(this, args);
}
if (platform.isDefaultMethod(method)) {
return platform.invokeDefaultMethod(method, service, proxy, args);
}
return loadServiceMethod(method).invoke(args != null ? args : emptyArgs);
}
});
}
我们在接口中定义的抽象接口方法,会通过 loadServiceMethod(method).invoke
实现,返回ServiceMethod,也就是注解接口对应的方法信息。 ServiceMethod类的核心方法是 abstract @Nullable T invoke(Object[] args);
,也就是运行时http接口类被调用时调用到InvocationHandler中委托的调用。 loadServerMethod方法负责解析接口方法生成一个ServiceMethod,并且为了避免重复不必要的解析(重复执行、反射、内存等成本)加了一个 serviceMethodCache。
ServiceMethod<?> loadServiceMethod(Method method) {
ServiceMethod<?> result = serviceMethodCache.get(method);
if (result != null) return result;
synchronized (serviceMethodCache) {
result = serviceMethodCache.get(method);
if (result == null) {
result = ServiceMethod.parseAnnotations(this, method);
serviceMethodCache.put(method, result);
}
}
return result;
}
parseAnnotations创建了一个RequestFactory对象,做了一些接口返回类型的校验(返回值必须要包含泛型、不能返回void),然后交给 HttpServiceMethod.parseAnnotations
。 RequestFactory对象负责具体的发送请求,其中封装了对底层的http客户端okhttp的调用。
static <T> ServiceMethod<T> parseAnnotations(Retrofit retrofit, Method method) {
RequestFactory requestFactory = RequestFactory.parseAnnotations(retrofit, method);
Type returnType = method.getGenericReturnType();
if (Utils.hasUnresolvableType(returnType)) {
throw methodError(method,
"Method return type must not include a type variable or wildcard: %s", returnType);
}
if (returnType == void.class) {
throw methodError(method, "Service methods cannot return void.");
}
return HttpServiceMethod.parseAnnotations(retrofit, method, requestFactory);
}
HttpServiceMethod.parseAnnotations
的代码比较多,我们可以整理一下其中要做的事情。
当我们调用retrofit的http接口类时,内部要执行的事情是,准备好相关的请求参数,构建好请求的url,发送http请求,等待http结果, 然后把http返回的结果数据,转换成接口的返回类型。
为代码看起来更清晰,我删除了一些kotlin suspend功能、异常检查等代码。
static <ResponseT, ReturnT> HttpServiceMethod<ResponseT, ReturnT> parseAnnotations(
Retrofit retrofit, Method method, RequestFactory requestFactory) {
// 获取方法上的注解
Annotation[] annotations = method.getAnnotations();
Type adapterType = method.getGenericReturnType();
//创建CallAdapter
CallAdapter<ResponseT, ReturnT> callAdapter =
createCallAdapter(retrofit, method, adapterType, annotations);
Type responseType = callAdapter.responseType();
// 创建repsonse对应的converter,Converter能把okhttp的ResponseBody转换成方法返回类型的对象,我们这里使用的是
Converter<ResponseBody, ResponseT> responseConverter =
createResponseConverter(retrofit, method, responseType);
okhttp3.Call.Factory callFactory = retrofit.callFactory;
return new CallAdapted<>(requestFactory, callFactory, responseConverter, callAdapter);
}
- createCallAdapter
createCallAdapter创建一个CallAdapter对象,Call是Retrofit对于http底层访问的抽象,目前默认的实现是OkHttpCall和异步版本的ExecutorCallbackCall。 创建Call对象的类有DefaultCallAdapterFactory,CompletableFutureCallAdapterFactory(针对返回CompletableFuture的接口方法),GuavaCallAdapterFactory(针对返回guava里的ListenableFuture的接口方法)
- createResponseConverter
createResponseConverter会在所有的ConverterFactory中去找哪个ConverterFactory支持convert当前的类型,找到返回使用。
- new CallAdapted<>(requestFactory, callFactory, responseConverter, callAdapter);
CallAdapted是对上述数据的封装,最终HttpServiceMethod.invoke调用的时候,会通过创建好一个OkHttpCall,然后传给CallAdapted.adapt方法调用, 编码参数,调用拿到http结果,转换参数返回。
@Override final @Nullable ReturnT invoke(Object[] args) {
Call<ResponseT> call = new OkHttpCall<>(requestFactory, args, callFactory, responseConverter);
return adapt(call, args);
}
更多资料
作者:bytejava
链接:类型安全的http客户端retrofit介绍、使用、实现原理分析 - 掘金