Spring GenericConversionService

/**
 * General NO-OP converter used when conversion is not required.
 * 没有操作的 convert
 */
private static final GenericConverter NO_OP_CONVERTER = new NoOpConverter("NO_OP");

/**
 * Used as a cache entry when no converter is available.
 * This converter is never returned.
 * 没有操作的 convert
 */
private static final GenericConverter NO_MATCH = new NoOpConverter("NO_MATCH");


/**
 * 转换器集合
 */
private final Converters converters = new Converters();

/**
 * 转换器缓存
 * key: 转换器缓存key
 * value: 转换器
 */
private final Map<ConverterCacheKey, GenericConverter> converterCache = new ConcurrentReferenceHashMap<>(64);

/**
 * 转换器接口
 */
private final Set<GenericConverter> globalConverters = new LinkedHashSet<>();

/**
 * 转换器映射
 */
private final Map<ConvertiblePair, ConvertersForPair> converters = new LinkedHashMap<>(36);

public void add(GenericConverter converter) {
   // 获取转换对象 ConvertiblePair
   Set<ConvertiblePair> convertibleTypes = converter.getConvertibleTypes();
   // 判空
   if (convertibleTypes == null) {
      Assert.state(converter instanceof ConditionalConverter,
            "Only conditional converters may return null convertible types");
      this.globalConverters.add(converter);
   }
   else {
      for (ConvertiblePair convertiblePair : convertibleTypes) {
         // 获取 ConvertersForPair对象
         ConvertersForPair convertersForPair = getMatchableConverters(convertiblePair);
         convertersForPair.add(converter);
      }
   }
}

private ConvertersForPair getMatchableConverters(ConvertiblePair convertiblePair) {
   // 缓存中获取
   ConvertersForPair convertersForPair = this.converters.get(convertiblePair);
   if (convertersForPair == null) {
      // 创建一个空对象
      convertersForPair = new ConvertersForPair();
      this.converters.put(convertiblePair, convertersForPair);
   }
   return convertersForPair;
}

@Nullable
public GenericConverter find(TypeDescriptor sourceType, TypeDescriptor targetType) {
   // Search the full type hierarchy
   // 找到 source 类型的类关系和接口关系
   List<Class<?>> sourceCandidates = getClassHierarchy(sourceType.getType());
   // 找到 target 类型的类关系和接口关系
   List<Class<?>> targetCandidates = getClassHierarchy(targetType.getType());
   // 循环 source 的类列表 和 target 的类列表
   for (Class<?> sourceCandidate : sourceCandidates) {
      for (Class<?> targetCandidate : targetCandidates) {
         // 创建 ConvertiblePair 对象
         ConvertiblePair convertiblePair = new ConvertiblePair(sourceCandidate, targetCandidate);
         // 获取 source + target 的转换接口
         GenericConverter converter = getRegisteredConverter(sourceType, targetType, convertiblePair);
         if (converter != null) {
            return converter;
         }
      }
   }
   return null;
}

private List<Class<?>> getClassHierarchy(Class<?> type) {
   // 层级关系列表
   List<Class<?>> hierarchy = new ArrayList<>(20);
   // 访问列表
   Set<Class<?>> visited = new HashSet<>(20);
   // 在第0个添加 type
   addToClassHierarchy(0, ClassUtils.resolvePrimitiveIfNecessary(type), false, hierarchy, visited);
   // type 是否是 array
   boolean array = type.isArray();

   int i = 0;
   while (i < hierarchy.size()) {
      Class<?> candidate = hierarchy.get(i);
      candidate = (array ? candidate.getComponentType() : ClassUtils.resolvePrimitiveIfNecessary(candidate));
      // 父类
      Class<?> superclass = candidate.getSuperclass();
      if (superclass != null && superclass != Object.class && superclass != Enum.class) {
         // 当前索引位置+1 设置父类
         addToClassHierarchy(i + 1, candidate.getSuperclass(), array, hierarchy, visited);
      }
      // 添加接口类型
      addInterfacesToClassHierarchy(candidate, array, hierarchy, visited);
      i++;
   }

   // 判断是否 enum
   if (Enum.class.isAssignableFrom(type)) {
      // 添加
      addToClassHierarchy(hierarchy.size(), Enum.class, array, hierarchy, visited);
      addToClassHierarchy(hierarchy.size(), Enum.class, false, hierarchy, visited);
      addInterfacesToClassHierarchy(Enum.class, array, hierarchy, visited);
   }

   // 添加
   addToClassHierarchy(hierarchy.size(), Object.class, array, hierarchy, visited);
   addToClassHierarchy(hierarchy.size(), Object.class, false, hierarchy, visited);
   return hierarchy;
}

private void addInterfacesToClassHierarchy(Class<?> type, boolean asArray,
      List<Class<?>> hierarchy, Set<Class<?>> visited) {

   // 获取类的接口列表
   for (Class<?> implementedInterface : type.getInterfaces()) {
      // 添加元素
      addToClassHierarchy(hierarchy.size(), implementedInterface, asArray, hierarchy, visited);
   }
}

/**
 * 在指定索引位置添加 class
 */
private void addToClassHierarchy(int index, Class<?> type, boolean asArray,
      List<Class<?>> hierarchy, Set<Class<?>> visited) {

   // 是否 array
   if (asArray) {
      // type 如果是array 直接创建空数组
      type = Array.newInstance(type, 0).getClass();
   }
   // 向访问者列表添加类型,判断是否成功
   if (visited.add(type)) {
      // 成功添加后放入具体位置
      hierarchy.add(index, type);
   }
}

@Nullable
private GenericConverter getRegisteredConverter(TypeDescriptor sourceType,
      TypeDescriptor targetType, ConvertiblePair convertiblePair) {

   // Check specifically registered converters
   // 从map中获取
   ConvertersForPair convertersForPair = this.converters.get(convertiblePair);
   if (convertersForPair != null) {
      // 获取 GenericConverter
      GenericConverter converter = convertersForPair.getConverter(sourceType, targetType);
      if (converter != null) {
         return converter;
      }
   }
   // Check ConditionalConverters for a dynamic match
   for (GenericConverter globalConverter : this.globalConverters) {
      if (((ConditionalConverter) globalConverter).matches(sourceType, targetType)) {
         return globalConverter;
      }
   }
   return null;
}

@Override
public void addConverter(Converter<?, ?> converter) {
   // 获取解析类型
   ResolvableType[] typeInfo = getRequiredTypeInfo(converter.getClass(), Converter.class);
   if (typeInfo == null && converter instanceof DecoratingProxy) {
      typeInfo = getRequiredTypeInfo(((DecoratingProxy) converter).getDecoratedClass(), Converter.class);
   }
   if (typeInfo == null) {
      throw new IllegalArgumentException("Unable to determine source type <S> and target type <T> for your " +
            "Converter [" + converter.getClass().getName() + "]; does the class parameterize those types?");
   }
   // 添加 converter
   addConverter(new ConverterAdapter(converter, typeInfo[0], typeInfo[1]));
}

@Override
public void addConverterFactory(ConverterFactory<?, ?> factory) {
   // 获取类型信息
   ResolvableType[] typeInfo = getRequiredTypeInfo(factory.getClass(), ConverterFactory.class);
   // 判断 factory 是不是DecoratingProxy
   if (typeInfo == null && factory instanceof DecoratingProxy) {
      // 其中 DecoratingProxy 可以获取 class
      typeInfo = getRequiredTypeInfo(((DecoratingProxy) factory).getDecoratedClass(), ConverterFactory.class);
   }
   if (typeInfo == null) {
      throw new IllegalArgumentException("Unable to determine source type <S> and target type <T> for your " +
            "ConverterFactory [" + factory.getClass().getName() + "]; does the class parameterize those types?");
   }
   // 添加转换器
   addConverter(new ConverterFactoryAdapter(factory,
         new ConvertiblePair(typeInfo[0].toClass(), typeInfo[1].toClass())));
}

@Override
public boolean canConvert(@Nullable TypeDescriptor sourceType, TypeDescriptor targetType) {
   Assert.notNull(targetType, "Target type to convert to cannot be null");
   if (sourceType == null) {
      return true;
   }
   // 获取 convert , 如果获取到了就是可以转换
   GenericConverter converter = getConverter(sourceType, targetType);
   return (converter != null);
}

@Nullable
private ResolvableType[] getRequiredTypeInfo(Class<?> converterClass, Class<?> genericIfc) {

   // 1. 通过class转换两次得到 ResolvableType
   ResolvableType resolvableType = ResolvableType.forClass(converterClass).as(genericIfc);
   // 2. 获取所有的 ResolvableType
   ResolvableType[] generics = resolvableType.getGenerics();
   if (generics.length < 2) {
      return null;
   }
   // 3. 数据校验准备
   Class<?> sourceType = generics[0].resolve();
   Class<?> targetType = generics[1].resolve();
   if (sourceType == null || targetType == null) {
      return null;
   }
   return generics;
}

@Nullable
protected GenericConverter getConverter(TypeDescriptor sourceType, TypeDescriptor targetType) {
   ConverterCacheKey key = new ConverterCacheKey(sourceType, targetType);
   GenericConverter converter = this.converterCache.get(key);
   if (converter != null) {
      return (converter != NO_MATCH ? converter : null);
   }

   // 找出 converter 对象
   converter = this.converters.find(sourceType, targetType);
   if (converter == null) {
      // 获取默认的 converter
      converter = getDefaultConverter(sourceType, targetType);
   }

   if (converter != null) {
      // 设置缓存
      this.converterCache.put(key, converter);
      return converter;
   }
   // 设置缓存
   this.converterCache.put(key, NO_MATCH);
   return null;
}

@Override
@Nullable
public Object convert(@Nullable Object source, @Nullable TypeDescriptor sourceType, TypeDescriptor targetType) {
   Assert.notNull(targetType, "Target type to convert to cannot be null");
   if (sourceType == null) {
      Assert.isTrue(source == null, "Source must be [null] if source type == [null]");
      // 处理 sourceType 为空的转换
      return handleResult(null, targetType, convertNullSource(null, targetType));
   }
   // 数据验证
   if (source != null && !sourceType.getObjectType().isInstance(source)) {
      throw new IllegalArgumentException("Source to convert from must be an instance of [" +
            sourceType + "]; instead it was a [" + source.getClass().getName() + "]");
   }
   // 获取转换器接口
   GenericConverter converter = getConverter(sourceType, targetType);
   if (converter != null) {
      // 通过工具获得转换结果
      Object result = ConversionUtils.invokeConverter(converter, source, sourceType, targetType);
      return handleResult(sourceType, targetType, result);
   }
   // 处理找不到 convert 的转换结果
   return handleConverterNotFound(source, sourceType, targetType);
}

@Nullable
private Object handleResult(@Nullable TypeDescriptor sourceType, TypeDescriptor targetType, @Nullable Object result) {
   if (result == null) {
      // 判断 target type
      assertNotPrimitiveTargetType(sourceType, targetType);
   }
   return result;
}

if (sourceType == null) {
   Assert.isTrue(source == null, "Source must be [null] if source type == [null]");
   // 处理 sourceType 为空的转换
   return handleResult(null, targetType, convertNullSource(null, targetType));
}

@Nullable
protected Object convertNullSource(@Nullable TypeDescriptor sourceType, TypeDescriptor targetType) {
   if (targetType.getObjectType() == Optional.class) {
      return Optional.empty();
   }
   return null;
}

@Nullable
private Object handleConverterNotFound(
      @Nullable Object source, @Nullable TypeDescriptor sourceType, TypeDescriptor targetType) {

   if (source == null) {
      assertNotPrimitiveTargetType(sourceType, targetType);
      return null;
   }
   if ((sourceType == null || sourceType.isAssignableTo(targetType)) &&
         targetType.getObjectType().isInstance(source)) {
      return source;
   }
   throw new ConverterNotFoundException(sourceType, targetType);
}

private static class ConvertersForPair {

   /**
    * 转换器列表
    */
   private final LinkedList<GenericConverter> converters = new LinkedList<>();

   /**
    * 添加转换器
    * @param converter
    */
   public void add(GenericConverter converter) {
      this.converters.addFirst(converter);
   }

   /**
    * 获取转换器
    * @param sourceType 原类型描述
    * @param targetType 目标类型描述
    * @return
    */
   @Nullable
   public GenericConverter getConverter(TypeDescriptor sourceType, TypeDescriptor targetType) {
      for (GenericConverter converter : this.converters) {
         // 判断是否匹配
         if (!(converter instanceof ConditionalGenericConverter) ||
               ((ConditionalGenericConverter) converter).matches(sourceType, targetType)) {
            return converter;
         }
      }
      return null;
   }

   @Override
   public String toString() {
      return StringUtils.collectionToCommaDelimitedString(this.converters);
   }
}

/**
 * 转换器对象
 */
private final Converter<Object, Object> converter;

/**
 * 元对象和目标对象.
 */
private final ConvertiblePair typeInfo;

/**
 * 解析类型
 */
private final ResolvableType targetType;

@Override
public boolean matches(TypeDescriptor sourceType, TypeDescriptor targetType) {
   // Check raw type first...
   // 判断类型是否一致
   if (this.typeInfo.getTargetType() != targetType.getObjectType()) {
      return false;
   }
   // Full check for complex generic type match required?
   ResolvableType rt = targetType.getResolvableType();
   if (!(rt.getType() instanceof Class) && !rt.isAssignableFrom(this.targetType) &&
         !this.targetType.hasUnresolvableGenerics()) {
      return false;
   }
   // 从 converter 判断是否可以转换
   return !(this.converter instanceof ConditionalConverter) ||
         ((ConditionalConverter) this.converter).matches(sourceType, targetType);
}

/**
 * convert 工厂
 */
private final ConverterFactory<Object, Object> converterFactory;

/**
 * 源对象和目标对象
 */
private final ConvertiblePair typeInfo;

@Override
public boolean matches(TypeDescriptor sourceType, TypeDescriptor targetType) {
   boolean matches = true;
   if (this.converterFactory instanceof ConditionalConverter) {
      // 是否 matches
      matches = ((ConditionalConverter) this.converterFactory).matches(sourceType, targetType);
   }
   if (matches) {
      // 获取 converter 接口
      Converter<?, ?> converter = this.converterFactory.getConverter(targetType.getType());
      // 类型判断
      if (converter instanceof ConditionalConverter) {
         // 判断是否匹配
         matches = ((ConditionalConverter) converter).matches(sourceType, targetType);
      }
   }
   return matches;
}

@Override
@Nullable
public Object convert(@Nullable Object source, TypeDescriptor sourceType, TypeDescriptor targetType) {
   if (source == null) {
      return convertNullSource(sourceType, targetType);
   }
   // 从工厂中获取一个 convert 接口进行转换
   return this.converterFactory.getConverter(targetType.getObjectType()).convert(source);
}

/**
 * source 的类型描述
 */
private final TypeDescriptor sourceType;

/**
 * target 的类型描述
 */
private final TypeDescriptor targetType;