一 SITUATION（背景情境）
1.1 模块定位与价值
lattice-model 是 Lattice 框架的基石模块，定义了整个框架的核心概念模型和元数据结构。它的核心使命是：
领域建模：定义 Ability（能力）、Business（业务）、Extension（扩展点）等核心概念
元数据管理：通过注解和规范（Spec）实现配置与代码的统一
编译期增强：利用注解处理器自动生成 SPI 配置文件
运行时基础：为 lattice-runtime 提供模型支撑
1.2 依赖分析（从 pom.xml 透视设计意图）
二、TASK（设计目标）
2.1 核心目标矩阵（MECE 完全穷尽）
lattice-model 的设计目标 ├── 领域建模 │ ├── 定义核心概念（Ability/Business/Extension/Product/UseCase） │ └── 建立概念之间的关系（聚合、组合、继承） │ ├── 元数据管理 │ ├── 注解定义（@Ability、@Business、@Extension 等） │ ├── 注解模型（AbilityAnnotation、BusinessAnnotation 等） │ └── 规范对象（AbilitySpec、ExtensionSpec 等） │ ├── 编译期处理 │ ├── 注解处理器（Processor） │ ├── 注解解析器（Parser） │ └── SPI 自动注册 │ ├── 运行时支撑 │ ├── 缓存接口定义 │ ├── 扩展点执行模型 │ └── 业务上下文管理 │ └── 工具支持 ├── 类加载器扩展 ├── 工具类库 └── 异常体系
三、ACTION（实现架构）
3.1 目录结构全景图（MECE 分层）
lattice-model/src/main/java/org/hiforce/lattice/ │ ├── 📌 annotation/ 【注解定义层】 │ ├── Ability.java // 能力注解：标记领域能力类 │ ├── Business.java // 业务注解：标记业务实现类 │ ├── Extension.java // 扩展点注解：标记可扩展方法 │ ├── Product.java // 产品注解：标记产品模板 │ ├── UseCase.java // 用例注解：标记业务用例 │ ├── Realization.java // 实现注解：标记扩展实现类 │ ├── Priority.java // 优先级注解：控制执行顺序 │ ├── ScanSkip.java // 跳过扫描注解 │ ├── Schema.java // 模式注解 │ │ │ ├── model/ 【注解模型子层】 │ │ ├── AbilityAnnotation.java // Ability 注解的运行时表示 │ │ ├── BusinessAnnotation.java // Business 注解的运行时表示 │ │ ├── ExtensionAnnotation.java // Extension 注解的运行时表示 │ │ ├── ProductAnnotation.java // Product 注解的运行时表示 │ │ ├── UseCaseAnnotation.java // UseCase 注解的运行时表示 │ │ ├── RealizationAnnotation.java // Realization 注解的运行时表示 │ │ ├── PriorityAnnotation.java // Priority 注解的运行时表示 │ │ ├── ReduceType.java // 聚合策略枚举（FIRST/ALL/NONE） │ │ ├── ProtocolType.java // 协议类型枚举（LOCAL/REMOTE） │ │ └── ScanSkipAnnotation.java // ScanSkip 注解的运行时表示 │ │ │ ├── parser/ 【注解解析子层】 │ │ ├── DefaultAbilityAnnotationParser.java │ │ ├── DefaultBusinessAnnotationParser.java │ │ ├── DefaultExtensionAnnotationParser.java │ │ ├── DefaultProductAnnotationParser.java │ │ ├── DefaultUseCaseAnnotationParser.java │ │ ├── DefaultRealizationAnnotationParser.java │ │ ├── DefaultPriorityAnnotationParser.java │ │ └── DefaultScanSkipAnnotationParser.java │ │ │ └── processor/ 【注解处理器子层】 │ ├── AbilityAnnotationProcessor.java // 编译期处理 @Ability │ ├── BusinessAnnotationProcessor.java // 编译期处理 @Business │ ├── ProductAnnotationProcessor.java // 编译期处理 @Product │ ├── UseCaseAnnotationProcessor.java // 编译期处理 @UseCase │ └── RealizationAnnotationProcessor.java // 编译期处理 @Realization │ ├── 🏗️ model/ 【核心模型层】 │ ├── ability/ 【能力模型子层】 │ │ ├── IAbility.java // 能力接口：定义能力的核心契约 │ │ ├── IBusinessExt.java // 业务扩展接口 │ │ ├── BusinessExt.java // 业务扩展抽象类 │ │ ├── cache/ │ │ │ └── IBusinessExtCache.java // 业务扩展缓存接口 │ │ └── execute/ │ │ ├── Reducer.java // 聚合器抽象类 │ │ └── ExtensionCallback.java // 扩展回调接口 │ │ │ ├── business/ 【业务模型子层】 │ │ ├── IBizObject.java // 业务对象接口 │ │ ├── BizContext.java // 业务上下文：携带 bizCode/bizId/scenario │ │ ├── ITemplate.java // 模板接口 │ │ ├── Template.java // 模板抽象类 │ │ ├── TemplateType.java // 模板类型枚举 │ │ ├── IBusiness.java // 业务标记接口 │ │ ├── BusinessTemplate.java // 业务模板 │ │ ├── IProduct.java // 产品标记接口 │ │ ├── ProductTemplate.java // 产品模板 │ │ ├── IUseCase.java // 用例标记接口 │ │ └── UseCaseTemplate.java // 用例模板 │ │ │ ├── register/ 【注册规范子层】 │ │ ├── BaseSpec.java // 规范基类（code/name/desc） │ │ ├── AbilitySpec.java // 能力规范：管理能力实例 │ │ ├── AbilityInstSpec.java // 能力实例规范 │ │ ├── ExtensionSpec.java // 扩展点规范：记录方法信息 │ │ ├── BusinessSpec.java // 业务规范 │ │ ├── ProductSpec.java // 产品规范 │ │ ├── UseCaseSpec.java // 用例规范 │ │ ├── RealizationSpec.java // 实现规范 │ │ └── TemplateSpec.java // 模板规范 │ │ │ ├── config/ 【配置模型子层】 │ │ ├── BusinessConfig.java // 业务配置：产品安装、扩展优先级 │ │ ├── ProductConfig.java // 产品配置 │ │ ├── ExtPriority.java // 扩展优先级 │ │ ├── ExtPriorityConfig.java // 扩展优先级配置 │ │ ├── ReadonlyBusinessConfig.java // 只读业务配置 │ │ └── builder/ │ │ ├── BusinessConfigBuilder.java // 业务配置构建器 │ │ └── ProductConfigBuilder.java // 产品配置构建器 │ │ │ ├── context/ 【上下文子层】 │ │ ├── AbilityContext.java // 能力上下文 │ │ └── SdkContext.java // SDK 上下文 │ │ │ └── scenario/ 【场景子层】 │ └── ScenarioRequest.java // 场景请求 │ ├── 🔌 extension/ 【扩展执行层】 │ ├── ExtensionRunner.java // 扩展执行器抽象类 │ ├── ExtensionRunnerType.java // 执行器类型枚举 │ ├── ExtensionRemoteRunner.java // 远程扩展执行器接口 │ ├── RemoteExtensionRunnerBuilder.java // 远程执行器构建器 │ └── RunnerItemEntry.java // 执行项入口 │ ├── 🔧 spi/ 【SPI 扩展层】 │ ├── LatticeAnnotationSpiFactory.java // SPI 工厂：管理所有注解解析器 │ │ │ ├── annotation/ 【注解 SPI 子层】 │ │ ├── LatticeAnnotationParser.java // 注解解析器标记接口 │ │ ├── LatticeAnnotationProcessor.java // 注解处理器基类（核心！） │ │ ├── AbilityAnnotationParser.java // Ability 解析器接口 │ │ ├── BusinessAnnotationParser.java // Business 解析器接口 │ │ ├── ExtensionAnnotationParser.java // Extension 解析器接口 │ │ ├── ProductAnnotationParser.java // Product 解析器接口 │ │ ├── UseCaseAnnotationParser.java // UseCase 解析器接口 │ │ ├── RealizationAnnotationParser.java // Realization 解析器接口 │ │ ├── PriorityAnnotationParser.java // Priority 解析器接口 │ │ └── ScanSkipAnnotationParser.java // ScanSkip 解析器接口 │ │ │ ├── classloader/ 【类加载器 SPI 子层】 │ │ ├── CustomClassLoaderSpi.java // 自定义类加载器 SPI 接口 │ │ └── LatticeClassLoader.java // Lattice 类加载器（支持多委托） │ │ │ └── config/ 【配置 SPI 子层】 │ └── ConfigResolverSpi.java // 配置解析器 SPI 接口 │ ├── 💾 cache/ 【缓存接口层】 │ ├── ILatticeRuntimeCache.java // 运行时缓存总接口 │ ├── ITemplateCache.java // 模板缓存接口 │ ├── IMultiKeyCache.java // 多键缓存接口 │ ├── LatticeCacheFactory.java // 缓存工厂 │ └── invoke/ │ ├── InvokeCache.java // 调用缓存 │ └── InvokeCacheKey.java // 调用缓存键 │ ├── ⚠️ exception/ 【异常层】 │ ├── ILatticeException.java // Lattice 异常接口 │ └── LatticeRuntimeException.java // Lattice 运行时异常 │ ├── 💬 message/ 【消息层】 │ ├── Message.java // 消息对象 │ ├── MessageCode.java // 消息编码 │ └── MessageHelper.java // 消息助手 │ ├── 🔢 sequence/ 【序列生成层】 │ └── SequenceGenerator.java // 序列生成器（雪花算法） │ └── 🛠️ utils/ 【工具层】 ├── BizCodeUtils.java // 业务编码工具 ├── BusinessExtUtils.java // 业务扩展工具 ├── JacksonUtils.java // JSON 序列化工具 ├── LatticeAnnotationUtils.java // 注解工具 ├── LatticeClassUtils.java // 类工具 └── ServicesFileUtils.java // SPI 文件读写工具
3.2 核心设计模式剖析
3.2.1 注解驱动的元数据模型（Annotation-Driven Metadata）
设计哲学：将配置信息声明化，通过注解表达业务意图
// 用户代码：声明一个能力 @Ability(code = "ORDER_ABILITY", name = "订单能力") public interface OrderAbility extends IAbility<OrderExt> { // 能力定义 } // 框架内部：三层处理链路 注解定义 (@Ability) ↓ 注解模型 (AbilityAnnotation) // 运行时访问 ↓ 注解解析器 (AbilityAnnotationParser) // SPI 扩展 ↓ 规范对象 (AbilitySpec) // 注册到运行时
3.2.2 SPI 双重机制（编译期 + 运行期）
编译期 SPI：基于 APT（Annotation Processing Tool）
// LatticeAnnotationProcessor 的工作原理 @AutoService(Processor.class) // 自动注册到 javac public class AbilityAnnotationProcessor extends LatticeAnnotationProcessor { // 1. 编译时扫描 @Ability 注解 @Override public boolean process(Set<? extends TypeElement> annotations, RoundEnvironment env) { // 2. 生成 META-INF/services/AbilityAnnotationParser // 3. 将实现类全限定名写入配置文件 } } // LatticeAnnotationSpiFactory 的加载机制 public class LatticeAnnotationSpiFactory { public List<AbilityAnnotationParser> getAbilityAnnotationParsers() { // 读取 META-INF/services/AbilityAnnotationParser ServiceLoader<AbilityAnnotationParser> parsers = ServiceLoader.load(AbilityAnnotationParser.class); return StreamSupport.stream(parsers.spliterator(), false) .collect(Collectors.toList()); } }
设计优势：
✅ 解耦：解析逻辑与框架核心分离
✅ 可测试：每个解析器可独立测试
✅ 可扩展：用户可自定义注解解析器
3.2.3 规范-模板模式（Spec-Template Pattern）
核心思想：元数据（Spec）和实例（Template）分离
// 元数据：描述"是什么" public class BusinessSpec extends BaseSpec { private String code; // 业务码 private String name; // 业务名称 private int priority; // 优先级 private Class<?> businessClass; // 业务类 // 工厂方法：创建实例 public BusinessTemplate newInstance() { return (BusinessTemplate) businessClass.newInstance(); } } // 实例：提供"怎么做" public abstract class BusinessTemplate extends Template { // 运行时执行的逻辑 public boolean isEffect(ScenarioRequest request) { ... } }
3.2.4 自定义类加载器（ClassLoader Isolation）
问题场景：插件间类冲突
解决方案：LatticeClassLoader
public class LatticeClassLoader extends ClassLoader { // 支持多个自定义类加载器 private final List<ClassLoader> customLoaders = Lists.newArrayList(); @Override public Class<?> loadClass(String name) throws ClassNotFoundException { try { // 1. 先走双亲委派 return super.loadClass(name); } catch (ClassNotFoundException ex) { // 2. 再遍历自定义加载器 for (ClassLoader loader : customLoaders) { try { return loader.loadClass(name); } catch (ClassNotFoundException ignored) {} } throw new ClassNotFoundException(name); } } }
设计特点：
✅ 隔离性：每个插件独立类空间
✅ 共享性：公共类走双亲委派
✅ 组合性：支持多个自定义加载器
