LinsirType 类型系统封装与扩展详细设计

文档编号: LINSIR-DESIGN-001
版本: 1.0
日期: 2026-03-24
作者: Linsir Framework Team

1. 封装设计引言

1.1 封装目标

LinsirType 的封装目标是简化 Spring Framework ResolvableType 的使用，提供更简洁、类型安全的 API。

1.2 Spring ResolvableType 使用痛点分析

痛点	说明	示例
API链过长	需要多次调用才能获取结果	`forClass().as().getGeneric().resolve()`
类型不安全	返回Class<?>需要强制转换	`@SuppressWarnings("unchecked")`
NONE处理	需要判断NONE返回值	`if (type == ResolvableType.NONE)`
异常处理	各种反射异常需要捕获	`NoSuchFieldException`, `NoSuchMethodException`
缓存缺失	每次解析都重新计算	无内置缓存机制

1.3 封装设计原则

原则	说明	应用
简化API	一行代码完成类型解析	提供静态工具方法
类型安全	使用泛型方法避免强制转换	`<T> Class<T> resolveGeneric(...)`
容错处理	统一异常处理，提供默认值	返回null或默认值而非抛出异常
性能优化	内置多级缓存	热点缓存+软引用缓存
统一入口	门面模式设计	LinsirType作为唯一入口

2. 主要使用场景分析

2.1 场景1：类泛型解析（Service<T>实现类）

场景描述：解析实现类继承泛型接口时的实际类型参数。

示例代码：

java

interface Service<T, ID> {
    T findById(ID id);
}

class UserService implements Service<User, Long> {
    // 实现代码
}

封装前代码：

java

ResolvableType type = ResolvableType.forClass(UserService.class);
ResolvableType baseService = type.as(Service.class);
Class<?> entityClass = baseService.getGeneric(0).resolve();
Class<?> idClass = baseService.getGeneric(1).resolve();

封装后代码：

java

Class<User> entityClass = LinsirType.resolveGeneric(
    UserService.class, Service.class, 0);
Class<Long> idClass = LinsirType.resolveGeneric(
    UserService.class, Service.class, 1);

设计要点：

使用泛型方法 <T> Class<T> 避免强制转换
内部处理 ResolvableType.NONE 情况
缓存解析结果提升性能

2.2 场景2：字段泛型解析（List<String>字段）

场景描述：解析类字段声明的泛型类型。

示例代码：

java

class Config {
    private List<String> names;
    private Map<String, Integer> settings;
}

封装前代码：

java

Field field = Config.class.getDeclaredField("names");
ResolvableType fieldType = ResolvableType.forField(field);
Class<?> elementType = fieldType.getGeneric(0).resolve();

封装后代码：

java

Class<String> elementType = LinsirType.resolveFieldGeneric(
    Config.class, "names", 0);

// 批量解析
Map<String, Class<?>[]> generics = LinsirType.resolveFieldGenerics(
    Config.class, "names", "settings");

设计要点：

封装反射获取Field的异常处理
提供批量解析方法减少反射调用
支持嵌套泛型解析

2.3 场景3：方法参数解析（Controller方法参数）

场景描述：解析Controller方法参数的泛型类型，支持重载方法。

示例代码：

java

@RestController
public class UserController {
    public void saveUsers(List<User> users) {}
    public void saveUsers(List<User> users, Map<String, Object> metadata) {}
}

封装前代码：

java

Method method = UserController.class.getMethod("saveUsers", List.class);
ResolvableType paramType = ResolvableType.forMethodParameter(method, 0);
Class<?> genericType = paramType.getGeneric(0).resolve();

封装后代码：

java

// 无重载
Class<User> userClass = LinsirType.resolveParameterGeneric(
    UserController.class, "saveUsers", 0, 0);

// 有重载
Class<User> userClass = LinsirType.resolveParameterGeneric(
    UserController.class, "saveUsers",
    new Class<?>[]{List.class}, 0, 0);

设计要点：

支持方法重载解析
封装方法查找逻辑
处理参数索引边界

2.4 场景4：方法返回类型解析（Repository方法）

场景描述：解析Repository方法返回类型的泛型信息。

示例代码：

java

interface Repository<T> {
    List<T> findAll();
    Optional<T> findById(Long id);
}

class UserRepository implements Repository<User> {
    public List<User> findAll() { return null; }
    public Optional<User> findById(Long id) { return null; }
}

封装后代码：

java

Class<User> userClass = LinsirType.resolveReturnTypeGeneric(
    UserRepository.class, "findAll", 0);

Class<User> userClass2 = LinsirType.resolveReturnTypeGeneric(
    UserRepository.class, "findById", new Class<?>[]{Long.class}, 0);

设计要点：

考虑类继承关系中的泛型替换
支持Optional等包装类型解析

2.5 场景5：嵌套泛型解析（Map<String, List<Integer>>）

场景描述：解析多级嵌套泛型。

示例代码：

java

class Processor {
    private Map<String, List<Integer>> data;
}

封装后代码：

java

// 解析 Map<String, List<Integer>> 中的 Integer
Class<Integer> integerClass = LinsirType.resolveNestedGeneric(
    Processor.class, "data", 1, 0);
// 1 = Map的第二个泛型参数(List<Integer>)
// 0 = List的第一个泛型参数(Integer)

设计要点：

支持可变参数索引
逐级解析嵌套类型
处理解析失败情况

2.6 场景6：类型检查与转换

场景描述：检查类型兼容性，支持数组、泛型、通配符等复杂类型。

封装后代码：

java

// 类型兼容性检查
boolean isCompatible = LinsirType.isAssignableFrom(
    List.class, ArrayList.class);  // true

// 接口实现检查
boolean implementsInterface = LinsirType.implementsInterface(
    UserService.class, Service.class);  // true

// 数组处理
Class<String> componentType = LinsirType.getArrayComponentType(
    String[].class);  // String.class
int dimensions = LinsirType.getArrayDimensions(
    String[][].class);  // 2

设计要点：

提供直观的类型检查方法
支持数组维度获取
统一类型兼容性判断逻辑

2.7 场景7：Lambda类型解析

场景描述：解析Lambda表达式的目标类型。

示例代码：

java

Consumer<String> consumer = s -> System.out.println(s);

设计要点：

使用SerializedLambda获取函数接口类型
解析泛型参数类型

2.8 场景8：Record类型支持

场景描述：支持Java 14+ Record类型的组件解析。

示例代码：

java

public record User(String name, Integer age) {}

设计要点：

使用反射获取Record组件
解析组件类型信息

3. 封装架构设计

3.1 门面模式设计（LinsirType）

门面类职责：

提供统一的静态API入口
委托给具体的解析器实现
处理缓存和异常
屏蔽内部实现细节

3.2 策略模式设计（TypeResolver体系）

策略模式优势：

每种解析逻辑独立封装
易于扩展新的解析类型
便于单元测试

3.3 缓存设计（两级缓存）

缓存设计要点：

热点缓存：固定容量，LRU淘汰
软引用缓存：无容量限制，内存不足时GC回收
缓存键设计：Type + Context组合

3.4 异常统一封装

异常设计原则：

统一包装为运行时异常
提供清晰的错误信息
保留原始异常便于调试

4. 封装API详细设计

4.1 类泛型解析API

java

/**
 * 解析类的单个泛型参数
 * 
 * @param clazz 要解析的类
 * @param genericInterface 泛型接口或父类
 * @param index 泛型参数索引（从0开始）
 * @return 解析后的Class，如果无法解析返回null
 * @throws LinsirTypeException 参数校验失败时抛出
 */
public static <T> Class<T> resolveGeneric(
        Class<?> clazz, 
        Class<?> genericInterface, 
        int index);

/**
 * 解析类的所有泛型参数
 * 
 * @param clazz 要解析的类
 * @param genericInterface 泛型接口或父类
 * @return 泛型参数数组，如果无法解析返回空数组
 */
public static Class<?>[] resolveGenerics(
        Class<?> clazz, 
        Class<?> genericInterface);

/**
 * 解析类的指定泛型参数（带默认值）
 * 
 * @param clazz 要解析的类
 * @param genericInterface 泛型接口或父类
 * @param index 泛型参数索引
 * @param defaultValue 默认值
 * @return 解析后的Class，如果无法解析返回默认值
 */
public static <T> Class<T> resolveGeneric(
        Class<?> clazz, 
        Class<?> genericInterface, 
        int index,
        Class<T> defaultValue);

4.2 字段泛型解析API

java

/**
 * 解析字段的单个泛型参数
 * 
 * @param clazz 声明字段的类
 * @param fieldName 字段名
 * @param index 泛型参数索引
 * @return 解析后的Class
 * @throws LinsirTypeException 字段不存在或解析失败时抛出
 */
public static <T> Class<T> resolveFieldGeneric(
        Class<?> clazz, 
        String fieldName, 
        int index);

/**
 * 解析字段的所有泛型参数
 * 
 * @param clazz 声明字段的类
 * @param fieldName 字段名
 * @return 泛型参数数组
 */
public static Class<?>[] resolveFieldGenerics(
        Class<?> clazz, 
        String fieldName);

/**
 * 批量解析多个字段的泛型参数
 * 
 * @param clazz 声明字段的类
 * @param fieldNames 字段名数组
 * @return 字段名到泛型参数数组的映射
 */
public static Map<String, Class<?>[]> resolveFieldGenerics(
        Class<?> clazz, 
        String... fieldNames);

4.3 方法参数解析API

java

/**
 * 解析方法参数的泛型类型
 * 
 * @param clazz 声明方法的类
 * @param methodName 方法名
 * @param parameterIndex 参数索引
 * @param genericIndex 泛型参数索引
 * @return 解析后的Class
 */
public static <T> Class<T> resolveParameterGeneric(
        Class<?> clazz,
        String methodName,
        int parameterIndex,
        int genericIndex);

/**
 * 解析方法参数泛型（支持重载）
 * 
 * @param clazz 声明方法的类
 * @param methodName 方法名
 * @param parameterTypes 方法参数类型（用于匹配重载）
 * @param parameterIndex 参数索引
 * @param genericIndex 泛型参数索引
 * @return 解析后的Class
 */
public static <T> Class<T> resolveParameterGeneric(
        Class<?> clazz,
        String methodName,
        Class<?>[] parameterTypes,
        int parameterIndex,
        int genericIndex);

4.4 方法返回类型解析API

java

/**
 * 解析方法返回类型的泛型
 * 
 * @param clazz 实现类
 * @param methodName 方法名
 * @param index 泛型参数索引
 * @return 解析后的Class
 */
public static <T> Class<T> resolveReturnTypeGeneric(
        Class<?> clazz, 
        String methodName, 
        int index);

/**
 * 解析方法返回类型泛型（支持重载）
 */
public static <T> Class<T> resolveReturnTypeGeneric(
        Class<?> clazz, 
        String methodName,
        Class<?>[] parameterTypes,
        int index);

4.5 嵌套泛型解析API

java

/**
 * 解析嵌套泛型类型
 * 
 * @param clazz 声明字段的类
 * @param fieldName 字段名
 * @param indexes 多级泛型索引
 * @return 解析后的Class
 */
public static Class<?> resolveNestedGeneric(
        Class<?> clazz,
        String fieldName,
        int... indexes);

4.6 类型检查API

java

/**
 * 检查是否为子类型
 */
public static boolean isSubtypeOf(Class<?> clazz, Class<?> superType);

/**
 * 检查是否实现了接口
 */
public static boolean implementsInterface(Class<?> clazz, Class<?> interfaceType);

/**
 * 检查类型兼容性
 */
public static boolean isAssignableFrom(Class<?> target, Class<?> source);

4.7 数组处理API

java

/**
 * 检查是否为数组类型
 */
public static boolean isArray(Class<?> clazz);

/**
 * 获取数组组件类型
 */
public static <T> Class<T> getArrayComponentType(Class<?> arrayClass);

/**
 * 获取数组维度
 */
public static int getArrayDimensions(Class<?> arrayClass);

5. 封装实现设计

5.1 LinsirType门面类实现

java

/**
 * LinsirType - 类型系统封装门面类
 * 
 * 设计要点：
 * 1. 工具类，禁止实例化
 * 2. 所有方法静态，便于调用
 * 3. 泛型方法提供类型安全
 * 4. 异常统一包装为运行时异常
 */
public final class LinsirType {
    
    // 解析器实例
    private static final ClassResolver classResolver = new ClassResolver();
    private static final FieldResolver fieldResolver = new FieldResolver();
    private static final MethodResolver methodResolver = new MethodResolver();
    
    // 缓存管理器
    private static final CacheManager cacheManager = new DefaultCacheManager();
    
    // 私有构造器
    private LinsirType() {
        throw new AssertionError("工具类禁止实例化");
    }
    
    /**
     * 解析类的单个泛型参数
     */
    @SuppressWarnings("unchecked")
    public static <T> Class<T> resolveGeneric(
            Class<?> clazz, 
            Class<?> genericInterface, 
            int index) {
        // 参数校验
        Assert.notNull(clazz, "Class must not be null");
        Assert.notNull(genericInterface, "Generic interface must not be null");
        Assert.isTrue(index >= 0, "Index must be non-negative");
        
        // 构建缓存键
        CacheKey key = new CacheKey(CacheKey.Type.CLASS_GENERIC, 
            clazz, genericInterface, index);
        
        // 查询缓存
        Class<?> cached = cacheManager.get(key);
        if (cached != null) {
            return (Class<T>) cached;
        }
        
        // 解析
        Class<T> result = classResolver.resolveClassGeneric(
            clazz, genericInterface, index);
        
        // 存入缓存
        if (result != null) {
            cacheManager.put(key, result);
        }
        
        return result;
    }
    
    // 其他方法实现...
}

5.2 ClassResolver实现

java

/**
 * 类泛型解析器
 */
public class ClassResolver {
    
    /**
     * 解析类继承的泛型接口或父类的泛型参数
     */
    @SuppressWarnings("unchecked")
    public <T> Class<T> resolveClassGeneric(
            Class<?> clazz, 
            Class<?> genericInterface, 
            int index) {
        try {
            ResolvableType type = ResolvableType.forClass(clazz);
            ResolvableType targetType = type.as(genericInterface);
            
            if (targetType == ResolvableType.NONE) {
                return null;
            }
            
            ResolvableType generic = targetType.getGeneric(index);
            return (Class<T>) generic.resolve();
        } catch (Exception e) {
            throw new LinsirTypeException(
                String.format("解析类泛型失败: %s from %s", 
                    genericInterface.getName(), clazz.getName()), e);
        }
    }
}

5.3 FieldResolver实现

java

/**
 * 字段泛型解析器
 */
public class FieldResolver {
    
    /**
     * 解析字段的泛型参数
     */
    @SuppressWarnings("unchecked")
    public <T> Class<T> resolveFieldGeneric(
            Class<?> clazz, 
            String fieldName, 
            int index) {
        try {
            Field field = clazz.getDeclaredField(fieldName);
            ResolvableType fieldType = ResolvableType.forField(field);
            
            ResolvableType generic = fieldType.getGeneric(index);
            return (Class<T>) generic.resolve();
        } catch (NoSuchFieldException e) {
            throw new LinsirTypeException(
                "字段不存在: " + fieldName + " in " + clazz.getName(), e);
        }
    }
    
    /**
     * 批量解析字段泛型
     */
    public Map<String, Class<?>[]> resolveFieldGenerics(
            Class<?> clazz, 
            String... fieldNames) {
        Map<String, Class<?>[]> result = new HashMap<>();
        
        for (String fieldName : fieldNames) {
            try {
                Field field = clazz.getDeclaredField(fieldName);
                ResolvableType fieldType = ResolvableType.forField(field);
                
                ResolvableType[] generics = fieldType.getGenerics();
                Class<?>[] types = new Class<?>[generics.length];
                
                for (int i = 0; i < generics.length; i++) {
                    types[i] = generics[i].resolve();
                }
                
                result.put(fieldName, types);
            } catch (NoSuchFieldException e) {
                throw new LinsirTypeException(
                    "字段不存在: " + fieldName, e);
            }
        }
        
        return result;
    }
}

5.4 MethodResolver实现

java

/**
 * 方法泛型解析器
 */
public class MethodResolver {
    
    /**
     * 解析方法参数的泛型
     */
    @SuppressWarnings("unchecked")
    public <T> Class<T> resolveParameterGeneric(
            Class<?> clazz,
            String methodName,
            Class<?>[] parameterTypes,
            int parameterIndex,
            int genericIndex) {
        try {
            Method method = findMethod(clazz, methodName, parameterTypes);
            if (method == null) {
                throw new NoSuchMethodException(
                    "Method not found: " + methodName);
            }
            
            ResolvableType paramType = ResolvableType.forMethodParameter(
                method, parameterIndex);
            ResolvableType generic = paramType.getGeneric(genericIndex);
            
            return (Class<T>) generic.resolve();
        } catch (Exception e) {
            throw new LinsirTypeException(
                "解析方法参数泛型失败: " + methodName, e);
        }
    }
    
    /**
     * 解析方法返回类型的泛型
     */
    @SuppressWarnings("unchecked")
    public <T> Class<T> resolveReturnTypeGeneric(
            Class<?> clazz, 
            String methodName,
            Class<?>[] parameterTypes,
            int index) {
        try {
            Method method = findMethod(clazz, methodName, parameterTypes);
            if (method == null) {
                throw new NoSuchMethodException(
                    "Method not found: " + methodName);
            }
            
            ResolvableType returnType = ResolvableType.forMethodReturnType(
                method, clazz);
            ResolvableType generic = returnType.getGeneric(index);
            
            return (Class<T>) generic.resolve();
        } catch (Exception e) {
            throw new LinsirTypeException(
                "解析方法返回类型泛型失败: " + methodName, e);
        }
    }
    
    private Method findMethod(Class<?> clazz, String methodName, 
            Class<?>[] parameterTypes) {
        if (parameterTypes == null) {
            // 查找第一个匹配的方法名
            for (Method method : clazz.getMethods()) {
                if (method.getName().equals(methodName)) {
                    return method;
                }
            }
            return null;
        }
        
        try {
            return clazz.getMethod(methodName, parameterTypes);
        } catch (NoSuchMethodException e) {
            return null;
        }
    }
}

5.5 DefaultCacheManager实现

java

/**
 * 默认缓存管理器
 * 实现两级缓存：热点缓存 + 软引用缓存
 */
public class DefaultCacheManager implements CacheManager {
    
    // 热点缓存容量
    private static final int HOT_CACHE_SIZE = 100;
    
    // 热点缓存 - 固定容量，LRU淘汰
    private final Map<CacheKey, Class<?>> hotCache = 
        new ConcurrentHashMap<>(HOT_CACHE_SIZE);
    
    // 软引用缓存 - 无容量限制，GC可回收
    private final ConcurrentReferenceHashMap<CacheKey, Class<?>> softCache = 
        new ConcurrentReferenceHashMap<>(256);
    
    // 访问计数器
    private final Map<CacheKey, AtomicInteger> accessCount = 
        new ConcurrentHashMap<>();
    
    @Override
    public Class<?> get(CacheKey key) {
        // 先查热点缓存
        Class<?> result = hotCache.get(key);
        if (result != null) {
            recordHit();
            return result;
        }
        
        // 再查软引用缓存
        result = softCache.get(key);
        if (result != null) {
            // 提升为热点
            promoteToHot(key, result);
            recordHit();
            return result;
        }
        
        recordMiss();
        return null;
    }
    
    @Override
    public void put(CacheKey key, Class<?> value) {
        // 根据访问频率决定放入哪个缓存
        int count = accessCount.computeIfAbsent(key, k -> new AtomicInteger())
                               .incrementAndGet();
        
        if (count > 3 || hotCache.size() < HOT_CACHE_SIZE) {
            // 高频访问或热点缓存未满，放入热点缓存
            hotCache.put(key, value);
        } else {
            // 放入软引用缓存
            softCache.put(key, value);
        }
    }
    
    private void promoteToHot(CacheKey key, Class<?> value) {
        if (hotCache.size() >= HOT_CACHE_SIZE) {
            // 热点缓存已满，淘汰最少访问的
            evictLeastAccessed();
        }
        hotCache.put(key, value);
    }
    
    private void evictLeastAccessed() {
        // 简单实现：随机淘汰（生产环境应使用LRU）
        if (!hotCache.isEmpty()) {
            CacheKey firstKey = hotCache.keySet().iterator().next();
            hotCache.remove(firstKey);
        }
    }
    
    @Override
    public void clear() {
        hotCache.clear();
        softCache.clear();
        accessCount.clear();
    }
    
    // 统计方法...
}

6. 扩展设计引言

6.1 扩展目标

类型系统作为基础能力，需要提供灵活的扩展机制以适应不同场景：

扩展目标	说明	示例
自定义类型解析	支持非标准类型的解析	Kotlin的KType
框架集成	与第三方框架无缝集成	Jackson、Gson
响应式支持	支持响应式编程模型	Mono、Flux
性能优化	针对特定场景的优化	批量解析、异步解析

6.2 可扩展性需求分析

7. 扩展点设计

7.1 TypeResolverExtension接口设计

java

/**
 * 类型解析扩展接口
 * 允许自定义类型解析逻辑
 */
public interface TypeResolverExtension {
    
    /**
     * 扩展点名称
     */
    String getName();
    
    /**
     * 扩展点优先级（数值越小优先级越高）
     */
    int getOrder();
    
    /**
     * 是否支持该类型的解析
     * 
     * @param type 要解析的类型
     * @param context 解析上下文
     * @return true表示支持
     */
    boolean supports(Type type, ResolutionContext context);
    
    /**
     * 解析类型
     * 
     * @param type 要解析的类型
     * @param context 解析上下文
     * @return 解析结果，如果无法解析返回null
     */
    ResolvedType resolve(Type type, ResolutionContext context);
}

7.2 VariableResolverExtension接口设计

java

/**
 * 变量解析器扩展接口
 * 用于解析类型变量（TypeVariable）
 */
public interface VariableResolverExtension {
    
    /**
     * 是否支持该变量
     */
    boolean supports(TypeVariable<?> variable, ResolutionContext context);
    
    /**
     * 解析类型变量
     * 
     * @param variable 类型变量
     * @param context 解析上下文
     * @return 解析后的类型，如果无法解析返回null
     */
    ResolvedType resolveVariable(TypeVariable<?> variable, ResolutionContext context);
}

7.3 ExtensionRegistry注册机制

java

/**
 * 扩展注册表
 * 管理所有类型解析扩展
 */
public class ExtensionRegistry {
    
    /** 扩展列表（按优先级排序） */
    private final List<TypeResolverExtension> resolvers = 
        new CopyOnWriteArrayList<>();
    
    /** 变量解析器 */
    private final List<VariableResolverExtension> variableResolvers = 
        new CopyOnWriteArrayList<>();
    
    /**
     * 注册类型解析扩展
     */
    public void register(TypeResolverExtension extension) {
        Objects.requireNonNull(extension, "Extension must not be null");
        
        // 按优先级插入
        int index = 0;
        for (TypeResolverExtension existing : resolvers) {
            if (existing.getOrder() > extension.getOrder()) {
                break;
            }
            index++;
        }
        resolvers.add(index, extension);
    }
    
    /**
     * 查找支持的解析器
     */
    public Optional<TypeResolverExtension> findResolver(
            Type type, ResolutionContext context) {
        for (TypeResolverExtension resolver : resolvers) {
            if (resolver.supports(type, context)) {
                return Optional.of(resolver);
            }
        }
        return Optional.empty();
    }
}

7.4 SPI加载机制

java

/**
 * SPI扩展加载器
 * 基于ServiceLoader加载扩展
 */
public class SpiExtensionLoader {
    
    /**
     * 加载所有扩展
     */
    public static List<TypeResolverExtension> loadExtensions() {
        List<TypeResolverExtension> extensions = new ArrayList<>();
        
        ServiceLoader<TypeResolverExtension> loader = 
            ServiceLoader.load(TypeResolverExtension.class);
        
        for (TypeResolverExtension extension : loader) {
            extensions.add(extension);
        }
        
        // 按优先级排序
        extensions.sort(Comparator.comparingInt(
            TypeResolverExtension::getOrder));
        
        return extensions;
    }
}

8. 扩展场景设计

8.1 自定义类型解析器扩展

java

/**
 * 自定义类型解析扩展示例
 * 解析自定义的泛型类型
 */
public class CustomTypeExtension implements TypeResolverExtension {
    
    @Override
    public String getName() {
        return "custom-type-resolver";
    }
    
    @Override
    public int getOrder() {
        return 100;
    }
    
    @Override
    public boolean supports(Type type, ResolutionContext context) {
        return type instanceof CustomGenericType;
    }
    
    @Override
    public ResolvedType resolve(Type type, ResolutionContext context) {
        CustomGenericType customType = (CustomGenericType) type;
        return ResolvedType.builder()
            .rawType(customType.getRawClass())
            .generics(resolveGenerics(customType, context))
            .build();
    }
}

8.2 响应式类型支持（Mono/Flux）

java

/**
 * 响应式类型解析扩展
 * 支持Project Reactor的Mono和Flux
 */
public class ReactiveTypeExtension implements TypeResolverExtension {
    
    @Override
    public String getName() {
        return "reactive-type-resolver";
    }
    
    @Override
    public int getOrder() {
        return 200;
    }
    
    @Override
    public boolean supports(Type type, ResolutionContext context) {
        if (!(type instanceof Class)) {
            return false;
        }
        Class<?> clazz = (Class<?>) type;
        return isMono(clazz) || isFlux(clazz);
    }
    
    @Override
    public ResolvedType resolve(Type type, ResolutionContext context) {
        Class<?> clazz = (Class<?>) type;
        // 解析Mono/Flux的泛型参数
        ResolvableType resolvable = ResolvableType.forClass(clazz);
        return ResolvedType.builder()
            .rawType(clazz)
            .generics(resolveReactiveGenerics(resolvable))
            .build();
    }
    
    private boolean isMono(Class<?> clazz) {
        return "reactor.core.publisher.Mono".equals(clazz.getName());
    }
    
    private boolean isFlux(Class<?> clazz) {
        return "reactor.core.publisher.Flux".equals(clazz.getName());
    }
}

8.3 Kotlin协程类型支持

java

/**
 * Kotlin类型解析扩展
 * 支持Kotlin的协程和KType
 */
public class KotlinTypeExtension implements TypeResolverExtension {
    
    @Override
    public String getName() {
        return "kotlin-type-resolver";
    }
    
    @Override
    public int getOrder() {
        return 300;
    }
    
    @Override
    public boolean supports(Type type, ResolutionContext context) {
        // 检查是否为Kotlin类型
        return type.getTypeName().startsWith("kotlin");
    }
    
    @Override
    public ResolvedType resolve(Type type, ResolutionContext context) {
        // 使用Kotlin反射解析类型
        // 需要依赖kotlin-reflect
        return resolveKotlinType(type, context);
    }
}

8.4 第三方框架集成扩展

java

/**
 * Jackson集成扩展
 * 支持Jackson的JavaType
 */
public class JacksonTypeExtension implements TypeResolverExtension {
    
    @Override
    public String getName() {
        return "jackson-type-resolver";
    }
    
    @Override
    public int getOrder() {
        return 400;
    }
    
    @Override
    public boolean supports(Type type, ResolutionContext context) {
        return type.getClass().getName()
            .contains("com.fasterxml.jackson");
    }
    
    @Override
    public ResolvedType resolve(Type type, ResolutionContext context) {
        // 将Jackson的JavaType转换为ResolvedType
        return convertJacksonType(type);
    }
}

9. 扩展实现机制

9.1 扩展加载策略

java

/**
 * 扩展加载策略
 */
public enum ExtensionLoadingStrategy {
    
    /**
     * 懒加载：首次使用时加载
     */
    LAZY {
        @Override
        public void load(ExtensionRegistry registry, 
                Supplier<List<TypeResolverExtension>> supplier) {
            // 不立即加载，延迟到首次使用
        }
    },
    
    /**
     * 预加载：启动时加载所有扩展
     */
    EAGER {
        @Override
        public void load(ExtensionRegistry registry, 
                Supplier<List<TypeResolverExtension>> supplier) {
            List<TypeResolverExtension> extensions = supplier.get();
            for (TypeResolverExtension extension : extensions) {
                registry.register(extension);
            }
        }
    },
    
    /**
     * 按需加载：根据配置选择性加载
     */
    ON_DEMAND {
        @Override
        public void load(ExtensionRegistry registry, 
                Supplier<List<TypeResolverExtension>> supplier) {
            Configuration config = ConfigurationHolder.get();
            List<String> enabled = config.getStringList(
                "linsir.type.resolvers.enabled");
            
            List<TypeResolverExtension> extensions = supplier.get();
            for (TypeResolverExtension extension : extensions) {
                if (enabled.contains(extension.getName())) {
                    registry.register(extension);
                }
            }
        }
    };
    
    public abstract void load(ExtensionRegistry registry, 
                              Supplier<List<TypeResolverExtension>> supplier);
}

9.2 扩展优先级管理

java

/**
 * 扩展优先级管理器
 */
public class ExtensionPriorityManager {
    
    /**
     * 优先级常量
     */
    public static final int PRIORITY_CORE = 0;      // 核心解析器
    public static final int PRIORITY_STANDARD = 100; // 标准扩展
    public static final int PRIORITY_FRAMEWORK = 200; // 框架集成
    public static final int PRIORITY_CUSTOM = 300;   // 自定义扩展
    
    /**
     * 检查优先级冲突
     */
    public static void checkPriorityConflict(
            List<TypeResolverExtension> extensions) {
        Set<Integer> priorities = new HashSet<>();
        for (TypeResolverExtension ext : extensions) {
            if (!priorities.add(ext.getOrder())) {
                throw new IllegalStateException(
                    "Priority conflict: " + ext.getName() + 
                    " has same order with another extension");
            }
        }
    }
}

9.3 扩展生命周期管理

java

/**
 * 扩展生命周期管理器
 */
public class ExtensionLifecycleManager {
    
    public enum ExtensionState {
        CREATED,      // 已创建
        INITIALIZING, // 初始化中
        ACTIVE,       // 活跃状态
        DESTROYING,   // 销毁中
        DESTROYED     // 已销毁
    }
    
    private final Map<String, ExtensionState> states = 
        new ConcurrentHashMap<>();
    
    /**
     * 初始化扩展
     */
    public void initialize(String name, Runnable initializer) {
        states.put(name, ExtensionState.INITIALIZING);
        try {
            initializer.run();
            states.put(name, ExtensionState.ACTIVE);
        } catch (Exception e) {
            states.put(name, ExtensionState.DESTROYED);
            throw new ExtensionInitializationException(
                "Failed to initialize: " + name, e);
        }
    }
    
    /**
     * 销毁扩展
     */
    public void destroy(String name, Runnable destroyer) {
        ExtensionState current = states.get(name);
        if (current == null || current == ExtensionState.DESTROYED) {
            return;
        }
        
        states.put(name, ExtensionState.DESTROYING);
        try {
            destroyer.run();
        } finally {
            states.put(name, ExtensionState.DESTROYED);
        }
    }
}

9.4 扩展与核心模块集成

java

/**
 * 扩展集成器
 * 负责将扩展集成到核心模块
 */
public class ExtensionIntegrator {
    
    private final ExtensionRegistry registry;
    private final CacheManager cacheManager;
    
    public ExtensionIntegrator(ExtensionRegistry registry, 
            CacheManager cacheManager) {
        this.registry = registry;
        this.cacheManager = cacheManager;
    }
    
    /**
     * 集成扩展
     */
    public void integrate(TypeResolverExtension extension) {
        // 1. 注册扩展
        registry.register(extension);
        
        // 2. 清空相关缓存
        cacheManager.clear();
        
        // 3. 记录日志
        LoggerFactory.getLogger(getClass())
            .info("Integrated extension: {}", extension.getName());
    }
}

10. 性能与兼容性设计

10.1 扩展对性能的影响控制

java

/**
 * 扩展性能监控器
 */
public class ExtensionPerformanceMonitor {
    
    private final Map<String, PerformanceStats> stats = 
        new ConcurrentHashMap<>();
    
    /**
     * 记录扩展解析耗时
     */
    public void record(String extensionName, long timeMillis) {
        stats.computeIfAbsent(extensionName, k -> new PerformanceStats())
             .record(timeMillis);
    }
    
    /**
     * 检查是否需要禁用慢速扩展
     */
    public List<String> checkSlowExtensions(long thresholdMillis) {
        List<String> slowExtensions = new ArrayList<>();
        for (Map.Entry<String, PerformanceStats> entry : stats.entrySet()) {
            if (entry.getValue().getAverageTime() > thresholdMillis) {
                slowExtensions.add(entry.getKey());
            }
        }
        return slowExtensions;
    }
}

10.2 版本兼容性设计

java

/**
 * 版本兼容性管理器
 */
public class VersionCompatibilityManager {
    
    /**
     * 检查扩展版本兼容性
     */
    public boolean checkCompatibility(
            TypeResolverExtension extension, 
            String frameworkVersion) {
        
        VersionRange supportedRange = extension.getSupportedVersionRange();
        return supportedRange.includes(frameworkVersion);
    }
    
    /**
     * 获取不兼容的扩展
     */
    public List<TypeResolverExtension> getIncompatibleExtensions(
            List<TypeResolverExtension> extensions,
            String frameworkVersion) {
        
        return extensions.stream()
            .filter(ext -> !checkCompatibility(ext, frameworkVersion))
            .collect(Collectors.toList());
    }
}

10.3 向后兼容保证

java

/**
 * 向后兼容适配器
 */
public class BackwardCompatibilityAdapter {
    
    /**
     * 适配旧版API调用
     */
    public static Class<?> adaptLegacyApiCall(
            Class<?> clazz, 
            Class<?> genericInterface, 
            int index) {
        
        // 尝试新版API
        try {
            return LinsirType.resolveGeneric(clazz, genericInterface, index);
        } catch (LinsirTypeException e) {
            // 降级到旧版实现
            return legacyResolve(clazz, genericInterface, index);
        }
    }
    
    private static Class<?> legacyResolve(Class<?> clazz, 
            Class<?> genericInterface, int index) {
        // 旧版实现逻辑
        ResolvableType type = ResolvableType.forClass(clazz);
        return type.as(genericInterface).getGeneric(index).resolve();
    }
}

11. 数据结构与算法

11.1 CacheKey设计

java

/**
 * 缓存键
 */
public class CacheKey {
    
    public enum Type {
        CLASS_GENERIC,      // 类泛型
        FIELD_GENERIC,      // 字段泛型
        METHOD_PARAMETER,   // 方法参数
        METHOD_RETURN       // 方法返回类型
    }
    
    private final Type type;
    private final Class<?> clazz;
    private final String memberName;
    private final int[] indexes;
    
    // 构造器、equals、hashCode...
}

11.2 缓存查找算法

算法：缓存查找
输入：CacheKey key
输出：Class<?> result 或 null

1. 查询热点缓存 hotCache.get(key)
2. 如果命中，返回结果
3. 查询软引用缓存 softCache.get(key)
4. 如果命中，提升到热点缓存，返回结果
5. 返回 null

11.3 类型解析算法

算法：类型解析
输入：Type type, ResolutionContext context
输出：ResolvedType

1. 查询缓存
2. 如果命中，返回缓存结果
3. 遍历所有扩展，找到支持的解析器
4. 调用解析器解析
5. 缓存解析结果
6. 返回结果

12. 质量保障

12.1 线程安全设计

组件	线程安全措施
LinsirType	无状态，线程安全
CacheManager	ConcurrentHashMap
ExtensionRegistry	CopyOnWriteArrayList
解析器实例	无状态，线程安全

12.2 异常处理策略

java

/**
 * 异常处理策略
 */
public class ExceptionHandlingStrategy {
    
    /**
     * 包装异常
     */
    public static LinsirTypeException wrap(Exception e, String message) {
        if (e instanceof LinsirTypeException) {
            return (LinsirTypeException) e;
        }
        return new LinsirTypeException(message, e);
    }
    
    /**
     * 处理解析失败
     */
    public static <T> T handleFailure(String message, Exception e, 
            Class<T> defaultValue) {
        if (defaultValue != null) {
            return defaultValue;
        }
        throw wrap(e, message);
    }
}

12.3 测试策略

测试类型	覆盖范围	测试数量
单元测试	每个解析器	30+
集成测试	扩展机制	10+
性能测试	缓存命中率	5+
并发测试	线程安全	5+

文档修订历史

版本	日期	修订内容	作者
1.0	2026-03-24	初始版本	Linsir Framework Team

文档结束

LinsirType 类型系统封装与扩展详细设计 ​

目录 ​

第一部分：封装设计 ​

第二部分：扩展设计 ​

第三部分：支撑设计 ​

1. 封装设计引言 ​

1.1 封装目标 ​

1.2 Spring ResolvableType 使用痛点分析 ​

1.3 封装设计原则 ​

2. 主要使用场景分析 ​

2.1 场景1：类泛型解析（Service<T>实现类） ​

2.2 场景2：字段泛型解析（List<String>字段） ​

2.3 场景3：方法参数解析（Controller方法参数） ​

2.4 场景4：方法返回类型解析（Repository方法） ​

2.5 场景5：嵌套泛型解析（Map<String, List<Integer>>） ​

2.6 场景6：类型检查与转换 ​

2.7 场景7：Lambda类型解析 ​

2.8 场景8：Record类型支持 ​

3. 封装架构设计 ​

3.1 门面模式设计（LinsirType） ​

3.2 策略模式设计（TypeResolver体系） ​

3.3 缓存设计（两级缓存） ​

3.4 异常统一封装 ​

4. 封装API详细设计 ​

4.1 类泛型解析API ​

4.2 字段泛型解析API ​

4.3 方法参数解析API ​

4.4 方法返回类型解析API ​

4.5 嵌套泛型解析API ​

4.6 类型检查API ​

4.7 数组处理API ​

5. 封装实现设计 ​

5.1 LinsirType门面类实现 ​

5.2 ClassResolver实现 ​

5.3 FieldResolver实现 ​

5.4 MethodResolver实现 ​

5.5 DefaultCacheManager实现 ​

6. 扩展设计引言 ​

6.1 扩展目标 ​

6.2 可扩展性需求分析 ​

7. 扩展点设计 ​

7.1 TypeResolverExtension接口设计 ​

7.2 VariableResolverExtension接口设计 ​

7.3 ExtensionRegistry注册机制 ​

7.4 SPI加载机制 ​

8. 扩展场景设计 ​

8.1 自定义类型解析器扩展 ​

8.2 响应式类型支持（Mono/Flux） ​

8.3 Kotlin协程类型支持 ​

8.4 第三方框架集成扩展 ​

9. 扩展实现机制 ​

9.1 扩展加载策略 ​

9.2 扩展优先级管理 ​

9.3 扩展生命周期管理 ​

9.4 扩展与核心模块集成 ​

10. 性能与兼容性设计 ​

10.1 扩展对性能的影响控制 ​

10.2 版本兼容性设计 ​

10.3 向后兼容保证 ​

11. 数据结构与算法 ​

11.1 CacheKey设计 ​

11.2 缓存查找算法 ​

11.3 类型解析算法 ​

12. 质量保障 ​

12.1 线程安全设计 ​

12.2 异常处理策略 ​

12.3 测试策略 ​

文档修订历史 ​

LinsirType 类型系统封装与扩展详细设计

目录

第一部分：封装设计

第二部分：扩展设计

第三部分：支撑设计

1. 封装设计引言

1.1 封装目标

1.2 Spring ResolvableType 使用痛点分析

1.3 封装设计原则

2. 主要使用场景分析

2.1 场景1：类泛型解析（Service<T>实现类）

2.2 场景2：字段泛型解析（List<String>字段）

2.3 场景3：方法参数解析（Controller方法参数）

2.4 场景4：方法返回类型解析（Repository方法）

2.5 场景5：嵌套泛型解析（Map<String, List<Integer>>）

2.6 场景6：类型检查与转换

2.7 场景7：Lambda类型解析

2.8 场景8：Record类型支持

3. 封装架构设计

3.1 门面模式设计（LinsirType）

3.2 策略模式设计（TypeResolver体系）

3.3 缓存设计（两级缓存）

3.4 异常统一封装

4. 封装API详细设计

4.1 类泛型解析API

4.2 字段泛型解析API

4.3 方法参数解析API

4.4 方法返回类型解析API

4.5 嵌套泛型解析API

4.6 类型检查API

4.7 数组处理API

5. 封装实现设计

5.1 LinsirType门面类实现

5.2 ClassResolver实现

5.3 FieldResolver实现

5.4 MethodResolver实现

5.5 DefaultCacheManager实现

6. 扩展设计引言

6.1 扩展目标

6.2 可扩展性需求分析

7. 扩展点设计

7.1 TypeResolverExtension接口设计

7.2 VariableResolverExtension接口设计

7.3 ExtensionRegistry注册机制

7.4 SPI加载机制

8. 扩展场景设计

8.1 自定义类型解析器扩展

8.2 响应式类型支持（Mono/Flux）

8.3 Kotlin协程类型支持

8.4 第三方框架集成扩展

9. 扩展实现机制

9.1 扩展加载策略

9.2 扩展优先级管理

9.3 扩展生命周期管理

9.4 扩展与核心模块集成

10. 性能与兼容性设计

10.1 扩展对性能的影响控制

10.2 版本兼容性设计

10.3 向后兼容保证

11. 数据结构与算法

11.1 CacheKey设计

11.2 缓存查找算法

11.3 类型解析算法

12. 质量保障

12.1 线程安全设计

12.2 异常处理策略

12.3 测试策略

文档修订历史