Android Retrofit 框架注解定义与解析模块深度剖析(一)

一、引言

在现代 Android 和 Java 开发中，网络请求是不可或缺的一部分。Retrofit 作为 Square 公司开源的一款强大的类型安全的 HTTP 客户端，凭借其简洁易用的 API 和高效的性能，在开发者社区中广受欢迎。Retrofit 的核心特性之一便是通过注解来定义 HTTP 请求，这种方式使得代码更加清晰、易读且易于维护。本文将深入 Retrofit 框架的源码，对其注解定义与解析模块进行全面且细致的分析，揭示其背后的实现原理。

二、Retrofit 框架概述

2.1 Retrofit 的基本工作流程

Retrofit 的主要工作流程可以概括为以下几个步骤：

  1. 定义服务接口：开发者使用注解定义一个接口，该接口包含了各种 HTTP 请求方法。
  2. 创建 Retrofit 实例：通过 Retrofit.Builder 构建 Retrofit 实例，配置请求的基础 URL、转换器工厂、调用适配器工厂等。
  3. 创建服务代理对象：使用 Retrofit 实例创建服务接口的代理对象。
  4. 发起请求：调用服务代理对象的方法发起 HTTP 请求，并处理响应结果。

2.2 注解在 Retrofit 中的作用

注解在 Retrofit 中扮演着至关重要的角色，它们用于描述 HTTP 请求的各个方面，包括请求方法（如 GET、POST 等）、请求路径、请求参数、请求头、请求体等。通过注解，开发者可以以一种声明式的方式定义请求，而无需编写繁琐的网络请求代码。

三、Retrofit 注解的定义

3.1 HTTP 请求方法注解

3.1.1 @GET 注解

java

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 表示 HTTP GET 请求的注解*/
@Documented
// 该注解只能应用于方法上
@Target(ElementType.METHOD)
// 该注解在运行时保留，以便通过反射获取
@Retention(RetentionPolicy.RUNTIME)
public @interface GET {/*** 指定请求的相对路径* @return 请求的相对路径，默认为空字符串*/String value() default "";
}

@GET 注解用于标记一个方法为 HTTP GET 请求，value 属性用于指定请求的相对路径。例如：

java

public interface ApiService {@GET("users/{id}")Call<User> getUser(@Path("id") int userId);
}
3.1.2 其他 HTTP 请求方法注解

除了 @GET 注解，Retrofit 还提供了 @POST、@PUT、@DELETE、@HEAD、@OPTIONS 和 @PATCH 等注解，它们的定义方式与 @GET 注解类似，只是用于不同的 HTTP 请求方法。

3.2 请求路径与参数注解

3.2.1 @Path 注解

java

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于替换 URL 中占位符的注解*/
@Documented
// 该注解只能应用于方法的参数上
@Target(ElementType.PARAMETER)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface Path {/*** 指定 URL 中的占位符名称* @return 占位符名称*/String value();/*** 指定是否对参数进行 URL 编码，默认为 false* @return 是否进行 URL 编码*/boolean encoded() default false;
}

@Path 注解用于替换 URL 中的占位符，例如在上面的 getUser 方法中，@Path("id") 表示将 userId 参数的值替换到 URL 中的 {id} 占位符处。

3.2.2 @Query 和 @QueryMap 注解

java

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于添加查询参数到 URL 中的注解*/
@Documented
// 该注解只能应用于方法的参数上
@Target(ElementType.PARAMETER)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface Query {/*** 指定查询参数的名称* @return 查询参数的名称*/String value();/*** 指定是否对参数进行 URL 编码，默认为 false* @return 是否进行 URL 编码*/boolean encoded() default false;
}import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于添加多个查询参数到 URL 中的注解*/
@Documented
// 该注解只能应用于方法的参数上
@Target(ElementType.PARAMETER)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface QueryMap {/*** 指定是否对参数进行 URL 编码，默认为 false* @return 是否进行 URL 编码*/boolean encoded() default false;
}

@Query 注解用于添加单个查询参数到 URL 中，@QueryMap 注解用于添加多个查询参数。例如：

java

public interface ApiService {@GET("search")Call<List<Item>> search(@Query("keyword") String keyword, @Query("page") int page);@GET("search")Call<List<Item>> searchWithMap(@QueryMap Map<String, String> queryParams);
}
3.2.3 @Header 和 @HeaderMap 注解

java

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于添加请求头的注解*/
@Documented
// 该注解只能应用于方法的参数上
@Target(ElementType.PARAMETER)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface Header {/*** 指定请求头的名称* @return 请求头的名称*/String value();
}import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于添加多个请求头的注解*/
@Documented
// 该注解只能应用于方法的参数上
@Target(ElementType.PARAMETER)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface HeaderMap {
}

@Header 注解用于添加单个请求头，@HeaderMap 注解用于添加多个请求头。例如：

java

public interface ApiService {@GET("data")Call<Data> getData(@Header("Authorization") String token);@GET("data")Call<Data> getDataWithMap(@HeaderMap Map<String, String> headers);
}
3.2.4 @Body 注解

java

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于指定请求体的注解*/
@Documented
// 该注解只能应用于方法的参数上
@Target(ElementType.PARAMETER)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface Body {
}

@Body 注解用于指定请求体，通常用于 POST、PUT 等请求。例如：

java

public interface ApiService {@POST("users")Call<User> createUser(@Body User user);
}
3.2.5 @FormUrlEncoded、@Field 和 @FieldMap 注解

java

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于标记表单编码请求的注解*/
@Documented
// 该注解只能应用于方法上
@Target(ElementType.METHOD)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface FormUrlEncoded {
}import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于添加表单字段的注解*/
@Documented
// 该注解只能应用于方法的参数上
@Target(ElementType.PARAMETER)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface Field {/*** 指定表单字段的名称* @return 表单字段的名称*/String value();/*** 指定是否对参数进行 URL 编码，默认为 false* @return 是否进行 URL 编码*/boolean encoded() default false;
}import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于添加多个表单字段的注解*/
@Documented
// 该注解只能应用于方法的参数上
@Target(ElementType.PARAMETER)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface FieldMap {/*** 指定是否对参数进行 URL 编码，默认为 false* @return 是否进行 URL 编码*/boolean encoded() default false;
}

@FormUrlEncoded 注解用于标记一个方法为表单编码请求，@Field 注解用于添加单个表单字段，@FieldMap 注解用于添加多个表单字段。例如：

java

public interface ApiService {@FormUrlEncoded@POST("login")Call<LoginResponse> login(@Field("username") String username, @Field("password") String password);@FormUrlEncoded@POST("login")Call<LoginResponse> loginWithMap(@FieldMap Map<String, String> fields);
}
3.2.6 @Multipart、@Part 和 @PartMap 注解

java

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于标记多部分请求的注解*/
@Documented
// 该注解只能应用于方法上
@Target(ElementType.METHOD)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface Multipart {
}import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于添加多部分请求中的一个部分的注解*/
@Documented
// 该注解只能应用于方法的参数上
@Target(ElementType.PARAMETER)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface Part {/*** 指定部分的名称* @return 部分的名称*/String value() default "";
}import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于添加多部分请求中的多个部分的注解*/
@Documented
// 该注解只能应用于方法的参数上
@Target(ElementType.PARAMETER)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface PartMap {
}

@Multipart 注解用于标记一个方法为多部分请求，@Part 注解用于添加多部分请求中的一个部分，@PartMap 注解用于添加多部分请求中的多个部分。多部分请求常用于文件上传等场景。例如：

java

public interface ApiService {@Multipart@POST("upload")Call<UploadResponse> uploadFile(@Part("file"; filename="image.jpg"") RequestBody file);@Multipart@POST("upload")Call<UploadResponse> uploadFiles(@PartMap Map<String, RequestBody> files);
}

3.3 其他注解

3.3.1 @Headers 注解

java

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;/*** 用于添加多个请求头的注解*/
@Documented
// 该注解只能应用于方法上
@Target(ElementType.METHOD)
// 该注解在运行时保留
@Retention(RetentionPolicy.RUNTIME)
public @interface Headers {/*** 指定请求头的数组* @return 请求头的数组*/String[] value();
}

@Headers 注解用于在方法上添加多个请求头。例如：

java

public interface ApiService {@Headers({"Content-Type: application/json","Authorization: Bearer token123"})@GET("data")Call<Data> getData();
}

四、Retrofit 注解的解析

4.1 解析入口：ServiceMethod 类

ServiceMethod 是 Retrofit 中解析注解的核心类，它负责将接口方法上的注解信息解析为实际的 HTTP 请求信息。以下是 ServiceMethod 类的部分源码：

java

abstract class ServiceMethod<T> {/*** 解析接口方法上的注解，创建 ServiceMethod 实例* @param retrofit Retrofit 实例* @param method 接口方法* @param <T> 响应类型* @return ServiceMethod 实例*/static <T> ServiceMethod<T> parseAnnotations(Retrofit retrofit, Method method) {// 创建 RequestFactory.Builder 实例，用于构建 RequestFactoryRequestFactory.Builder requestFactoryBuilder = new RequestFactory.Builder(retrofit, method);// 解析请求方法和路径相关的注解requestFactoryBuilder.parseMethodAnnotation(method.getAnnotations());// 获取方法的参数类型Type[] parameterTypes = method.getGenericParameterTypes();// 获取方法的参数注解Annotation[][] parameterAnnotationsArray = method.getParameterAnnotations();// 遍历方法的每个参数for (int p = 0; p < parameterTypes.length; p++) {// 解析参数的注解requestFactoryBuilder.parseParameter(p, parameterTypes[p], parameterAnnotationsArray[p]);}// 构建 RequestFactory 实例RequestFactory requestFactory = requestFactoryBuilder.build();// 获取方法的返回类型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.");}// 创建 CallAdapter 实例，用于将 Call 对象转换为其他类型CallAdapter<T, ?> callAdapter = createCallAdapter(retrofit, method, returnType, requestFactory);// 获取响应类型Type responseType = callAdapter.responseType();if (Utils.hasUnresolvableType(responseType)) {throw methodError(method, "Call return type must not include a type variable or wildcard: %s", returnType);}// 创建 Converter 实例，用于将响应数据转换为指定类型Converter<ResponseBody, T> responseConverter =createResponseConverter(retrofit, method, responseType);// 获取 OkHttpClient 实例okhttp3.Call.Factory callFactory = retrofit.callFactory();// 创建 ServiceMethod 实例return new HttpServiceMethod<>(callFactory, requestFactory, callAdapter, responseConverter);}/*** 创建 CallAdapter 实例* @param retrofit Retrofit 实例* @param method 接口方法* @param returnType 方法的返回类型* @param requestFactory 请求工厂* @param <T> 响应类型* @return CallAdapter 实例*/private static <T> CallAdapter<T, ?> createCallAdapter(Retrofit retrofit, Method method, Type returnType, RequestFactory requestFactory) {try {// 通过 Retrofit 实例获取 CallAdapter.Factory 列表，并调用其 get 方法创建 CallAdapter 实例return (CallAdapter<T, ?>) retrofit.callAdapter(returnType, method.getAnnotations());} catch (RuntimeException e) {throw methodError(method, e, "Unable to create call adapter for %s", returnType);}}/*** 创建响应转换器实例* @param retrofit Retrofit 实例* @param method 接口方法* @param responseType 响应类型* @param <T> 响应类型* @return 响应转换器实例*/private static <T> Converter<ResponseBody, T> createResponseConverter(Retrofit retrofit, Method method, Type responseType) {try {// 通过 Retrofit 实例获取 Converter.Factory 列表，并调用其 responseBodyConverter 方法创建响应转换器实例return retrofit.responseBodyConverter(responseType, method.getAnnotations());} catch (RuntimeException e) {throw methodError(method, e, "Unable to create converter for %s", responseType);}}/*** 抽象方法，用于执行请求* @param args 方法参数* @return 响应结果*/abstract @Nullable T invoke(Object[] args);
}

parseAnnotations 方法是解析的入口，它接收 Retrofit 实例和 Method 实例作为参数，通过以下步骤完成注解解析：

  1. 创建 RequestFactory.Builder 实例，用于构建 RequestFactory。
  2. 调用 requestFactoryBuilder.parseMethodAnnotation 方法解析请求方法和路径相关的注解。
  3. 遍历方法的每个参数，调用 requestFactoryBuilder.parseParameter 方法解析参数的注解。
  4. 构建 RequestFactory 实例。
  5. 获取方法的返回类型，并创建 CallAdapter 实例，用于将 Call 对象转换为其他类型。
  6. 获取响应类型，并创建 Converter 实例，用于将响应数据转换为指定类型。
  7. 获取 OkHttpClient 实例，并创建 ServiceMethod 实例。

4.2 解析请求方法和路径注解：RequestFactory.Builder.parseMethodAnnotation 方法

java

static final class Builder {// 存储请求方法（如 GET、POST 等）private String httpMethod;// 存储请求是否需要请求体private boolean hasBody;// 存储请求的相对路径private String relativeUrl;// 存储请求的请求头private okhttp3.Headers headers;// 存储路径中的占位符名称private List<String> relativeUrlParamNames;// 标记是否为多部分请求private boolean isMultipart;// 标记是否为表单编码请求private boolean isFormEncoded;/*** 解析请求方法和路径相关的注解* @param annotations 方法上的注解数组*/void parseMethodAnnotation(Annotation[] annotations) {for (Annotation annotation : annotations) {if (annotation instanceof HttpMethod) {// 如果注解是 HttpMethod 类型（如 @GET、@POST 等）HttpMethod httpMethodAnnotation = (HttpMethod) annotation;// 获取请求方法this.httpMethod = httpMethodAnnotation.value();// 判断是否需要请求体this.hasBody = httpMethodAnnotation.hasBody();String path = httpMethodAnnotation.path();if (!path.isEmpty()) {// 检查路径是否以 / 开头if (path.startsWith("/")) {throw methodError(method, "@%s path must not start with /: %s",httpMethodAnnotation.annotationType().getSimpleName(), path);}this.relativeUrl = path;// 解析路径中的占位符this.relativeUrlParamNames = parsePathParameters(path);}} else if (annotation instanceof Headers) {// 如果注解是 Headers 类型String[] headersToParse = ((Headers) annotation).value();if (headersToParse.length == 0) {throw methodError(method, "@Headers annotation is empty.");}// 解析请求头this.headers = parseHeaders(headersToParse);} else if (annotation instanceof Multipart) {// 如果注解是 Multipart 类型if (this.hasBody) {throw methodError(method, "Only one encoding annotation is allowed.");}this.isMultipart = true;this.hasBody = true;} else if (annotation instanceof FormUrlEncoded) {// 如果注解是 FormUrlEncoded 类型if (this.hasBody) {throw methodError(method, "Only one encoding annotation is allowed.");}this.isFormEncoded = true;this.hasBody = true;}}if (httpMethod == null) {throw methodError(method, "HTTP method annotation is required (e.g., @GET, @POST, etc.).");}}/*** 解析路径中的占位符* @param path 请求路径* @return 占位符名称列表*/private static List<String> parsePathParameters(String path) {// 定义正则表达式，用于匹配路径中的占位符Matcher m = PARAM_URL_REGEX.matcher(path);List<String> patterns = new ArrayList<>();while (m.find()) {String name = m.group(1);if (name == null) {continue;}if (patterns.contains(name)) {throw new IllegalArgumentException("URL path "" + path + "" has duplicate param "" + name + "".");}patterns.add(name);}return patterns;}/*** 解析请求头* @param headers 请求头数组* @return OkHttp 的 Headers 实例*/private static okhttp3.Headers parseHeaders(String[] headers) {okhttp3.Headers.Builder builder = new okhttp3.Headers.Builder();for (String header : headers) {int colon = header.indexOf(':');if (colon == -1 || colon == 0 || colon == header.length() - 1) {throw new IllegalArgumentException("Headers value must be in the form "Name: Value". Found: "" + header + """);}String name = header.substring(0, colon).trim();String value = header.substring(colon + 1).trim();builder.add(name, value);}return builder.build();}
}

parseMethodAnnotation 方法遍历方法上的所有注解，根据注解的类型进行不同的处理：

  1. 如果注解是 HttpMethod 类型（如 @GET、@POST 等），获取请求方法、判断是否需要请求体，并解析路径中的占位符。
  2. 如果注解是 Headers 类型，解析请求头。
  3. 如果注解是 Multipart 类型，标记为多部分请求。
  4. 如果注解是 FormUrlEncoded 类型，标记为表单编码请求。

4.3 解析参数注解：RequestFactory.Builder.parseParameter 方法

java

static final class Builder {// 存储参数处理器数组private ParameterHandler<?>[] parameterHandlers;/*** 解析方法参数的注解* @param p 参数索引* @param parameterType 参数类型* @param annotations 参数上的注解数组*/void parseParameter(int p, Type parameterType, @Nullable Annotation[] annotations) {if (annotations == null) {throw parameterError(method, p, "No Retrofit annotation found.");}ParameterHandler<?> result = null;for (Annotation annotation : annotations) {// 创建参数处理器ParameterHandler<?> annotationAction = parseParameterAnnotation(p, parameterType, annotations, annotation);if (annotationAction == null) {continue;}if (result != null) {throw parameterError(method, p, "Multiple Retrofit annotations found, only one allowed.");}result = annotationAction;}if (result == null) {throw parameterError(method, p, "No Retrofit annotation found.");}// 将参数处理器添加到参数处理器数组中parameterHandlers[p] = result;}/*** 解析单个参数注解* @param p 参数索引* @param type 参数类型* @param annotations 参数上的注解数组* @param annotation 当前要解析的注解* @return 参数处理器*/private @Nullable ParameterHandler<?> parseParameterAnnotation(int p, Type type, Annotation[] annotations, Annotation annotation) {if (annotation instanceof Path) {// 如果注解

4.3 解析参数注解：RequestFactory.Builder.parseParameter 方法（续）

java

static final class Builder {// 存储参数处理器数组private ParameterHandler<?>[] parameterHandlers;/*** 解析方法参数的注解* @param p 参数索引* @param parameterType 参数类型* @param annotations 参数上的注解数组*/void parseParameter(int p, Type parameterType, @Nullable Annotation[] annotations) {if (annotations == null) {throw parameterError(method, p, "No Retrofit annotation found.");}ParameterHandler<?> result = null;for (Annotation annotation : annotations) {// 创建参数处理器ParameterHandler<?> annotationAction = parseParameterAnnotation(p, parameterType, annotations, annotation);if (annotationAction == null) {continue;}if (result != null) {throw parameterError(method, p, "Multiple Retrofit annotations found, only one allowed.");}result = annotationAction;}if (result == null) {throw parameterError(method, p, "No Retrofit annotation found.");}// 将参数处理器添加到参数处理器数组中parameterHandlers[p] = result;}/*** 解析单个参数注解* @param p 参数索引* @param type 参数类型* @param annotations 参数上的注解数组* @param annotation 当前要解析的注解* @return 参数处理器*/private @Nullable ParameterHandler<?> parseParameterAnnotation(int p, Type type, Annotation[] annotations, Annotation annotation) {if (annotation instanceof Path) {// 如果注解是 Path 类型Path path = (Path) annotation;// 检查路径中是否包含该占位符if (!relativeUrlParamNames.contains(path.value())) {throw parameterError(method, p, "@Path parameter "" + path.value()+ "" not found in relative URL "" + relativeUrl + """);}// 检查参数类型是否为基本类型或字符串if (Utils.hasUnresolvableType(type)) {throw parameterError(method, p,"@Path parameter type must not include a type variable or wildcard: %s", type);}// 创建 PathParameterHandler 实例return new ParameterHandler.Path<>(path.value(), path.encoded(),converterFactory.stringConverter(type, annotations, retrofit));} else if (annotation instanceof Query) {// 如果注解是 Query 类型Query query = (Query) annotation;// 检查参数类型是否为基本类型或字符串if (Utils.hasUnresolvableType(type)) {throw parameterError(method, p,"@Query parameter type must not include a type variable or wildcard: %s", type);}// 创建 QueryParameterHandler 实例return new ParameterHandler.Query<>(query.value(), query.encoded(),converterFactory.stringConverter(type, annotations, retrofit));} else if (annotation instanceof QueryMap) {// 如果注解是 QueryMap 类型if (!Map.class.isAssignableFrom(Utils.getRawType(type))) {throw parameterError(method, p, "@QueryMap parameter type must be Map.");}Type keyType = Utils.getSupertype(type, Map.class, String.class);if (keyType != String.class) {throw parameterError(method, p, "@QueryMap keys must be of type String: %s", type);}Type valueType = Utils.getSupertype(type, Map.class, Object.class);// 创建 QueryMapParameterHandler 实例return new ParameterHandler.QueryMap<>(converterFactory.stringConverter(valueType, annotations, retrofit));} else if (annotation instanceof Header) {// 如果注解是 Header 类型Header header = (Header) annotation;// 检查参数类型是否为基本类型或字符串if (Utils.hasUnresolvableType(type)) {throw parameterError(method, p,"@Header parameter type must not include a type variable or wildcard: %s", type);}// 创建 HeaderParameterHandler 实例return new ParameterHandler.Header<>(header.value(),converterFactory.stringConverter(type, annotations, retrofit));} else if (annotation instanceof HeaderMap) {// 如果注解是 HeaderMap 类型if (!Map.class.isAssignableFrom(Utils.getRawType(type))) {throw parameterError(method, p, "@HeaderMap parameter type must be Map.");}Type keyType = Utils.getSupertype(type, Map.class, String.class);if (keyType != String.class) {throw parameterError(method, p, "@HeaderMap keys must be of type String: %s", type);}Type valueType = Utils.getSupertype(type, Map.class, Object.class);// 创建 HeaderMapParameterHandler 实例return new ParameterHandler.HeaderMap<>(converterFactory.stringConverter(valueType, annotations, retrofit));} else if (annotation instanceof Body) {// 如果注解是 Body 类型if (isFormEncoded || isMultipart) {throw parameterError(method, p,"@Body parameters cannot be used with form or multi - part encoding.");}// 创建 BodyParameterHandler 实例return new ParameterHandler.Body<>(converterFactory.requestBodyConverter(type, annotations, methodAnnotations, retrofit));} else if (annotation instanceof Field) {// 如果注解是 Field 类型if (!isFormEncoded) {throw parameterError(method, p, "@Field parameters can only be used with form encoding.");}Field field = (Field) annotation;// 检查参数类型是否为基本类型或字符串if (Utils.hasUnresolvableType(type)) {throw parameterError(method, p,"@Field parameter type must not include a type variable or wildcard: %s", type);}// 创建 FieldParameterHandler 实例return new ParameterHandler.Field<>(field.value(), field.encoded(),converterFactory.stringConverter(type, annotations, retrofit));} else if (annotation instanceof FieldMap) {// 如果注解是 FieldMap 类型if (!isFormEncoded) {throw parameterError(method, p, "@FieldMap parameters can only be used with form encoding.");}if (!Map.class.isAssignableFrom(Utils.getRawType(type))) {throw parameterError(method, p, "@FieldMap parameter type must be Map.");}Type keyType = Utils.getSupertype(type, Map.class, String.class);if (keyType != String.class) {throw parameterError(method, p, "@FieldMap keys must be of type String: %s", type);}Type valueType = Utils.getSupertype(type, Map.class, Object.class);// 创建 FieldMapParameterHandler 实例return new ParameterHandler.FieldMap<>(converterFactory.stringConverter(valueType, annotations, retrofit));} else if (annotation instanceof Part) {// 如果注解是 Part 类型if (!isMultipart) {throw parameterError(method, p, "@Part parameters can only be used with multipart encoding.");}Part part = (Part) annotation;String partName = part.value();if (!"".equals(partName) && !partName.endsWith(";")) {partName = partName + ";";}// 创建 PartParameterHandler 实例return new ParameterHandler.Part<>(partName,converterFactory.requestBodyConverter(type, annotations, methodAnnotations, retrofit));} else if (annotation instanceof PartMap) {// 如果注解是 PartMap 类型if (!isMultipart) {throw parameterError(method, p, "@PartMap parameters can only be used with multipart encoding.");}if (!Map.class.isAssignableFrom(Utils.getRawType(type))) {throw parameterError(method, p, "@PartMap parameter type must be Map.");}Type keyType = Utils.getSupertype(type, Map.class, String.class);if (keyType != String.class) {throw parameterError(method, p, "@PartMap keys must be of type String: %s", type);}Type valueType = Utils.getSupertype(type, Map.class, Object.class);// 创建 PartMapParameterHandler 实例return new ParameterHandler.PartMap<>(converterFactory.requestBodyConverter(valueType, annotations, methodAnnotations, retrofit));}return null;}
}
4.3.1 详细解析逻辑

  • @Path 注解解析：

    • 首先，从 Path 注解中获取占位符名称，检查该占位符是否存在于之前解析得到的 relativeUrlParamNames 列表中。如果不存在，会抛出异常，确保路径占位符的正确性。
    • 接着，检查参数类型是否包含不可解析的类型变量或通配符。如果存在，也会抛出异常，因为 @Path 参数类型应该是基本类型或字符串。
    • 最后，创建 ParameterHandler.Path 实例，该实例负责处理路径占位符的替换。converterFactory.stringConverter 方法用于创建一个将参数类型转换为字符串的转换器，以便将参数值正确地替换到路径中。

  • @Query 注解解析：

    • 对于 Query 注解，同样会检查参数类型是否包含不可解析的类型变量或通配符。
    • 然后创建 ParameterHandler.Query 实例，该实例会将参数值作为查询参数添加到 URL 中。converterFactory.stringConverter 用于将参数值转换为字符串形式。

  • @QueryMap 注解解析：

    • 先检查参数类型是否为 Map 类型，如果不是会抛出异常。
    • 接着检查 Map 的键类型是否为 String 类型，若不是也会抛出异常。
    • 最后创建 ParameterHandler.QueryMap 实例，该实例会将 Map 中的键值对作为查询参数添加到 URL 中。converterFactory.stringConverter 用于将 Map 的值转换为字符串。

  • @Header 注解解析：

    • 检查参数类型是否包含不可解析的类型变量或通配符。
    • 创建 ParameterHandler.Header 实例，该实例会将参数值作为请求头添加到请求中。converterFactory.stringConverter 用于将参数值转换为字符串形式的请求头值。

  • @HeaderMap 注解解析：

    • 检查参数类型是否为 Map 类型，以及 Map 的键类型是否为 String 类型。
    • 创建 ParameterHandler.HeaderMap 实例，该实例会将 Map 中的键值对作为请求头添加到请求中。converterFactory.stringConverter 用于将 Map 的值转换为字符串形式的请求头值。

  • @Body 注解解析：

    • 检查当前请求是否为表单编码或多部分请求，如果是则抛出异常，因为 @Body 参数不能与表单或多部分编码同时使用。
    • 创建 ParameterHandler.Body 实例，该实例会将参数作为请求体发送。converterFactory.requestBodyConverter 用于将参数类型转换为 RequestBody 类型，以便进行网络传输。

  • @Field 注解解析：

    • 检查当前请求是否为表单编码请求，如果不是则抛出异常，因为 @Field 参数只能用于表单编码请求。
    • 检查参数类型是否包含不可解析的类型变量或通配符。
    • 创建 ParameterHandler.Field 实例，该实例会将参数值作为表单字段添加到请求体中。converterFactory.stringConverter 用于将参数值转换为字符串形式的表单字段值。

  • @FieldMap 注解解析：

    • 检查当前请求是否为表单编码请求，以及参数类型是否为 Map 类型，Map 的键类型是否为 String 类型。
    • 创建 ParameterHandler.FieldMap 实例，该实例会将 Map 中的键值对作为表单字段添加到请求体中。converterFactory.stringConverter 用于将 Map 的值转换为字符串形式的表单字段值。

  • @Part 注解解析：

    • 检查当前请求是否为多部分请求，如果不是则抛出异常，因为 @Part 参数只能用于多部分请求。
    • 处理 Part 注解的 value 属性，确保其格式正确。
    • 创建 ParameterHandler.Part 实例，该实例会将参数作为多部分请求的一部分添加到请求体中。converterFactory.requestBodyConverter 用于将参数类型转换为 RequestBody 类型。

  • @PartMap 注解解析：

    • 检查当前请求是否为多部分请求，以及参数类型是否为 Map 类型，Map 的键类型是否为 String 类型。
    • 创建 ParameterHandler.PartMap 实例，该实例会将 Map 中的键值对作为多部分请求的多个部分添加到请求体中。converterFactory.requestBodyConverter 用于将 Map 的值转换为 RequestBody 类型。

4.4 创建 RequestFactory 实例

在完成所有参数注解的解析后，会调用 RequestFactory.Builder 的 build 方法来构建 RequestFactory 实例：

java

RequestFactory build() {return new RequestFactory(this);
}

RequestFactory 类封装了所有解析得到的请求信息，包括请求方法、请求路径、请求头、请求体等，后续会根据这些信息创建实际的 Request 对象。

4.5 创建 CallAdapter 和 Converter 实例

在 ServiceMethod.parseAnnotations 方法中，还会创建 CallAdapter 和 Converter 实例：

java

// 创建 CallAdapter 实例，用于将 Call 对象转换为其他类型
CallAdapter<T, ?> callAdapter = createCallAdapter(retrofit, method, returnType, requestFactory);
// 获取响应类型
Type responseType = callAdapter.responseType();
if (Utils.hasUnresolvableType(responseType)) {throw methodError(method, "Call return type must not include a type variable or wildcard: %s", returnType);
}// 创建 Converter 实例，用于将响应数据转换为指定类型
Converter<ResponseBody, T> responseConverter =createResponseConverter(retrofit, method, responseType);
4.5.1 CallAdapter 实例创建

createCallAdapter 方法通过 Retrofit 实例的 callAdapter 方法从 CallAdapter.Factory 列表中查找合适的 CallAdapter.Factory，并调用其 get 方法创建 CallAdapter 实例。CallAdapter 的作用是将 Call 对象转换为其他类型，例如将 Call<Response> 转换为 Observable<Response> 等，以支持不同的异步编程模型。

4.5.2 Converter 实例创建

createResponseConverter 方法通过 Retrofit 实例的 responseBodyConverter 方法从 Converter.Factory 列表中查找合适的 Converter.Factory，并调用其 responseBodyConverter 方法创建 Converter 实例。Converter 的作用是将 ResponseBody 转换为指定的响应类型，例如将 JSON 数据转换为 Java 对象。

4.6 创建 ServiceMethod 实例

最后，根据前面解析得到的信息，创建 ServiceMethod 实例：

java

// 获取 OkHttpClient 实例
okhttp3.Call.Factory callFactory = retrofit.callFactory();
// 创建 ServiceMethod 实例
return new HttpServiceMethod<>(callFactory, requestFactory, callAdapter, responseConverter);

HttpServiceMethod 是 ServiceMethod 的具体实现类，它负责执行实际的 HTTP 请求，并处理响应结果。在 invoke 方法中，会根据 RequestFactory 创建 Request 对象，使用 OkHttpClient 发送请求，然后通过 CallAdapter 和 Converter 处理响应。

java

final class HttpServiceMethod<ResponseT, ReturnT> extends ServiceMethod<ReturnT> {private final okhttp3.Call.Factory callFactory;private final RequestFactory requestFactory;private final CallAdapter<ResponseT, ReturnT> callAdapter;private final Converter<ResponseBody, ResponseT> responseConverter;HttpServiceMethod(okhttp3.Call.Factory callFactory, RequestFactory requestFactory,CallAdapter<ResponseT, ReturnT> callAdapter,Converter<ResponseBody, ResponseT> responseConverter) {this.callFactory = callFactory;this.requestFactory = requestFactory;this.callAdapter = callAdapter;this.responseConverter = responseConverter;}@Override@Nullable ReturnT invoke(Object[] args) {// 创建 OkHttp 的 Request 对象Request request = requestFactory.create(args);// 创建 OkHttp 的 Call 对象okhttp3.Call call = callFactory.newCall(request);// 调用 CallAdapter 的 adapt 方法将 Call 对象转换为指定类型return callAdapter.adapt(new OkHttpCall<>(request, callFactory, responseConverter));}
}

五、注解解析后的使用

当 ServiceMethod 实例创建完成后，就可以使用它来发起 HTTP 请求了。在调用服务接口的方法时，实际上是调用 ServiceMethod 的 invoke 方法：

java

public interface ApiService {@GET("users/{id}")Call<User> getUser(@Path("id") int userId);
}// 创建 Retrofit 实例
Retrofit retrofit = new Retrofit.Builder().baseUrl("https://api.example.com/").addConverterFactory(GsonConverterFactory.create()).build();// 创建服务代理对象
ApiService apiService = retrofit.create(ApiService.class);// 发起请求
Call<User> call = apiService.getUser(1);
call.enqueue(new Callback<User>() {@Overridepublic void onResponse(Call<User> call, Response<User> response) {if (response.isSuccessful()) {User user = response.body();// 处理响应数据} else {// 处理请求失败}}@Overridepublic void onFailure(Call<User> call, Throwable t) {// 处理请求异常}
});

在上述代码中，apiService.getUser(1) 实际上调用了 ServiceMethod 的 invoke 方法，该方法会根据之前解析得到的注解信息创建 Request 对象，使用 OkHttpClient 发送请求，并通过 CallAdapter 和 Converter 处理响应结果。

六、总结

Retrofit 的注解定义与解析模块是其核心功能之一，通过使用注解，开发者可以以一种简洁、声明式的方式定义 HTTP 请求。在解析过程中，Retrofit 利用 Java 的反射机制，在运行时获取方法和参数上的注解信息，并根据注解类型进行相应的处理。具体步骤包括解析请求方法和路径注解、解析参数注解、创建 RequestFactory、CallAdapter 和 Converter 实例，最终创建 ServiceMethod 实例来执行实际的 HTTP 请求。这种设计使得 Retrofit 具有高度的灵活性和可扩展性，开发者可以通过自定义 CallAdapter.Factory 和 Converter.Factory 来满足不同的需求。同时，注解的使用也使得代码更加清晰、易读和易于维护，提高了开发效率。

本文来自互联网用户投稿，该文观点仅代表作者本人，不代表本站立场。本站仅提供信息存储空间服务，不拥有所有权，不承担相关法律责任。如若转载，请注明出处：http://www.mzph.cn/pingmian/71992.shtml

如若内容造成侵权/违法违规/事实不符，请联系多彩编程网进行投诉反馈email:809451989@qq.com，一经查实，立即删除！

相关文章

C# Enumerable类 之 数据分组

C# Enumerable类 之 数据分组

总目录 前言 在 C# 中&#xff0c;System.Linq.Enumerable 类是 LINQ&#xff08;Language Integrated Query&#xff09;的核心组成部分&#xff0c;它提供了一系列静态方法&#xff0c;用于操作实现了 IEnumerable 接口的集合。通过这些方法&#xff0c;我们可以轻松地对集合…
阅读更多...
推理模型对SQL理解能力的评测：DeepSeek r1、GPT-4o、Kimi k1.5和Claude 3.7 Sonnet

推理模型对SQL理解能力的评测：DeepSeek r1、GPT-4o、Kimi k1.5和Claude 3.7 Sonnet

引言 随着大型语言模型&#xff08;LLMs&#xff09;在技术领域的应用日益广泛&#xff0c;评估这些模型在特定技术任务上的能力变得越来越重要。本研究聚焦于四款领先的推理模型——DeepSeek r1、GPT-4o、Kimi k1.5和Claude 3.7 Sonnet在SQL理解与分析方面的能力&#xff0c;…
阅读更多...
IDEA接入阿里云百炼中免费的通义千问[2025版]

IDEA接入阿里云百炼中免费的通义千问[2025版]

安装deepseek 上一篇文章IDEA安装deepseek最新教程2025中说明了怎么用idea安装codeGPT插件&#xff0c;并接入DeepSeek&#xff0c;无奈接入的官方api已经不能使用了&#xff0c;所以我们尝试从其他地方接入 阿里云百炼https://bailian.console.aliyun.com/ 阿里云百炼‌是阿…
阅读更多...
实施一套先进的智能摄像头服务系统。

实施一套先进的智能摄像头服务系统。

一、项目背景 随着物联网、人工智能和大数据技术的飞速发展&#xff0c;智能摄像头已成为家庭、企业以及公共安全领域的重要设备。其便捷、高效、智能的特点&#xff0c;使得市场需求日益增长。为了满足用户对智能监控的多样化需求&#xff0c;提供更加全面、可靠的监控服务&a…
阅读更多...
linux自启动服务

linux自启动服务

在Linux环境中&#xff0c;systemd是一个系统和服务管理器&#xff0c;它为每个服务使用.service文件进行配置。systemctl是用于控制系统服务的主要工具。本文将详细介绍如何使用systemctl来管理vsftpd服务&#xff0c;以及如何设置服务自启动。 使用Systemd设置自启动服务 创…
阅读更多...
010-Catch2

010-Catch2

Catch2 一、框架简介 Catch2 是一个基于 C 的现代化单元测试框架&#xff0c;支持 TDD&#xff08;测试驱动开发&#xff09;和 BDD&#xff08;行为驱动开发&#xff09;模式。其核心优势在于&#xff1a; 单头文件设计&#xff1a;v2.x 版本仅需包含 catch.hpp 即可使用自然…
阅读更多...
数字人分身开发指南：从概念到实战

数字人分身开发指南：从概念到实战

一、什么是数字人分身&#xff1f; 想象一下&#xff0c;在电脑或手机屏幕里&#xff0c;一个能跟你聊天、回答问题&#xff0c;甚至还能做表情的虚拟角色。这就是数字人分身&#xff0c;它用上了人工智能技术&#xff0c;让机器也能像人一样交流。无论是在线客服、网络主播还…
阅读更多...
Pixelmator Pro for Mac 专业图像处理软件【媲美PS的修图】

Pixelmator Pro for Mac 专业图像处理软件【媲美PS的修图】

介绍 Pixelmator Pro&#xff0c;是一款非常强大、美观且易于使用的图像编辑器&#xff0c;专为 Mac 设计。采用单窗口界面、基于机器学习的智能图像编辑、自动水平检测&#xff0c;智能快速选择及更好的修复工具等功能优点。许多非破坏性的专业编辑工具可让您进行最佳的照片处…
阅读更多...
LiveGBS流媒体平台GB/T28181常见问题-视频流安全控制HTTP接口鉴权勾选流地址鉴权后401Unauthorized如何播放调用接口流地址校验

LiveGBS流媒体平台GB/T28181常见问题-视频流安全控制HTTP接口鉴权勾选流地址鉴权后401Unauthorized如何播放调用接口流地址校验

LiveGBS流媒体平台GB/T28181常见问题频流安全控制HTTP接口鉴权勾选流地址鉴权后401Unauthorized如何播放调用接口流地址校验&#xff1f; 1、安全控制1.1、HTTP接口鉴权1.2、流地址鉴权 2、401 Unauthorized2.1、携带token调用接口2.1.1、获取鉴权token2.1.2、调用其它接口2.1.…
阅读更多...
C++设计模式-抽象工厂模式：从原理、适用场景、使用方法，常见问题和解决方案深度解析

C++设计模式-抽象工厂模式：从原理、适用场景、使用方法，常见问题和解决方案深度解析

一、模式基本概念 1.1 定义与核心思想 抽象工厂模式&#xff08;Abstract Factory Pattern&#xff09;是创建型设计模式的集大成者&#xff0c;它通过提供统一的接口来创建多个相互关联或依赖的对象族&#xff0c;而无需指定具体类。其核心思想体现在两个维度&#xff1a; …
阅读更多...
【prompt实战】知乎问题解答专家

【prompt实战】知乎问题解答专家

本文原创作者&#xff1a;姚瑞南 AI-agent 大模型运营专家&#xff0c;先后任职于美团、猎聘等中大厂AI训练专家和智能运营专家岗&#xff1b;多年人工智能行业智能产品运营及大模型落地经验&#xff0c;拥有AI外呼方向国家专利与PMP项目管理证书。&#xff08;转载需经授权&am…
阅读更多...
数据结构第八节：红黑树（初阶）

数据结构第八节：红黑树（初阶）

【本节要点】 红黑树概念红黑树性质红黑树结点定义红黑树结构红黑树插入操作的分析 一、红黑树的概念与性质 1.1 红黑树的概念 红黑树 &#xff0c;是一种 二叉搜索树 &#xff0c;但 在每个结点上增加一个存储位表示结点的颜色&#xff0c;可以是 Red和 Black 。 通过对 任何…
阅读更多...
Spring Boot3.3.X整合Mybatis-Plus

Spring Boot3.3.X整合Mybatis-Plus

前提说明&#xff1a; 项目的springboot版本为&#xff1a;3.3.2 需要整合的mybatis-plus版本&#xff1a;3.5.7 废话不多说&#xff0c;开始造吧 1.准备好数据库和表 2.配置全局文件application.properties或者是application.yml&#xff08;配置mapper的映射文件路径&am…
阅读更多...
可视化图解算法：链表指定区间反转

可视化图解算法：链表指定区间反转

1. 题目 描述 给你单链表的头指针 head 和两个整数 left 和 right &#xff0c;其中 left < right 。请你反转从位置 left 到位置 right 的链表节点&#xff0c;返回 反转后的链表 。 示例1 输入&#xff1a; 输入&#xff1a;head [1,2,3,4,5], left 2, right 4 输…
阅读更多...
✨SQL-递归CTE

✨SQL-递归CTE

&#x1f4d6; SQL魔法课堂&#xff1a;CTE「时间折叠术」全解 &#x1f3a9; 第一章&#xff1a;什么是CTE&#xff1f; CTE&#xff08;Common Table Expression&#xff09; 就像 SQL 里的「临时笔记本」&#x1f4d2;&#xff1a; WITH 临时笔记本 AS ( SELECT ... FRO…
阅读更多...
Cursor 新手入门使用教程

Cursor 新手入门使用教程

一、Cursor 是什么&#xff1f; Cursor 是一个集成了 GPT-4、Claude 3.5 等先进 LLM&#xff08;大语言模型&#xff09;的类 VSCode 编译器&#xff0c;可以理解为在 VSCode 中集成了 AI 辅助编程助手。从界面布局来看&#xff0c;Cursor 与 VSCode 基本一致&#xff0c;且使…
阅读更多...
如何在Spring Boot中配置和使用MyBatis-Plus

如何在Spring Boot中配置和使用MyBatis-Plus

在当今的Java开发中&#xff0c;Spring Boot已经成为了一个非常流行的框架&#xff0c;而MyBatis-Plus则是一个强大的ORM框架&#xff0c;为开发人员提供了更简便的数据库操作方式。很多开发者都在使用Spring Boot和MyBatis-Plus的组合来快速构建高效的应用。今天就来聊聊如何在…
阅读更多...
【贪心算法3】

【贪心算法3】

力扣1005.k次取反后最大化的数组和 链接: link 思路 既然要求最大和&#xff0c;那么不妨先给数组排个序&#xff0c;如果有负数&#xff0c;先处理负数从前往后给数组取反&#xff0c;如果负数处理完后k还有次数&#xff0c;此时数组全是正数了&#xff0c;只需要对第一个元…
阅读更多...
自然语言处理中的语音识别技术：从声波到语义的智能解码

自然语言处理中的语音识别技术：从声波到语义的智能解码

引言 语音识别&#xff08;Automatic Speech Recognition, ASR&#xff09;是自然语言处理&#xff08;NLP&#xff09;的关键分支&#xff0c;旨在将人类语音信号转化为可处理的文本信息。随着深度学习技术的突破&#xff0c;语音识别已从实验室走向日常生活&#xff0c;赋能…
阅读更多...
1688店铺所有商品数据接口详解

1688店铺所有商品数据接口详解

​​一、接口概述淘宝开放平台提供 1688.items.onsale.get/taobao.item_search_shop 接口&#xff0c;可批量获取店铺在售商品列表&#xff0c;包含商品 ID、标题、价格、销量、图片等核心信息。该接口适用于商品库管理、竞品监控、数据分析等场景 ​二、接口调用流程 前期准…
阅读更多...
最新文章

Copyright @ 2022~2023