[享学Feign] 四、原生Feign的核心API详解(二)：Contract、SynchronousMethodHandler...

public abstract class Logger {
	
  // 记录日志时，对configKey进行格式化  子类可以复写这种实现，但一般都没必要	
  protected static String methodTag(String configKey) {
    return new StringBuilder().append('[').append(configKey.substring(0, configKey.indexOf('(')))
        .append("] ").toString();
  }
	
	// 它是个protected的抽象方法，子类必须复写。三大参数交给你，子类决定如何书写（写控制台or写文件？）
	// 比如你可以使用System.out，可以用Log4j、SLF4j都可以...
	protected abstract void log(String configKey, String format, Object... args);

	// 记录请求信息。你可以复写，但一般没必要。保持出厂格式吧...
	protected void logRequest(String configKey, Level logLevel, Request request) {
		// 打印请求URL...
		log(configKey, "---> %s %s HTTP/1.1", request.httpMethod().name(), request.url());
		
		// 接下来的内容，只有日志级别在HEADERS以及以上才输出
		// 这是Feign自己的日志级别：NONE,BASIC,HEADERS,FULL
		// 所以只有日志级别为HEADERS,FULL下面才会输出，日志级别是你定的。但默认是NONE
		if (logLevel.ordinal() >= Level.HEADERS.ordinal()) {
			... // 除数请求头、请求体、响应码、响应体等
		}
	}

	// 记录响应信息
	protected Response logAndRebufferResponse(...) { ... }
	// 记录异常信息
	protected IOException logIOException(...){ ... }
}

public interface InvocationHandlerFactory {
	
	// Dispatcher：每个方法对应的MethodHandler -> SynchronousMethodHandler实例
	// 创建出来的是一个FeignInvocationHandler实例，实现了InvocationHandler接口
	InvocationHandler create(Target target, Map<Method, MethodHandler> dispatch);
}

static final class Default implements InvocationHandlerFactory {

	// 很简单：调用FeignInvocationHandler构造器完成实例的创建
    @Override
    public InvocationHandler create(Target target, Map<Method, MethodHandler> dispatch) {
      return new ReflectiveFeign.FeignInvocationHandler(target, dispatch);
    }
  }

static class FeignInvocationHandler implements InvocationHandler {

    private final Target target;
    private final Map<Method, MethodHandler> dispatch;
	...

    @Override
    public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {
      ... //省略对equals、hashCode、toString等方法的处理代码
	
	  // 通过dispath完成调度，因此最终调用的是MethodHandler#invoke
      return dispatch.get(method).invoke(args);
    }
}

public interface Contract {

	// 此方法来解析类中链接到HTTP请求的方法：提取有效信息到元信息存储
	// MethodMetadata：方法各种元信息，包括但不限于
	// 返回值类型returnType
	// 请求参数、请求参数的index、名称
	// url、查询参数、请求body体等等等等
	List<MethodMetadata> parseAndValidatateMetadata(Class<?> targetType);
}

abstract class BaseContract implements Contract {
    @Override
    public List<MethodMetadata> parseAndValidatateMetadata(Class<?> targetType) {
		// 这些检查挺有意思的
		// 1、类上不能存在任何一个泛型变量
		... targetType.getTypeParameters().length == 0
		// 2、接口最多最多只能有一个父接口
		... targetType.getInterfaces().length <= 1
			targetType.getInterfaces()[0].getInterfaces().length == 0

		// 对该类所有的方法进行解析：包装成一个MethodMetadata
		// getMethods表示本类 + 父类的public方法
		// 因为是接口，所有肯定都是public的（当然Java8支持private、default、static等）
		Map<String, MethodMetadata> result = new LinkedHashMap<String, MethodMetadata>();
		for (Method method : targetType.getMethods()) {
			... // 排除掉Object的方法、static方法、default方法等
			
			// parseAndValidateMetadata是本类的一个protected方法
			MethodMetadata metadata = parseAndValidateMetadata(targetType, method);
			// 请注意这个key是：metadata.configKey()
			result.put(metadata.configKey(), metadata);

			// 注意：这里并没有把result直接返回回去
			// 而是返回一个快照版本
			return new ArrayList<>(result.values());
		}
    }
}

BaseContract：

	protected MethodMetadata parseAndValidateMetadata(Class<?> targetType, Method method) {
		MethodMetadata data = new MethodMetadata();
		// 方法返回类型是支持泛型的
		data.returnType(Types.resolve(targetType, targetType, method.getGenericReturnType()));
		// 这里使用了Feign的一个工具方法，来生成configKey，不用过于了解细节，简单的说就是尽量唯一
		data.configKey(Feign.configKey(targetType, method));

	  // 这一步很重要：处理接口上的注解。并且处理了父接口哦
	  // 这就是为何你父接口上的注解，子接口里也生效的原因哦~~~
	  // processAnnotationOnClass()是个abstract方法，交给子类去实现（毕竟注解是可以扩展的嘛）
      if (targetType.getInterfaces().length == 1) {
        processAnnotationOnClass(data, targetType.getInterfaces()[0]);
      }
      processAnnotationOnClass(data, targetType);
	
	  // 处理标注在方法上的所有注解
	  // 若子接口override了父接口的方法，注解请以子接口的为主，忽略父接口方法
      for (Annotation methodAnnotation : method.getAnnotations()) {
        processAnnotationOnMethod(data, methodAnnotation, method);
      }
		// 简单的说：处理完方法上的注解后，必须已经知道到底是GET or POST 或者其它了
	   checkState(data.template().method() != null,


		// 方法参数，支持泛型类型的。如List<String>这种...
      Class<?>[] parameterTypes = method.getParameterTypes();
      Type[] genericParameterTypes = method.getGenericParameterTypes();

	   // 注解是个二维数组...
      Annotation[][] parameterAnnotations = method.getParameterAnnotations();
      int count = parameterAnnotations.length;
      // 一个注解一个注解的处理
      for (int i = 0; i < count; i++) {
		...
		// processAnnotationsOnParameter是抽象方法，子类去决定
        if (parameterAnnotations[i] != null) {
          isHttpAnnotation = processAnnotationsOnParameter(data, parameterAnnotations[i], i);
        }

		// 方法参数若存在URI类型的参数，那url就以它为准，并不使用全局的了
		if (parameterTypes[i] == URI.class) {
			data.urlIndex(i);
		}
		... 
		// 校验body：
		// 1、body参数不能用作form表单的parameters
		// 2、Body parameters不能太多
		
		...
		return data;
      }
		
	}

class Default extends BaseContract {

	static final Pattern REQUEST_LINE_PATTERN = Pattern.compile("^([A-Z]+)[ ]*(.*)$");

	// 支持注解：@Headers
    @Override
    protected void processAnnotationOnClass(MethodMetadata data, Class<?> targetType) { ... }

	// 支出注解：@RequestLine、@Body、@Headers
    @Override
    protected void processAnnotationOnMethod(MethodMetadata data, Annotation methodAnnotation, Method method) { ... }

	// 支持注解：@Param、@QueryMap、@HeaderMap等
    @Override
    protected boolean processAnnotationsOnParameter(MethodMetadata data, Annotation[] annotations, int paramIndex) { ... }
	...
}

interface MethodHandler {
	Object invoke(Object[] argv) throws Throwable;
}

// 访问权限是Default
final class DefaultMethodHandler implements MethodHandler {

	private final MethodHandle unboundHandle;
	private MethodHandle handle;

	// 从Method里拿到方法句柄，赋值给unboundHandle
	public DefaultMethodHandler(Method defaultMethod) { ... }


  // 把目标对象（代理对象）绑定到方法句柄上
  // 这样unboundHandle就变为了已经绑定好的handle，这样invoke就能调用啦
  public void bindTo(Object proxy) {
    if (handle != null) {
      throw new IllegalStateException("Attempted to rebind a default method handler that was already bound");
    }
    handle = unboundHandle.bindTo(proxy);
  }

  // 调用目标方法
  // 调用前：请确保已经绑定了目标对象
  @Override
  public Object invoke(Object[] argv) throws Throwable {
    if (handle == null) {
      throw new IllegalStateException("Default method handler invoked before proxy has been bound.");
    }
    return handle.invokeWithArguments(argv);
  }
}

final class SynchronousMethodHandler implements MethodHandler {
	
	// 方法元信息
	private final MethodMetadata metadata;
	// 目标  也就是最终真正构建Http请求Request的实例 一般为HardCodedTarget
	private final Target<?> target;
	// 负责最终请求的发送 -> 默认传进来的是基于JDK源生的，效率很低，不建议直接使用
	private final Client client;
	// 负责重试 -->默认传进来的是Default，是有重试机制的哦，生产上使用请务必注意
	private final Retryer retryer;

	// 请求拦截器，它会在target.apply(template); 也就是模版 -> 请求的转换之前完成拦截
	// 说明：并不是发送请求之前那一刻哦，请务必注意啦
	// 它的作用只能是对请求模版做定制，而不能再对Request做定制了
	// 内置仅有一个实现：BasicAuthRequestInterceptor 用于鉴权
	private final List<RequestInterceptor> requestInterceptors;

	// 若你想在控制台看到feign的请求日志，改变此日志级别为info吧（因为一般只有info才会输出到日志文件）
	private final Logger.Level logLevel;
	...
	// 构建请求模版的工厂
	// 对于请求模版，有多种构建方式，内部会用到可能多个编码器，下文详解
	private final RequestTemplate.Factory buildTemplateFromArgs;
	// 请求参数：比如链接超时时间、请求超时时间等
	private final Options options;

	// 解码器：用于对Response进行解码
	private final Decoder decoder;
	// 发生错误/异常时的解码器
	private final ErrorDecoder errorDecoder;

	// 是否解码404状态码？默认是不解码的
	private final boolean decode404;
	
	// 唯一的构造器，并且还是私有的（所以肯定只能在本类内构建出它的实例喽）
	// 完成了对如上所有属性的赋值
	private SynchronousMethodHandler( ... ) { ... }

  	@Override
  	public Object invoke(Object[] argv) throws Throwable {
  		// 根据方法入参，结合工厂构建出一个请求模版
		RequestTemplate template = buildTemplateFromArgs.create(argv);
		// findOptions()：如果你方法入参里含有Options类型这里会被找出来
		// 说明：若有多个只会有第一个生效（不会报错）
		Options options = findOptions(argv);
		// 重试机制：注意这里是克隆一个来使用
		Retryer retryer = this.retryer.clone();
		while (true) {
		     try {
		        return executeAndDecode(template, options);
		      } catch (RetryableException e) {
				
				// 若抛出异常，那就触发重试逻辑
		       try {
		       	  // 该逻辑是：如果不重试了，该异常会继续抛出
		       	  // 若要充值，就会走下面的continue
		          retryer.continueOrPropagate(e);
		        } catch (RetryableException th) {
		        	...
		        }
		        continue;
		      }
		}
  	}
}