Retrofit 是 square 公司出品的开源的 http 请求框架。
其面向接口和注解的编程方式，使我们的http请求变的更加简单，我们只需要创建一个Api接口类，写上服务器的接口方法即可，而无需关心其实现方式，例如：
public interface ApiService {
@POST("login")
@FormUrlEncoded
Call<BaseResponseResult<User>> login(@Field("Phone") String phone, @Field("Password") String password);
}
然后直接在业务类中调用：
@Test
public void testRetrofit() {
Retrofit retrofit = new Retrofit.Builder()
.addConverterFactory(GsonConverterFactory.create())
.baseUrl("http://api.xxx.com/api/") // api 的域名前缀
.build();
ApiService apiService = retrofit.create(ApiService.class);
try {
String result = apiService.login("13000000000", "123456").execute().body().toString();
System.out.println(result);
} catch (IOException pE) {
pE.printStackTrace();
}
}
Note：为了避免项目中的多次创建Retrofit，可以配合dagger2实现单例注入。
其虽然提供了简便的编程方式，但接口的标准比较固定：
baseUrl + apiUrl 的方式
而我们服务器端提供的接口可能并不一定按照这种方式定义，比如：
需求1：服务器端要配合app的需求调整其返回的数据的格式及业务逻辑，为保证兼容以前的 app 的业务需要，我们可能要告诉服务器某个接口的版本，所以我们可能需要传入接口的版本信息。
方案1：最简单实现是直接在接口上加上版本信息：
@POST("200800\login")
@FormUrlEncoded
Call<BaseResponseResult<User>> login(@Field("Phone") String phone, @Field("Password") String password);
但这样的话，如果要更改好多接口的版本可能要改的信息比较多，也不符合设计的原则。
由于Retrofit本身的实现基于注解，所以我们可以扩展注解的方式实现，也符合其设计标准。
方案2：
// kotlin 代码
// 可以注解接口类，修改所有的接口的版本；亦可以修改接口的方法修改某个接口的版本。
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class ApiVersion(val value: Int = 0 /* 0-Ignore */)
// 注解到接口方法
@ApiVersion(2008000)
@POST("login")
@FormUrlEncoded
Call<BaseResponseResult<User>> login(@Field("Phone") String phone, @Field("Password") String password);
需求2：
服务器提供的接口都使用了几个共同的参数，可能每个接口可能都需要传接口的 SC/SV 等参数做接口验证，或者传入手机系统的信息、硬件信息、app的Flavor信息。
给每个接口注解几个固定的参数，基于注解的实现：
// form 表单的 POST 方式
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class FixedField(val keys: Array<String>, val values: Array<String>)
// get 方式
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class FixedQuery(val keys: Array<String>, val values: Array<String>)
// 注解到接口方法
@POST("phone_login")
@FixedField(keys = {"SC", "SV"}, values = {"xxx", "yyy"})
@FormUrlEncoded
Call<BaseResponseResult<User>> login(@Field("Phone") String phone, @Field("Password") String password);
有时我们可能希望把一个类转换到成 FieldMap 或者 QueryMap 的键值对的方式提交到服务器，可以使用：
@Target(AnnotationTarget.CLASS, AnnotationTarget.FUNCTION)
@Retention(AnnotationRetention.RUNTIME)
annotation class DynamicClassQuery(val value: Array<KClass<out IDynamicQueryClass>>)
// 比如要所有接口上都注入手机的版本，系统信息，由于参数太多，我就准备了一个类，实现自动转换。
@DynamicClassQuery(Header.class)
public interface ApiService {
...
}
// 创建一个统一的接口
interface IDynamicQueryClass {
fun toQuery(): Map<String, String?>
}
// 实现类，用于存放手机的版本，系统信息
class Header : IDynamicQueryClass {
...
override fun toQuery(): Map<String, String?> {
val map: HashMap<String, String?> = HashMap()
val fields = Header::class.java.declaredFields;
fields.map {
map.put(it.name, it.get(this)?.toString());
}
return map;
}
}
加了这么多自定义注解，需要修改 Retrofit 的注解处理代码，已处理我们的自定义注解。 现附上扩展 Retrofit 的代码：
// Retrofit
ServiceMethod<Object, Object> serviceMethod = (ServiceMethod<Object, Object>) loadServiceMethod(method);
// 加入扩展的参数
args = serviceMethod.rebuildArgs(args);
// ServiceMethod
final class ServiceMethod<R, T> {
// 扩展的注解
Map<String, String> fixedFields;
Map<String, String> fixedQueries;
...
ServiceMethod(Builder<R, T> builder) {
...
// 扩展的注解
this.fixedFields = builder.fixedFields;
this.fixedQueries = builder.fixedQueries;
}
...
// 扩展我们需要的参数
public Object[] rebuildArgs(Object[] args) {
List<Object> argList = new ArrayList<>(Arrays.asList(args));
if (!this.fixedFields.isEmpty()) {
for (Map.Entry<String, String> entry : fixedFields.entrySet()) {
argList.add(entry.getValue());
}
}
if (!this.fixedQueries.isEmpty()) {
for (Map.Entry<String, String> entry : fixedQueries.entrySet()) {
argList.add(entry.getValue());
}
}
return argList.toArray();
}
...
static final class Builder<T, R> {
...
// 扩展的注解
Map<String, String> fixedFields;
Map<String, String> fixedQueries;
...
Builder(Retrofit retrofit, Method method) {
...
// 初始化扩展的注解
this.fixedFields = new HashMap<>();
this.fixedQueries = new HashMap<>();
}
...
// 解析接口的注解，这里包含父类的注解，使用时请注意
Annotation[] classAnnotations = method.getDeclaringClass().getAnnotations();
for (Annotation annotation : classAnnotations) {
// 这个是解析我们扩展的注解的方法
parseExtendAnnotation(annotation);
}
for (Annotation annotation : methodAnnotations) {
parseMethodAnnotation(annotation);
}
...
// 加上自定义扩展注解的数量
parameterHandlers = new ParameterHandler<?>[parameterCount + fixedFields.size() + fixedQueries.size()];
...
// 处理自定义注解参数
int p = parameterCount;
Converter<?, String> converter = BuiltInConverters.ToStringConverter.INSTANCE;
for (Map.Entry<String, String> entry : fixedFields.entrySet()) {
parameterHandlers[p++] = new ParameterHandler.Field(entry.getKey(), converter, false);
}
for (Map.Entry<String, String> entry : fixedQueries.entrySet()) {
parameterHandlers[p++] = new ParameterHandler.Query<>(entry.getKey(), converter, false);
}
}
// 转换自定义的注解
private void parseExtendAnnotation(Annotation annotation) {
if (annotation instanceof FixedField) {
FixedField fixedField = (FixedField) annotation;
String[] keys = fixedField.keys();
String[] values = fixedField.values();
if (keys.length != values.length) {
throw methodError("FixedField keys count (" + keys.length + ") doesn't match values count (" + values.length + ")");
}
for (int i = 0; i < keys.length; i++) {
if (keys[i] == null || keys[i].length() == 0) continue;
fixedFields.put(keys[i], values[i]);
}
isFormEncoded = true;
} else if (annotation instanceof FixedQuery) {
FixedQuery fixedQuery = (FixedQuery) annotation;
String[] keys = fixedQuery.keys();
String[] values = fixedQuery.values();
if (keys.length != values.length) {
throw methodError("FixedQuery keys count (" + keys.length + ") doesn't match values count (" + values.length + ")");
}
for (int i = 0; i < keys.length; i++) {
if (keys[i] == null || keys[i].length() == 0) continue;
fixedQueries.put(keys[i], values[i]);
}
gotQuery = true;
} else if (annotation instanceof ApiVersion) {
ApiVersion version = (ApiVersion) annotation;
this.apiVersion = version.value();
if (relativeUrl != null) {
relativeUrl = apiVersion + "/" + relativeUrl;
}
} else if (annotation instanceof SC) {
fixedFields.put("SC", ((SC) annotation).value());
} else if (annotation instanceof SV) {
fixedFields.put("SV", ((SV) annotation).value());
} else if (annotation instanceof DynamicClassQuery) {
Class<? extends IDynamicQueryClass>[] clsArray = ((DynamicClassQuery) annotation).value();
for (Class<? extends IDynamicQueryClass> cls : clsArray) {
try {
fixedQueries.putAll(cls.newInstance().toQuery());
} catch (Exception e) {
e.printStackTrace();
}
}
}
}
}
