linsir-core 封装架构设计方案

一、设计目标

基于 Spring Framework 的 spring-core 模块，设计 linsir-core 的封装架构，实现以下目标：

简化使用 - 提供更简洁的 API 接口，降低学习成本
隔离依赖 - 业务层不直接依赖 Spring 接口，便于未来替换或升级
增强功能 - 在 Spring 基础上增加实用功能
统一规范 - 建立团队内部的开发规范

二、Spring Core 核心能力分析

2.1 核心包结构

org.springframework.core
├── annotation/          # 注解处理工具
├── codec/              # 编码解码抽象
├── convert/            # 类型转换系统
├── env/                # 环境抽象（Profile、PropertySource）
├── io/                 # 资源加载（Resource、ResourceLoader）
├── task/               # 任务执行抽象
└── util/               # 通用工具类

2.2 核心能力矩阵

能力	核心类	用途
类型系统	`ResolvableType`	泛型解析、类型推断
资源加载	`ResourceLoader`	统一资源访问（文件、URL、classpath）
类型转换	`ConversionService`	类型转换（String → Integer 等）
工具类	`ClassUtils`, `ReflectionUtils`	反射、类操作工具
断言工具	`Assert`	参数校验
环境抽象	`Environment`	配置管理、Profile 切换

三、封装架构设计

3.1 整体架构

┌─────────────────────────────────────────────────────────────┐
│                      API 层 (Public)                         │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │   Types     │  │  Resources  │  │      Utils          │  │
│  │  类型系统    │  │  资源加载    │  │    工具类            │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                      SPI 层 (Extension)                      │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────┐  │
│  │TypeConverter│  │ResourceLoader│  │   Environment      │  │
│  │ 类型转换器   │  │  资源加载器   │  │    环境抽象          │  │
│  └─────────────┘  └─────────────┘  └─────────────────────┘  │
├─────────────────────────────────────────────────────────────┤
│                   Internal 层 (Implementation)               │
│              Spring Core 原生实现包装                         │
└─────────────────────────────────────────────────────────────┘

3.2 包结构设计

com.linsir.core
├── api/                    # API 层 - 对外暴露的接口
│   ├── types/             # 类型系统 API
│   ├── resource/          # 资源加载 API
│   └── util/              # 工具类 API
├── spi/                   # SPI 层 - 扩展点接口
│   ├── converter/         # 类型转换 SPI
│   ├── resource/          # 资源加载 SPI
│   └── env/               # 环境抽象 SPI
├── internal/              # 内部实现层
│   ├── spring/            # Spring 实现包装
│   └── util/              # 内部工具
└── support/               # 支持类
    └── util/              # 工具类支持

四、核心组件设计

4.1 类型系统封装 (Types)

设计思路

对 ResolvableType 进行封装，提供更友好的 API。

接口定义

java

/**
 * 类型解析器 - API 层
 */
public interface TypeResolver {
    
    /**
     * 解析类的泛型参数
     */
    <T> Class<T> resolveGeneric(Class<?> targetClass, Class<?> genericBase, int index);
    
    /**
     * 获取类的所有泛型参数
     */
    Class<?>[] resolveGenerics(Class<?> targetClass, Class<?> genericBase);
    
    /**
     * 检查类型是否匹配
     */
    boolean isAssignable(Class<?> source, Class<?> target);
    
    /**
     * 获取数组元素类型
     */
    Class<?> getComponentType(Class<?> arrayType);
}

使用示例

java

// 原始 Spring API
ResolvableType type = ResolvableType.forClass(UserService.class);
ResolvableType generic = type.as(BaseService.class).getGeneric(0);
Class<?> userClass = generic.resolve();

// 封装后的 API
Class<?> userClass = typeResolver.resolveGeneric(
    UserService.class, 
    BaseService.class, 
    0
);

4.2 资源加载封装 (Resources)

设计思路

对 ResourceLoader 进行封装，统一资源访问方式。

接口定义

java

/**
 * 资源加载器 - API 层
 */
public interface ResourceLoader {
    
    /**
     * 加载资源
     * @param location 资源路径（支持 classpath:, file:, http: 等前缀）
     */
    Resource load(String location);
    
    /**
     * 加载多个资源（支持通配符）
     */
    Resource[] loadAll(String locationPattern);
    
    /**
     * 检查资源是否存在
     */
    boolean exists(String location);
}

/**
 * 资源抽象
 */
public interface Resource {
    
    /**
     * 获取输入流
     */
    InputStream getInputStream() throws IOException;
    
    /**
     * 获取资源内容（文本）
     */
    String getContentAsString() throws IOException;
    
    /**
     * 获取文件
     */
    File getFile() throws IOException;
    
    /**
     * 获取资源名称
     */
    String getName();
    
    /**
     * 检查资源是否存在
     */
    boolean exists();
}

使用示例

java

// 加载配置文件
Resource resource = resourceLoader.load("classpath:application.properties");
String content = resource.getContentAsString();

// 加载多个资源
Resource[] resources = resourceLoader.loadAll("classpath*:mapper/*.xml");

4.3 工具类封装 (Utils)

设计思路

对 Spring 的 ClassUtils, ReflectionUtils, Assert 等进行封装。

接口定义

java

/**
 * 类工具 - API 层
 */
public final class Classes {
    
    private Classes() {}
    
    /**
     * 获取默认类加载器
     */
    public static ClassLoader getDefaultClassLoader();
    
    /**
     * 加载类
     */
    public static Class<?> forName(String className);
    
    /**
     * 获取所有接口
     */
    public static List<Class<?>> getAllInterfaces(Class<?> clazz);
    
    /**
     * 判断是否为简单值类型
     */
    public static boolean isSimpleValueType(Class<?> clazz);
}

/**
 * 反射工具 - API 层
 */
public final class Reflections {
    
    private Reflections() {}
    
    /**
     * 获取字段值
     */
    public static Object getFieldValue(Object target, String fieldName);
    
    /**
     * 设置字段值
     */
    public static void setFieldValue(Object target, String fieldName, Object value);
    
    /**
     * 调用方法
     */
    public static Object invokeMethod(Object target, String methodName, Object... args);
    
    /**
     * 查找方法
     */
    public static Method findMethod(Class<?> clazz, String methodName, Class<?>... paramTypes);
}

/**
 * 断言工具 - API 层
 */
public final class Asserts {
    
    private Asserts() {}
    
    /**
     * 断言对象不为 null
     */
    public static void notNull(Object object, String message);
    
    /**
     * 断言字符串不为空
     */
    public static void hasText(String text, String message);
    
    /**
     * 断言条件为 true
     */
    public static void isTrue(boolean condition, String message);
    
    /**
     * 断言集合不为空
     */
    public static void notEmpty(Collection<?> collection, String message);
}

使用示例

java

// 类操作
Class<?> clazz = Classes.forName("com.example.UserService");
List<Class<?>> interfaces = Classes.getAllInterfaces(clazz);

// 反射操作
Object value = Reflections.getFieldValue(user, "name");
Reflections.setFieldValue(user, "age", 25);

// 断言
Asserts.notNull(user, "User must not be null");
Asserts.hasText(username, "Username must not be empty");

五、实现方案

5.1 实现类设计

java

/**
 * TypeResolver 实现
 */
public class DefaultTypeResolver implements TypeResolver {
    
    @Override
    public <T> Class<T> resolveGeneric(Class<?> targetClass, Class<?> genericBase, int index) {
        ResolvableType type = ResolvableType.forClass(targetClass);
        ResolvableType generic = type.as(genericBase).getGeneric(index);
        return (Class<T>) generic.resolve();
    }
    
    // ... 其他方法实现
}

/**
 * ResourceLoader 实现
 */
public class DefaultResourceLoader implements ResourceLoader {
    
    private final org.springframework.core.io.ResourceLoader delegate;
    
    public DefaultResourceLoader() {
        this.delegate = new PathMatchingResourcePatternResolver();
    }
    
    @Override
    public Resource load(String location) {
        org.springframework.core.io.Resource resource = delegate.getResource(location);
        return new SpringResourceAdapter(resource);
    }
    
    // ... 其他方法实现
}

/**
 * Resource 适配器
 */
public class SpringResourceAdapter implements Resource {
    
    private final org.springframework.core.io.Resource delegate;
    
    public SpringResourceAdapter(org.springframework.core.io.Resource delegate) {
        this.delegate = delegate;
    }
    
    @Override
    public InputStream getInputStream() throws IOException {
        return delegate.getInputStream();
    }
    
    @Override
    public String getContentAsString() throws IOException {
        try (Reader reader = new InputStreamReader(getInputStream())) {
            return FileCopyUtils.copyToString(reader);
        }
    }
    
    // ... 其他方法实现
}

5.2 工厂类设计

java

/**
 * Core 模块入口
 */
public final class LinsirCore {
    
    private static final TypeResolver typeResolver = new DefaultTypeResolver();
    private static final ResourceLoader resourceLoader = new DefaultResourceLoader();
    
    private LinsirCore() {}
    
    /**
     * 获取类型解析器
     */
    public static TypeResolver types() {
        return typeResolver;
    }
    
    /**
     * 获取资源加载器
     */
    public static ResourceLoader resources() {
        return resourceLoader;
    }
}

使用示例

java

// 类型解析
Class<?> genericType = LinsirCore.types()
    .resolveGeneric(UserService.class, BaseService.class, 0);

// 资源加载
Resource resource = LinsirCore.resources().load("classpath:config.properties");
String content = resource.getContentAsString();

六、扩展机制

6.1 SPI 扩展点

java

/**
 * 类型转换器 SPI
 */
public interface TypeConverter<S, T> {
    
    /**
     * 获取源类型
     */
    Class<S> getSourceType();
    
    /**
     * 获取目标类型
     */
    Class<T> getTargetType();
    
    /**
     * 执行转换
     */
    T convert(S source);
}

/**
 * 资源加载器 SPI
 */
public interface ResourceLoaderStrategy {
    
    /**
     * 是否支持该协议
     */
    boolean supports(String protocol);
    
    /**
     * 加载资源
     */
    Resource load(String location);
}

6.2 扩展注册

java

/**
 * 扩展注册器
 */
public interface ExtensionRegistry {
    
    /**
     * 注册类型转换器
     */
    <S, T> void registerConverter(TypeConverter<S, T> converter);
    
    /**
     * 注册资源加载策略
     */
    void registerResourceLoader(ResourceLoaderStrategy strategy);
}

七、与 Spring 的关系

7.1 依赖关系

linsir-core
    ├── spring-core (compile)      # 核心依赖
    ├── spring-jcl (compile)       # 日志抽象
    └── spring-util (optional)     # 可选工具

7.2 版本兼容

linsir-core 版本	Spring Framework 版本	JDK 版本
1.0.x	6.1.x	17+
1.1.x	6.2.x	17+

八、下一步工作

接口细化 - 完善各 API 接口的定义
实现开发 - 开发具体的实现类
单元测试 - 编写全面的单元测试
文档完善 - 编写详细的使用文档
性能优化 - 针对高频操作进行性能优化

linsir-core 封装架构设计方案 ​

一、设计目标 ​

二、Spring Core 核心能力分析 ​

2.1 核心包结构 ​

2.2 核心能力矩阵 ​

三、封装架构设计 ​

3.1 整体架构 ​

3.2 包结构设计 ​

四、核心组件设计 ​

4.1 类型系统封装 (Types) ​

设计思路 ​

接口定义 ​

使用示例 ​

4.2 资源加载封装 (Resources) ​

设计思路 ​

接口定义 ​

使用示例 ​

4.3 工具类封装 (Utils) ​

设计思路 ​

接口定义 ​

使用示例 ​

五、实现方案 ​

5.1 实现类设计 ​

5.2 工厂类设计 ​

使用示例 ​

六、扩展机制 ​

6.1 SPI 扩展点 ​

6.2 扩展注册 ​

七、与 Spring 的关系 ​

7.1 依赖关系 ​

7.2 版本兼容 ​

八、下一步工作 ​

linsir-core 封装架构设计方案

一、设计目标

二、Spring Core 核心能力分析

2.1 核心包结构

2.2 核心能力矩阵

三、封装架构设计

3.1 整体架构

3.2 包结构设计

四、核心组件设计

4.1 类型系统封装 (Types)

设计思路

接口定义

使用示例

4.2 资源加载封装 (Resources)

设计思路

接口定义

使用示例

4.3 工具类封装 (Utils)

设计思路

接口定义

使用示例

五、实现方案

5.1 实现类设计

5.2 工厂类设计

使用示例

六、扩展机制

6.1 SPI 扩展点

6.2 扩展注册

七、与 Spring 的关系

7.1 依赖关系

7.2 版本兼容

八、下一步工作