[享学Feign] 七、请求模版对象RequestTemplate和标准请求对象feign.Request

@SuppressWarnings({"WeakerAccess", "UnusedReturnValue"})
public final class RequestTemplate implements Serializable {

	// 查询参数：key是name，QueryTemplate表示遵循rfc6570规范的模版
	private final Map<String, QueryTemplate> queries = new LinkedHashMap<>();
	private final Map<String, HeaderTemplate> headers = new TreeMap<>(String.CASE_INSENSITIVE_ORDER);
	private UriTemplate uriTemplate;

	// 注意：此处target表示的是最终准备请求的URL，并非feign.Target
	private String target;
	// 拼接在url后面的片段，一般表示锚点。如#bootmark
	private String fragment;
	
	// mark the new template resolved
	private boolean resolved = false;

	private HttpMethod method;
	// 请注意：这里使用的更加通用的UTF-8编码
	private transient Charset charset = Util.UTF_8;
	// 请求Body体 内包含bodyTemplate字符串
	private Request.Body body = Request.Body.empty();
	
	// 这两个属性就不解释了
	private boolean decodeSlash = true;
	private CollectionFormat collectionFormat = CollectionFormat.EXPLODED;

}

RequestTemplate：

  // 构造器：空构造是它唯一非@Deprecated的public构造器，但一般不用它来构建实例
  // 此构造器唯一调用处：`MethodMetadata`
  public RequestTemplate() {
    super();
  }

  // 将自己转换为标准的Request对象
  // 转换之前：请确保所有的template模版都已经被解析过了  resolved = true
  public Request request() {
    if (!this.resolved) {
      throw new IllegalStateException("template has not been resolved.");
    }
    return Request.create(this.method, this.url(), this.headers(), this.requestBody());
  }

  // 给请求模版指定Http方法
  public RequestTemplate method(HttpMethod method) {
    checkNotNull(method, "method");
    this.method = method;
    return this;
  }

  // 这个方法最特别的地方在于：给uriTemplate进行了重新赋值->把编码后的结果赋值给它
  public RequestTemplate decodeSlash(boolean decodeSlash) {
    this.decodeSlash = decodeSlash;
    this.uriTemplate =
        UriTemplate.create(this.uriTemplate.toString(), !this.decodeSlash, this.charset);
    return this;
  }


  // 该方法作用：给request设置一个uri
  // 这里会解析UriTemplate，并且拼接好所有的部分（包括查询参数、锚点等，但domain此处不管哦~)
  public RequestTemplate uri(String uri) { ... }
  public RequestTemplate uri(String uri, boolean append) { ... }
  public String url() { ... }
  public String path() { ... }

  // 它是组装所有的所有的所有的部分，拼接成一个完成的URL
  // 形如：http://www.baidu.com/aaa/bbb?name=YourBatman#mark
  public RequestTemplate target(String target) { ... }
	
  // 获取所有template的所有参数名称们，也就是key们	
  public List<String> variables() { ... }

  // Body Template to resolve.
  public String bodyTemplate() {
    return body.bodyTemplate();
  }
  // 查询参数
  public String queryLine() { ... }

RequestTemplate：

  // 使用提供的变量值替换解析所有表达式。
  // 注意：变量值是一份，所有的模版都会解析哦
  public RequestTemplate resolve(Map<String, ?> variables) {
		StringBuilder uri = new StringBuilder();
		
		// 特别注意：在基础上赋值一份出来，所以操作的是这份新的，return出去的也是新的哦
		RequestTemplate resolved = RequestTemplate.from(this);

		... //1、解析uriTemplate，·uriTemplate.expand(variables)·
	
		// 2、解析查询参数模版，这块相对复杂。用&连接起来
		if (!this.queries.isEmpty()) {
		
			// 先处理模版：一个模版一个模版的处理
			Iterator<QueryTemplate> queryTemplates = this.queries.values().iterator();
			while (queryTemplates.hasNext()) {
				...
				String queryExpanded = queryTemplate.expand(variables);
				...
				query.append("&"); 
			}
			...
			// 设值查询参数
			resolved.uri(uri.toString());

			//再处理请求头模版
			if (!this.headers.isEmpty()) {
				for (HeaderTemplate headerTemplate : this.headers.values()) {
					...
					String headerValues = header.substring(header.indexOf(" ") + 1);
					...
				}
			}

			// 处理body模版
			// 说明：body里持有BodyTemplate的引用，所以底层依旧是bodyTemplate.expand(variables)
			resolved.body(this.body.expand(variables));
			
			// 标志位：标记为已处理
			resolved.resolved = true;
			return resolved;
		}
		
  }

interface Factory {
   RequestTemplate create(Object[] argv);
}

private static class BuildTemplateByResolvingArgs implements RequestTemplate.Factory {

	private final QueryMapEncoder queryMapEncoder;
	protected final MethodMetadata metadata;
	
	// 这里的Expander指的是feign.Param.Expander，也就是由注解决定使用哪种Expander，默认是ToStringExpander
	// 这里的key 数字类型：表示参数的index...
	private final Map<Integer, Expander> indexToExpander = new LinkedHashMap<Integer, Expander>();

	// 唯一构造器：给前两个属性赋值。并且并且并且根据这两个属性
	// 计算出indexToExpander的值，然后存储着
	private BuildTemplateByResolvingArgs(MethodMetadata metadata, QueryMapEncoder queryMapEncoder) {
      this.metadata = metadata;
      this.queryMapEncoder = queryMapEncoder;

	  // 计算
	  ...
	  for (Entry<Integer, Class<? extends Expander>> indexToExpanderClass : metadata.indexToExpanderClass().entrySet()) {
	  		...
	  		indexToExpander.put(indexToExpanderClass.getKey(), indexToExpanderClass.getValue().newInstance());
	  		...
	  }
	}
}

BuildTemplateByResolvingArgs：

    @Override
    public RequestTemplate create(Object[] argv) {
    	// 同样的，先拷贝一份出来RequestTemplate出来，但这并不是最终return的
		RequestTemplate mutable = RequestTemplate.from(metadata.template());

		// varBuilder装载所有的k-v
		Map<String, Object> varBuilder = new LinkedHashMap<String, Object>();
		for (Entry<Integer, Collection<String>> entry : metadata.indexToName().entrySet()) {
			int i = entry.getKey();
			Object value = argv[i];
			if (value != null) {
				...
				for (String name : entry.getValue()) {
					varBuilder.put(name, value);
				}
			}
		}

		// 调用RequestTemplate#resolve()方法，得到一个全新的实例
		RequestTemplate template = resolve(argv, mutable, varBuilder);
		// 支持@QueryMap
		if (metadata.queryMapIndex() != null) {
			...
		}
		// 支持@HeaderMap
		if (metadata.headerMapIndex() != null) {
			...
		}
		return template;
    }

	// 本类默认实现，直接嗲用RequestTemplate填充模版
	// 两个子类对此方法均由复写...
    protected RequestTemplate resolve(Object[] argv,
                                      RequestTemplate mutable,
                                      Map<String, Object> variables) {
      return mutable.resolve(variables);
    }

private static class BuildEncodedTemplateFromArgs extends BuildTemplateByResolvingArgs {

    private final Encoder encoder;
    ... // 省略构造器

	// 复写父类的resolve()解析方法，让解码器参与进来
    @Override
    protected RequestTemplate resolve(Object[] argv,
                                      RequestTemplate mutable,
                                      Map<String, Object> variables) {
      Object body = argv[metadata.bodyIndex()];
      checkArgument(body != null, "Body parameter %s was null", metadata.bodyIndex());
      	...
		encoder.encode(body, metadata.bodyType(), mutable);
		...
	}

}

public final class Request {

  // 这些参数很容易理解：它就是Http请求的各个部分
  private final HttpMethod httpMethod;
  private final String url;
  private final Map<String, Collection<String>> headers;
  private final Body body;
  ... // 省略构造器。构造器是私有的，并不能直接构造实例对象，而是提供了静态方法

	// 获取编码 -> 来自于body
  public Charset charset() {
    return body.encoding;
  }
  // body的二进制表示形式 --> 通用
  public byte[] body() {
    return body.data;
  }
  ... // 省略其它get方法（并没有set方法哦~~~）
}

Request：

  // 特点：method使用字符串，body使用二进制 + 编码的方式
  // Body.encoded(body, charset)可以把二进制 + 编码 转换为一个Body对象
  // 所以这个构造器是面向用户良好的创建方法，因此使用也较多
  public static Request create(String method,
                               String url,
                               Map<String, Collection<String>> headers,
                               byte[] body,
                               Charset charset) {
    checkNotNull(method, "httpMethod of %s", method);
    HttpMethod httpMethod = HttpMethod.valueOf(method.toUpperCase());
    return create(httpMethod, url, headers, body, charset);
  }
  ...
  // 最终调用都是Request唯一的构造器：new Request(httpMethod, url, headers, body);

	// Http标准方法的枚举
  public enum HttpMethod {
    GET, HEAD, POST, PUT, DELETE, CONNECT, OPTIONS, TRACE, PATCH
  }
  // 发送请求的选项：链接超时（默认10s），读取超时（默认60秒）
  public static class Options {
    private final int connectTimeoutMillis;
    private final int readTimeoutMillis;
    private final boolean followRedirects;
    ...
  }

public static class Body {

	// 数据用字节数组表述，可以表示任意类型，最为通用
    private final byte[] data;
    private final Charset encoding;

	// 但是请注意：body内容可能来自于模版，这是需要区分的一点
	// 很显然，bodyTemplate是可以为null的
    private final BodyTemplate bodyTemplate;

	... // 省略私有构造器

	// 根据variables，经过BodyTemplate产生一个新的Body对象
	// 这是根据模版构建Body的一种方式：使用较多
    public Request.Body expand(Map<String, ?> variables) {
      if (bodyTemplate == null)
        return this;
      return encoded(bodyTemplate.expand(variables).getBytes(encoding), encoding);
    }
    // 直接传值构建：静态方法
    public static Request.Body encoded(byte[] bodyData, Charset encoding) {
      return new Request.Body(bodyData, encoding, null);
    }
    // 静态方法：空消息体  data为null 编码类型为null...
    public static Body empty() {
      return new Request.Body(null, null, null);
    }

	...
	// 获取body的二进制表示形式。注意：方法名不叫getBytes
    public byte[] asBytes() {
      return data;
    }
    // 转为String的前提条件：data和encoding都不能为null
    public String asString() {
      return (encoding != null && data != null) ? new String(data, encoding) : "Binary data";
    }

    public int length() {
      return data != null ? data.length : 0;
    }
    // 拿到Body的模版（可能为null）
    public String bodyTemplate() {
      return (bodyTemplate != null) ? bodyTemplate.toString() : null;
    }
}