public Retrofit build() {
//baseUrl是必須的
if (baseUrl == null) {
throw new IllegalStateException("Base URL required.");
}
//如果沒(méi)有設(shè)置callFactory對(duì)象，系統(tǒng)自動(dòng)生成一個(gè)OkhttpClient對(duì)象.因?yàn)镺KHttpclient實(shí)現(xiàn)了 Call.Factory接口
// public class OkHttpClient implements Cloneable, Call.Factory, WebSocket.Factory
okhttp3.Call.Factory callFactory = this.callFactory;
if (callFactory == null) {
callFactory = new OkHttpClient();
}
//如果沒(méi)有設(shè)置callbackExecutor，系統(tǒng)自動(dòng)生成一個(gè)，platform.defaultCallbackExecutor，這個(gè)platform是無(wú)參構(gòu)造方法里調(diào)用Platform.get()方法得到的。
/**
public Builder() {
this(Platform.get());
}**/
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);
}
Platform
class Platform {
private static final Platform PLATFORM = findPlatform();
static Platform get() {
return PLATFORM;
}
private static Platform findPlatform() {
try {
Class.forName("android.os.Build");
if (Build.VERSION.SDK_INT != 0) {
return new Android();
}
} catch (ClassNotFoundException ignored) {
}
try {
Class.forName("java.util.Optional");
return new Java8();
} catch (ClassNotFoundException ignored) {
}
try {
//怎么還有IOS代碼呢？
Class.forName("org.robovm.apple.foundation.NSObject");
return new IOS();
} catch (ClassNotFoundException ignored) {
}
return new Platform();
}
Executor defaultCallbackExecutor() {
return null;
}
CallAdapter.Factory defaultCallAdapterFactory(Executor callbackExecutor) {
if (callbackExecutor != null) {
return new ExecutorCallAdapterFactory(callbackExecutor);
}
return DefaultCallAdapterFactory.INSTANCE;
}
boolean isDefaultMethod(Method method) {
return false;
}
Object invokeDefaultMethod(Method method, Class declaringClass, Object object, Object... args)
throws Throwable {
throw new UnsupportedOperationException();
}
static class Android extends Platform {
@Override public Executor defaultCallbackExecutor() {
return new MainThreadExecutor();
}
@Override CallAdapter.Factory defaultCallAdapterFactory(Executor callbackExecutor) {
return new ExecutorCallAdapterFactory(callbackExecutor);
}
static class MainThreadExecutor implements Executor {
private final Handler handler = new Handler(Looper.getMainLooper());
@Override public void execute(Runnable r) {
handler.post(r);
}
}
}
}
@SuppressWarnings("unchecked") // Single-interface proxy creation guarded by parameter safety.
public T create(final Class 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();
@Override public Object invoke(Object proxy, Method method, Object... args)
throws Throwable {
// 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);
}
//創(chuàng)建ServiceMethod對(duì)象
ServiceMethod serviceMethod = loadServiceMethod(method);
OkHttpCall okHttpCall = new OkHttpCall<>(serviceMethod, args);
return serviceMethod.callAdapter.adapt(okHttpCall);
}
});
}
public ServiceMethod build() {
//1 處理返回結(jié)果，做一定的轉(zhuǎn)換
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();
//2提取方法的注解
for (Annotation annotation : methodAnnotations) {
parseMethodAnnotation(annotation);
}
//如果httpMethod為null，即沒(méi)有使用方法類型注解修飾，拋出異常進(jìn)行提示
if (httpMethod == null) {
throw methodError("HTTP method annotation is required (e.g., @GET, @POST, etc.).");
}
//如果沒(méi)有請(qǐng)求體，即使用了GET，HEAD，DELETE，OPTIONS等所修飾，即不涉及到表單的提交，但是同時(shí)使用了Multipart，或者FormUrlEncoded所修飾，就報(bào)錯(cuò)
if (!hasBody) {
if (isMultipart) {
throw methodError(
"Multipart can only be specified on HTTP methods with request body (e.g., @POST).");
}
if (isFormEncoded) {
throw methodError("FormUrlEncoded can only be specified on HTTP methods with "
+ "request body (e.g., @POST).");
}
}
//3提取方法的參數(shù)
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);
}
//相對(duì)路徑為null且gotURL為false的話，拋出異常，因?yàn)闆](méi)有相對(duì)路徑無(wú)法請(qǐng)求。
if (relativeUrl == null && !gotUrl) {
throw methodError("Missing either @%s URL or @Url parameter.", httpMethod);
}
//沒(méi)有使用@FormUrlEncoded，@Multipart主機(jī)并且hasBody為false，但是gotBody為true，拋出異常，提示
Non-Body類型的HTTP method 不能參數(shù)不能使用@Body注解
if (!isFormEncoded && !isMultipart && !hasBody && gotBody) {
throw methodError("Non-body HTTP method cannot contain @Body.");
}
//使用@FormUrlEncoded修飾的方法中的參數(shù)至少有一個(gè)參數(shù)被@Field注解修飾
if (isFormEncoded && !gotField) {
throw methodError("Form-encoded method must contain at least one @Field.");
}
//使用@Multipart修飾的方法中的參數(shù)至少有一個(gè)參數(shù)被@Part注解修飾
if (isMultipart && !gotPart) {
throw methodError("Multipart method must contain at least one @Part.");
}
//4 當(dāng)前Builder對(duì)象初始化完畢，可以用來(lái)夠著ServiceMethod對(duì)象。
return new ServiceMethod<>(this);
}
處理返回結(jié)果
private CallAdapter createCallAdapter() {
//獲取方法的返回結(jié)果,如果有不能解析的類型則拋出異常，也就是說(shuō)接口中定義的方法的返回值不能使用泛型
Type returnType = method.getGenericReturnType();
if (Utils.hasUnresolvableType(returnType)) {
throw methodError(
"Method return type must not include a type variable or wildcard: %s", returnType);
}
//接口里的方法不能返回void
if (returnType == void.class) {
throw methodError("Service methods cannot return void.");
}
Annotation[] annotations = method.getAnnotations();
try {
return retrofit.callAdapter(returnType, annotations);
} catch (RuntimeException e) { // Wide exception range because factories are user code.
//用戶自定義的Adapter可能不能正確的處理返回結(jié)果，這時(shí)候拋出異常
throw methodError(e, "Unable to create call adapter for %s", returnType);
}
}
解析方法注解
1處處理方法的注解，就是先處理GET/POST/Header等注解信息
private void parseMethodAnnotation(Annotation annotation) {
if (annotation instanceof DELETE) {
parseHttpMethodAndPath("DELETE", ((DELETE) annotation).value(), false);
} else if (annotation instanceof GET) {
parseHttpMethodAndPath("GET", ((GET) annotation).value(), false);
} else if (annotation instanceof HEAD) {
parseHttpMethodAndPath("HEAD", ((HEAD) annotation).value(), false);
if (!Void.class.equals(responseType)) {
throw methodError("HEAD method must use Void as response type.");
}
} else if (annotation instanceof PATCH) {
parseHttpMethodAndPath("PATCH", ((PATCH) annotation).value(), true);
} else if (annotation instanceof POST) {
parseHttpMethodAndPath("POST", ((POST) annotation).value(), true);
} else if (annotation instanceof PUT) {
parseHttpMethodAndPath("PUT", ((PUT) annotation).value(), true);
} else if (annotation instanceof OPTIONS) {
parseHttpMethodAndPath("OPTIONS", ((OPTIONS) annotation).value(), false);
} else if (annotation instanceof HTTP) {
HTTP http = (HTTP) annotation;
parseHttpMethodAndPath(http.method(), http.path(), http.hasBody());
} else if (annotation instanceof retrofit2.http.Headers) {
headers注解
String[] headersToParse = ((retrofit2.http.Headers) annotation).value();
if (headersToParse.length == 0) {
throw methodError("@Headers annotation is empty.");
}
headers = parseHeaders(headersToParse);
} else if (annotation instanceof Multipart) {//如果是Multipart注解
if (isFormEncoded) {
//如果同時(shí)使用了FormUrlEncoded注解報(bào)錯(cuò)
throw methodError("Only one encoding annotation is allowed.");
}
isMultipart = true;
} else if (annotation instanceof FormUrlEncoded) {
if (isMultipart) {
//如果同時(shí)使用了Multipart注解報(bào)錯(cuò),從這我們可以看出一個(gè)方法不能同時(shí)被Multipart和FormUrlEncoded所修飾
throw methodError("Only one encoding annotation is allowed.");
}
isFormEncoded = true;
}
}
private void parseHttpMethodAndPath(String httpMethod, String value, boolean hasBody) {
//如果該Builder已經(jīng)有HTTPMethod了就不能改變了，直接拋異常
if (this.httpMethod != null) {
throw methodError("Only one HTTP method is allowed. Found: %s and %s.",
this.httpMethod, httpMethod);
}
//將HTTPMethod賦值給httpMethod對(duì)象，Get、Post、Delete等
this.httpMethod = httpMethod;
this.hasBody = hasBody;//是否有請(qǐng)求體
//如果value為null，返回，因?yàn)関alue參數(shù)的值其實(shí)就是relativeURL。所以不能為null
if (value.isEmpty()) {
return;
}
// Get the relative URL path and existing query string, if present.
int question = value.indexOf("?");
if (question != -1 && question < value.length() - 1) {
// Ensure the query string does not have any named parameters.
String queryParams = value.substring(question + 1);
//獲取查詢參數(shù)
Matcher queryParamMatcher = PARAM_URL_REGEX.matcher(queryParams);
if (queryParamMatcher.find()) {
//如果在value里面找到里查詢參數(shù)的話，拋出異常。因?yàn)椴樵儏?shù)可以使用@Query注解來(lái)動(dòng)態(tài)配置。
throw methodError("URL query string "%s" must not have replace block. "
+ "For dynamic query parameters use @Query.", queryParams);
}
}
this.relativeUrl = value; //將value賦值給relativeUrl
this.relativeUrlParamNames = parsePathParameters(value); //獲取value里面的path占位符，如果有的話
}
再來(lái)看下解析value里的path占位符的方法。
/**
獲取已知URI里面的路徑集合，如果一個(gè)參數(shù)被使用了兩次，它只會(huì)在set中出現(xiàn)一次，好拗口啊，使用LinkedHashSet來(lái)保存path參數(shù)集合，保證了路徑參數(shù)的順序。
* Gets the set of unique path parameters used in the given URI. If a parameter is used twice
* in the URI, it will only show up once in the set.
*/
static Set parsePathParameters(String path) {
Matcher m = PARAM_URL_REGEX.matcher(path);
Set patterns = new LinkedHashSet<>();
while (m.find()) {
patterns.add(m.group(1));
}
return patterns;
}
private Headers parseHeaders(String[] headers) {
Headers.Builder builder = new Headers.Builder();
for (String header : headers) {
// header以“:"分割，前面是key,后面是value
int colon = header.indexOf(":");
if (colon == -1 || colon == 0 || colon == header.length() - 1) {
//header必須是key:value格式表示，不然報(bào)錯(cuò)
throw methodError(
"@Headers value must be in the form "Name: Value". Found: "%s"", header);
}
String headerName = header.substring(0, colon); //key值
String headerValue = header.substring(colon + 1).trim(); //value值，必須是一個(gè)數(shù)組，艸，又猜錯(cuò)了。
if ("Content-Type".equalsIgnoreCase(headerName)) {
//遇到"Content-Type"字段。還需要獲得具體的MediaType。
MediaType type = MediaType.parse(headerValue);
if (type == null) {
//如果mediaType為null。拋出一個(gè)type畸形的錯(cuò)誤。
throw methodError("Malformed content type: %s", headerValue);
}
contentType = type;
} else {
將header的key和value加入到Builder里面。
builder.add(headerName, headerValue);
}
}
最后調(diào)用build方法生成一個(gè)Header對(duì)愛(ài)。
return builder.build();
}
/**
* Add a header with the specified name and value. Does validation of header names and values.
*/
public Builder add(String name, String value) {
checkNameAndValue(name, value);
return addLenient(name, value);
}
int parameterCount = parameterAnnotationsArray.length; //求得數(shù)組的長(zhǎng)度
parameterHandlers = new ParameterHandler[parameterCount];
for (int p = 0; p < parameterCount; p++) {
Type parameterType = parameterTypes[p]; //便利參數(shù)，依次處理參數(shù)
//如果參數(shù)不能解析，拋出異常
if (Utils.hasUnresolvableType(parameterType)) {
throw parameterError(p, "Parameter type must not include a type variable or wildcard: %s",
parameterType);
}
//獲取第p個(gè)參數(shù)的注解數(shù)組，如果沒(méi)有注解拋出異常，可見(jiàn)，使用了Retrofit，接口方法中每個(gè)參數(shù)都必須使用注解進(jìn)行修飾。
Annotation[] parameterAnnotations = parameterAnnotationsArray[p];
if (parameterAnnotations == null) {
throw parameterError(p, "No Retrofit annotation found.");
}
//解析方法中的參數(shù)，存入parameterHandlers[]數(shù)組中。
parameterHandlers[p] = parseParameter(p, parameterType, parameterAnnotations);
}
static boolean hasUnresolvableType(Type type) {
//如果參數(shù)是引用數(shù)據(jù)類型，返回false，可見(jiàn)，接口定義中方法的參數(shù)只能是基本數(shù)據(jù)類型
if (type instanceof Class) {
return false;
}
//如果參數(shù)是泛型
if (type instanceof ParameterizedType) {
ParameterizedType parameterizedType = (ParameterizedType) type;
//去除泛型類中的實(shí)際類型，遍歷
for (Type typeArgument : parameterizedType.getActualTypeArguments()) {
//如果有一個(gè)泛型參數(shù)是基本數(shù)據(jù)類型，返回true，都不是返回false
if (hasUnresolvableType(typeArgument)) {
return true;
}
}
return false;
}
//如果參數(shù)是泛型數(shù)組類型
if (type instanceof GenericArrayType) {
return hasUnresolvableType(((GenericArrayType) type).getGenericComponentType());
}
if (type instanceof TypeVariable) {
return true;
}
if (type instanceof WildcardType) {
return true;
}
String className = type == null ? "null" : type.getClass().getName();
throw new IllegalArgumentException("Expected a Class, ParameterizedType, or "
+ "GenericArrayType, but <" + type + "> is of type " + className);
}
解析參數(shù)
parameterHandlers[p] = parseParameter(p, parameterType, parameterAnnotations);
private ParameterHandler parseParameter(
int p, Type parameterType, Annotation[] annotations) {
ParameterHandler result = null;
//遍歷參數(shù)的注解數(shù)組，調(diào)用parseParameterAnnotation()
for (Annotation annotation : annotations) {
ParameterHandler annotationAction = parseParameterAnnotation(
p, parameterType, annotations, annotation);
//如果該注解沒(méi)有返回，則解析下一個(gè)注解
if (annotationAction == null) {
continue;
}
if (result != null) {
throw parameterError(p, "Multiple Retrofit annotations found, only one allowed.");
}
result = annotationAction; //將解析的結(jié)果賦值給Result
}
//如果注解為null，拋出異常。這個(gè)地方永遠(yuǎn)不會(huì)調(diào)用，因?yàn)樵讷@取注解數(shù)組之前就做過(guò)判斷了，如果注解數(shù)組為null，直接拋異常，Line197-Line200 in ServiceMethod.Builder中
if (result == null) {
throw parameterError(p, "No Retrofit annotation found.");
}
return result;
}
獲取參數(shù)注解信息
再來(lái)看看parseParameterAnnotation()方法,內(nèi)容略多
private ParameterHandler parseParameterAnnotation(
int p, Type type, Annotation[] annotations, Annotation annotation) {
if (annotation instanceof Url) {
//如果使用了Url注解，
if (gotUrl) {
//如果gotUrl為true，因?yàn)間otURL默認(rèn)為false，說(shuō)明之前處理過(guò)Url注解了,拋出多個(gè)@Url注解異常
throw parameterError(p, "Multiple @Url method annotations found.");
}
if (gotPath) {
//如果gotPath為true，拋出異常，說(shuō)明@Path注解不能和@Url注解一起使用
throw parameterError(p, "@Path parameters may not be used with @Url.");
}
if (gotQuery) {
//如果gotQuery為true，拋出異常，說(shuō)明@Url注解不能用在@Query注解后面
throw parameterError(p, "A @Url parameter must not come after a @Query");
}
if (relativeUrl != null) {
//如果relativeUrl不為null,拋出異常，說(shuō)明使用了@Url注解，relativeUrl必須為null
throw parameterError(p, "@Url cannot be used with @%s URL", httpMethod);
}
gotUrl = true;
----------------------------------------------------------------------------------------
//如果參數(shù)類型是HttpURL，String，URI或者參數(shù)類型是“android.net.Uri",返回ParameterHandler.RelativeUrl()，實(shí)際是交由這個(gè)類處理
if (type == HttpUrl.class
|| type == String.class
|| type == URI.class
|| (type instanceof Class && "android.net.Uri".equals(((Class) type).getName()))) {
return new ParameterHandler.RelativeUrl();
} else {
//不然就拋出異常，也就是說(shuō)@Url注解必須使用在okhttp3.HttpUrl, String, java.net.URI, or android.net.Uri 這幾種類型的參數(shù)上。
throw parameterError(p,
"@Url must be okhttp3.HttpUrl, String, java.net.URI, or android.net.Uri type.");
}
------------------------------------------------------------------------------------------
} else if (annotation instanceof Path) { //@Path注解
//如果gotQuery為true。拋出異常，因?yàn)锧Path修飾的參數(shù)是路徑的占位符。不是查詢參數(shù)，不能使用@Query注解修飾
if (gotQuery) {
throw parameterError(p, "A @Path parameter must not come after a @Query.");
}
if (gotUrl) {
throw parameterError(p, "@Path parameters may not be used with @Url.");
}
//如果相對(duì)路徑為null，那@path注解也就無(wú)意義了。
if (relativeUrl == null) {
throw parameterError(p, "@Path can only be used with relative url on @%s", httpMethod);
}
gotPath = true;
Path path = (Path) annotation;
String name = path.value(); //獲取@Path注解的值
validatePathName(p, name); //對(duì)改值進(jìn)行校驗(yàn)，1該value必須是合法字符，2:該相對(duì)路徑必須包含相應(yīng)的占位符
//然后將改參數(shù)的所有注解進(jìn)行處理，最終調(diào)用ParameterHandler.Path進(jìn)行處理。
Converter converter = retrofit.stringConverter(type, annotations);
return new ParameterHandler.Path<>(name, converter, path.encoded());
} else if (annotation instanceof Query) { //Query注解，看不太懂，最后也是調(diào)用ParameterHandler.Query進(jìn)行處理
Query query = (Query) annotation;
String name = query.value();
boolean encoded = query.encoded();
Class rawParameterType = Utils.getRawType(type);
gotQuery = true;
if (Iterable.class.isAssignableFrom(rawParameterType)) {
if (!(type instanceof ParameterizedType)) {
throw parameterError(p, rawParameterType.getSimpleName()
+ " must include generic type (e.g., "
+ rawParameterType.getSimpleName()
+ ")");
}
ParameterizedType parameterizedType = (ParameterizedType) type;
Type iterableType = Utils.getParameterUpperBound(0, parameterizedType);
Converter converter =
retrofit.stringConverter(iterableType, annotations);
return new ParameterHandler.Query<>(name, converter, encoded).iterable();
} else if (rawParameterType.isArray()) {
Class arrayComponentType = boxIfPrimitive(rawParameterType.getComponentType());
Converter converter =
retrofit.stringConverter(arrayComponentType, annotations);
return new ParameterHandler.Query<>(name, converter, encoded).array();
} else {
Converter converter =
retrofit.stringConverter(type, annotations);
return new ParameterHandler.Query<>(name, converter, encoded);
}
} else if (annotation instanceof QueryMap) {
Class rawParameterType = Utils.getRawType(type);
if (!Map.class.isAssignableFrom(rawParameterType)) {
throw parameterError(p, "@QueryMap parameter type must be Map.");
}
Type mapType = Utils.getSupertype(type, rawParameterType, Map.class);
if (!(mapType instanceof ParameterizedType)) {
throw parameterError(p, "Map must include generic types (e.g., Map)");
}
ParameterizedType parameterizedType = (ParameterizedType) mapType;
Type keyType = Utils.getParameterUpperBound(0, parameterizedType);
if (String.class != keyType) {
throw parameterError(p, "@QueryMap keys must be of type String: " + keyType);
}
Type valueType = Utils.getParameterUpperBound(1, parameterizedType);
Converter valueConverter =
retrofit.stringConverter(valueType, annotations);
return new ParameterHandler.QueryMap<>(valueConverter, ((QueryMap) annotation).encoded());
} else if (annotation instanceof Header) {
Header header = (Header) annotation;
String name = header.value();
Class rawParameterType = Utils.getRawType(type);
if (Iterable.class.isAssignableFrom(rawParameterType)) {
if (!(type instanceof ParameterizedType)) {
throw parameterError(p, rawParameterType.getSimpleName()
+ " must include generic type (e.g., "
+ rawParameterType.getSimpleName()
+ ")");
}
ParameterizedType parameterizedType = (ParameterizedType) type;
Type iterableType = Utils.getParameterUpperBound(0, parameterizedType);
Converter converter =
retrofit.stringConverter(iterableType, annotations);
return new ParameterHandler.Header<>(name, converter).iterable();
} else if (rawParameterType.isArray()) {
Class arrayComponentType = boxIfPrimitive(rawParameterType.getComponentType());
Converter converter =
retrofit.stringConverter(arrayComponentType, annotations);
return new ParameterHandler.Header<>(name, converter).array();
} else {
Converter converter =
retrofit.stringConverter(type, annotations);
return new ParameterHandler.Header<>(name, converter);
}
} else if (annotation instanceof HeaderMap) {
Class rawParameterType = Utils.getRawType(type);
if (!Map.class.isAssignableFrom(rawParameterType)) {
throw parameterError(p, "@HeaderMap parameter type must be Map.");
}
Type mapType = Utils.getSupertype(type, rawParameterType, Map.class);
if (!(mapType instanceof ParameterizedType)) {
throw parameterError(p, "Map must include generic types (e.g., Map)");
}
ParameterizedType parameterizedType = (ParameterizedType) mapType;
Type keyType = Utils.getParameterUpperBound(0, parameterizedType);
if (String.class != keyType) {
throw parameterError(p, "@HeaderMap keys must be of type String: " + keyType);
}
Type valueType = Utils.getParameterUpperBound(1, parameterizedType);
Converter valueConverter =
retrofit.stringConverter(valueType, annotations);
return new ParameterHandler.HeaderMap<>(valueConverter);
} else if (annotation instanceof Field) {
if (!isFormEncoded) {
throw parameterError(p, "@Field parameters can only be used with form encoding.");
}
Field field = (Field) annotation;
String name = field.value();
boolean encoded = field.encoded();
gotField = true;
Class rawParameterType = Utils.getRawType(type);
if (Iterable.class.isAssignableFrom(rawParameterType)) {
if (!(type instanceof ParameterizedType)) {
throw parameterError(p, rawParameterType.getSimpleName()
+ " must include generic type (e.g., "
+ rawParameterType.getSimpleName()
+ ")");
}
ParameterizedType parameterizedType = (ParameterizedType) type;
Type iterableType = Utils.getParameterUpperBound(0, parameterizedType);
Converter converter =
retrofit.stringConverter(iterableType, annotations);
return new ParameterHandler.Field<>(name, converter, encoded).iterable();
} else if (rawParameterType.isArray()) {
Class arrayComponentType = boxIfPrimitive(rawParameterType.getComponentType());
Converter converter =
retrofit.stringConverter(arrayComponentType, annotations);
return new ParameterHandler.Field<>(name, converter, encoded).array();
} else {
Converter converter =
retrofit.stringConverter(type, annotations);
return new ParameterHandler.Field<>(name, converter, encoded);
}
} else if (annotation instanceof FieldMap) {
if (!isFormEncoded) {
throw parameterError(p, "@FieldMap parameters can only be used with form encoding.");
}
Class rawParameterType = Utils.getRawType(type);
if (!Map.class.isAssignableFrom(rawParameterType)) {
throw parameterError(p, "@FieldMap parameter type must be Map.");
}
Type mapType = Utils.getSupertype(type, rawParameterType, Map.class);
if (!(mapType instanceof ParameterizedType)) {
throw parameterError(p,
"Map must include generic types (e.g., Map)");
}
ParameterizedType parameterizedType = (ParameterizedType) mapType;
Type keyType = Utils.getParameterUpperBound(0, parameterizedType);
if (String.class != keyType) {
throw parameterError(p, "@FieldMap keys must be of type String: " + keyType);
}
Type valueType = Utils.getParameterUpperBound(1, parameterizedType);
Converter valueConverter =
retrofit.stringConverter(valueType, annotations);
gotField = true;
return new ParameterHandler.FieldMap<>(valueConverter, ((FieldMap) annotation).encoded());
} else if (annotation instanceof Part) {
if (!isMultipart) {
throw parameterError(p, "@Part parameters can only be used with multipart encoding.");
}
Part part = (Part) annotation;
gotPart = true;
String partName = part.value();
Class rawParameterType = Utils.getRawType(type);
if (partName.isEmpty()) {
if (Iterable.class.isAssignableFrom(rawParameterType)) {
if (!(type instanceof ParameterizedType)) {
throw parameterError(p, rawParameterType.getSimpleName()
+ " must include generic type (e.g., "
+ rawParameterType.getSimpleName()
+ ")");
}
ParameterizedType parameterizedType = (ParameterizedType) type;
Type iterableType = Utils.getParameterUpperBound(0, parameterizedType);
if (!MultipartBody.Part.class.isAssignableFrom(Utils.getRawType(iterableType))) {
throw parameterError(p,
"@Part annotation must supply a name or use MultipartBody.Part parameter type.");
}
return ParameterHandler.RawPart.INSTANCE.iterable();
} else if (rawParameterType.isArray()) {
Class arrayComponentType = rawParameterType.getComponentType();
if (!MultipartBody.Part.class.isAssignableFrom(arrayComponentType)) {
throw parameterError(p,
"@Part annotation must supply a name or use MultipartBody.Part parameter type.");
}
return ParameterHandler.RawPart.INSTANCE.array();
} else if (MultipartBody.Part.class.isAssignableFrom(rawParameterType)) {
return ParameterHandler.RawPart.INSTANCE;
} else {
throw parameterError(p,
"@Part annotation must supply a name or use MultipartBody.Part parameter type.");
}
} else {
Headers headers =
Headers.of("Content-Disposition", "form-data; name="" + partName + """,
"Content-Transfer-Encoding", part.encoding());
if (Iterable.class.isAssignableFrom(rawParameterType)) {
if (!(type instanceof ParameterizedType)) {
throw parameterError(p, rawParameterType.getSimpleName()
+ " must include generic type (e.g., "
+ rawParameterType.getSimpleName()
+ ")");
}
ParameterizedType parameterizedType = (ParameterizedType) type;
Type iterableType = Utils.getParameterUpperBound(0, parameterizedType);
if (MultipartBody.Part.class.isAssignableFrom(Utils.getRawType(iterableType))) {
throw parameterError(p, "@Part parameters using the MultipartBody.Part must not "
+ "include a part name in the annotation.");
}
Converter converter =
retrofit.requestBodyConverter(iterableType, annotations, methodAnnotations);
return new ParameterHandler.Part<>(headers, converter).iterable();
} else if (rawParameterType.isArray()) {
Class arrayComponentType = boxIfPrimitive(rawParameterType.getComponentType());
if (MultipartBody.Part.class.isAssignableFrom(arrayComponentType)) {
throw parameterError(p, "@Part parameters using the MultipartBody.Part must not "
+ "include a part name in the annotation.");
}
Converter converter =
retrofit.requestBodyConverter(arrayComponentType, annotations, methodAnnotations);
return new ParameterHandler.Part<>(headers, converter).array();
} else if (MultipartBody.Part.class.isAssignableFrom(rawParameterType)) {
throw parameterError(p, "@Part parameters using the MultipartBody.Part must not "
+ "include a part name in the annotation.");
} else {
Converter converter =
retrofit.requestBodyConverter(type, annotations, methodAnnotations);
return new ParameterHandler.Part<>(headers, converter);
}
}
} else if (annotation instanceof PartMap) {
if (!isMultipart) {
throw parameterError(p, "@PartMap parameters can only be used with multipart encoding.");
}
gotPart = true;
Class rawParameterType = Utils.getRawType(type);
if (!Map.class.isAssignableFrom(rawParameterType)) {
throw parameterError(p, "@PartMap parameter type must be Map.");
}
Type mapType = Utils.getSupertype(type, rawParameterType, Map.class);
if (!(mapType instanceof ParameterizedType)) {
throw parameterError(p, "Map must include generic types (e.g., Map)");
}
ParameterizedType parameterizedType = (ParameterizedType) mapType;
Type keyType = Utils.getParameterUpperBound(0, parameterizedType);
if (String.class != keyType) {
throw parameterError(p, "@PartMap keys must be of type String: " + keyType);
}
Type valueType = Utils.getParameterUpperBound(1, parameterizedType);
if (MultipartBody.Part.class.isAssignableFrom(Utils.getRawType(valueType))) {
throw parameterError(p, "@PartMap values cannot be MultipartBody.Part. "
+ "Use @Part List or a different value type instead.");
}
Converter valueConverter =
retrofit.requestBodyConverter(valueType, annotations, methodAnnotations);
PartMap partMap = (PartMap) annotation;
return new ParameterHandler.PartMap<>(valueConverter, partMap.encoding());
} else if (annotation instanceof Body) {
if (isFormEncoded || isMultipart) {
throw parameterError(p,
"@Body parameters cannot be used with form or multi-part encoding.");
}
if (gotBody) {
throw parameterError(p, "Multiple @Body method annotations found.");
}
Converter converter;
try {
converter = retrofit.requestBodyConverter(type, annotations, methodAnnotations);
} catch (RuntimeException e) {
// Wide exception range because factories are user code.
throw parameterError(e, p, "Unable to create @Body converter for %s", type);
}
gotBody = true;
return new ParameterHandler.Body<>(converter);
}
return null; // Not a Retrofit annotation.找不到該注解
}
static final class Path extends ParameterHandler {
private final String name; //參數(shù)名，占位符
private final Converter valueConverter;
private final boolean encoded; //是否編碼
Path(String name, Converter valueConverter, boolean encoded) {
this.name = checkNotNull(name, "name == null");
this.valueConverter = valueConverter;
this.encoded = encoded;
}
@Override void apply(RequestBuilder builder, T value) throws IOException {
if (value == null) {
throw new IllegalArgumentException(
"Path parameter "" + name + "" value must not be null.");
}
builder.addPathParam(name, valueConverter.convert(value), encoded);
}
}
void addPathParam(String name, String value, boolean encoded) {
if (relativeUrl == null) {
// The relative URL is cleared when the first query parameter is set.
throw new AssertionError();
}
//將占位符”{name}”使用value替換
relativeUrl = relativeUrl.replace("{" + name + "}", canonicalizeForPath(value, encoded));
}
@Query使用場(chǎng)景
@Query用來(lái)修飾接口方法中的查詢字段
static final class Query extends ParameterHandler {
private final String name;
private final Converter valueConverter;
private final boolean encoded;
Query(String name, Converter valueConverter, boolean encoded) {
this.name = checkNotNull(name, "name == null");
this.valueConverter = valueConverter;
this.encoded = encoded;
}
@Override void apply(RequestBuilder builder, T value) throws IOException {
if (value == null) return; // Skip null values.
builder.addQueryParam(name, valueConverter.convert(value), encoded);
}
}
//將查詢參數(shù)組合到相對(duì)路徑上。
void addQueryParam(String name, String value, boolean encoded) {
if (relativeUrl != null) {
// Do a one-time combination of the built relative URL and the base URL.
urlBuilder = baseUrl.newBuilder(relativeUrl);
if (urlBuilder == null) {
throw new IllegalArgumentException(
"Malformed URL. Base: " + baseUrl + ", Relative: " + relativeUrl);
}
relativeUrl = null;
}
if (encoded) {
urlBuilder.addEncodedQueryParameter(name, value);
} else {
urlBuilder.addQueryParameter(name, value);
}
}
static final class Body extends ParameterHandler {
private final Converter converter;
Body(Converter converter) {
this.converter = converter;
}
@Override void apply(RequestBuilder builder, T value) {
if (value == null) {
throw new IllegalArgumentException("Body parameter value must not be null.");
}
RequestBody body;
try {
body = converter.convert(value);
} catch (IOException e) {
throw new RuntimeException("Unable to convert " + value + " to RequestBody", e);
}
builder.setBody(body);
}
}
/** Builds an HTTP request from method arguments. */
Request toRequest(Object... args) throws IOException {
RequestBuilder requestBuilder = new RequestBuilder(httpMethod, baseUrl, relativeUrl, headers,
contentType, hasBody, isFormEncoded, isMultipart);
@SuppressWarnings("unchecked") // It is an error to invoke a method with the wrong arg types.
ParameterHandler
/** Builds an HTTP request from method arguments. */
Request toRequest(Object... args) throws IOException {
RequestBuilder requestBuilder = new RequestBuilder(httpMethod, baseUrl, relativeUrl, headers,
contentType, hasBody, isFormEncoded, isMultipart);
@SuppressWarnings("unchecked") // It is an error to invoke a method with the wrong arg types.
ParameterHandler
