# LuFramework **Repository Path**: whiteclouds/luframework ## Basic Information - **Project Name**: LuFramework - **Description**: LuFramework - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2023-06-30 - **Last Updated**: 2026-04-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # LuFramework

Java Spring Boot DDD License

企业级领域驱动设计（DDD）框架，助力构建可维护、可扩展的现代化应用

📖 完整文档 · 快速开始 · 模块详解

--- ## 📖 目录 - [项目简介](#项目简介) - [核心特性](#核心特性) - [技术架构](#技术架构) - [分层架构](#分层架构) - [模块划分](#模块划分) - [快速开始](#快速开始) - [环境要求](#环境要求) - [添加依赖](#添加依赖) - [编写第一个API](#编写第一个api) - [使用分布式锁](#使用分布式锁) - [领域事件示例](#领域事件示例) - [模块详解](#模块详解) - [API层 (framework-api)](#api层-framework-api) - [应用层 (framework-application)](#应用层-framework-application) - [领域层 (framework-domain)](#领域层-framework-domain) - [基础设施层 (framework-infrastructure)](#基础设施层-framework-infrastructure) - [分布式锁 (tom-lock)](#分布式锁-tom-lock) - [代码生成器 (framework-generator)](#代码生成器-framework-generator) - [Spring Boot Starter (framework-spring-boot-starter)](#spring-boot-starter-framework-spring-boot-starter) - [设计模式与原则](#设计模式与原则) - [技术栈](#技术栈) - [开发规范](#开发规范) - [命名规范](#命名规范) - [错误处理](#错误处理) - [日志规范](#日志规范) - [代码注释](#代码注释) - [贡献指南](#贡献指南) - [许可证](#许可证) --- ## 🎯 项目简介 LuFramework（鲁框架）是一个基于**领域驱动设计（DDD）**理念构建的企业级Java开发框架。它采用分层架构和模块化设计，旨在帮助开发者构建可维护、可测试、可扩展的现代化企业应用。 该框架深度整合Spring Boot、MyBatis Plus、Redisson等主流技术栈，提供了完整的DDD实现支持，包括领域实体、聚合根、值对象、领域服务、仓储、领域事件等核心概念。同时内置分布式锁、代码生成器、统一异常处理等实用功能，大幅提高开发效率。 ### 适用场景 - ✨ 中大型企业级应用 - 💼 业务逻辑复杂的业务系统 - 🏗️ 需要长期维护和迭代的项目 - 🔒 需要分布式锁和高并发处理的系统 - 📊 数据处理和转换复杂的业务场景 --- ## ✨ 核心特性 ### 🏗️ 分层架构 - **API层**：处理HTTP请求和响应，参数校验 - **应用层**：编排领域对象，处理事务和应用逻辑 - **领域层**：核心业务逻辑，DDD概念完整实现 - **基础设施层**：数据持久化、缓存、外部服务集成 ### 🎯 完整DDD支持 - **聚合根（Aggregate Root）**：业务操作的基本单元 - **实体（Entity）**：具有唯一标识和生命周期的对象 - **值对象（Value Object）**：不可变的描述性对象 - **领域服务（Domain Service）**：跨实体的业务逻辑 - **领域事件（Domain Event）**：发布-订阅的事件驱动机制 - **仓储（Repository）**：聚合的持久化和检索 - **规约（Specification）**：封装业务查询规则 ### 🔒 分布式锁 - 基于Redisson的分布式锁实现 - 注解式声明：`@TomLock`, `@XTomLock` - 支持多种锁模式：方法锁、参数锁、业务签名锁 - 支持SpEL表达式动态计算锁Key - 可配置超时和过期时间 ### 🔧 代码生成器 - 基于MyBatis Plus Generator - 支持FreeMarker模板 - 自动生成Entity、Mapper、Service、Controller - 统一仓储配置支持 - 自定义业务签名生成 ### 💾 统一数据访问 - MyBatis Plus集成 - 统一仓储模式（UnifiedRepository） - 多数据源支持 - 数据转换和验证链 - 缓存集成（支持业务签名） ### 📡 事件驱动架构 - 领域事件总线（DomainEventBus） - 同步/异步事件发布 - 事件重试和修复机制 - 事件存储支持 - 事件调度器 ### 🔐 统一响应格式 - 标准化API响应：`ApiResult` - 统一异常处理 - 全局异常处理器 - 业务异常和系统异常分离 ### ⚡ 现代技术栈 - Spring Boot 3.5.8 + Java 21 - MapStruct 对象映射 - Lombok 减少样板代码 - Validation API 参数校验 - MyBatis Plus ORM框架 - Redisson 分布式锁 - Easy-ES Elasticsearch集成 --- ## 🏗️ 技术架构 ### 分层架构 ``` ┌─────────────────────────────────────────┐ │ API层 (Presentation) │ │ ┌─────────────────────────────────┐ │ │ │ Controller, Request/Response │ │ │ │ Exception Handling, Validation │ │ │ └─────────────────────────────────┘ │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ 应用层 (Application) │ │ ┌─────────────────────────────────┐ │ │ │ AppService, Domain Event Pub │ │ │ │ Transaction Management │ │ │ └─────────────────────────────────┘ │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ 领域层 (Domain) │ │ ┌─────────────────────────────────┐ │ │ │ Aggregate, Entity, ValueObject │ │ │ │ Domain Service, Specification │ │ │ │ Domain Event, Repository IF │ │ │ └─────────────────────────────────┘ │ └─────────────────────────────────────────┘ ↓ ┌─────────────────────────────────────────┐ │ 基础设施层 (Infrastructure) │ │ ┌─────────────────────────────────┐ │ │ │ Repository Impl, Data Access │ │ │ │ Cache, Converter, Lock │ │ │ └─────────────────────────────────┘ │ └─────────────────────────────────────────┘ ``` ### 模块依赖关系 ```mermaid graph TD Starter[framework-spring-boot-starter] --> Api[framework-api] Starter --> Application[framework-application] Starter --> Domain[framework-domain] Starter --> Infrastructure[framework-infrastructure] Api --> Application Application --> Domain Application --> Infrastructure Domain --> Base[framework-base] Infrastructure --> Domain Infrastructure --> Config[framework-config] Infrastructure --> Constant[framework-constant] Infrastructure --> Utils[framework-common-utils] Generator[framework-generator] --> Infrastructure Generator --> Domain Generator --> Api TomLock[tom-lock] --> Utils TomLock --> Infrastructure Utils --> Base Config --> Constant ``` --- ## 🚀 快速开始 ### 环境要求 - JDK 21或更高版本 - Maven 3.8+ - MySQL 8.0+ - Redis 6.0+（用于分布式锁） ### 添加依赖 在您的Spring Boot项目的`pom.xml`中添加LuFramework依赖： ```xml com.zijidelu.luframework framework-spring-boot-starter 1.0-SNAPSHOT ``` ### 编写第一个API #### 1. 定义领域实体（Domain Entity） ```java package com.yourapp.domain.model.entity; import com.zijidelu.luframework.domain.model.entity.Entity; import lombok.Data; import lombok.EqualsAndHashCode; @Data @EqualsAndHashCode(callSuper = true) public class Product extends Entity { private String name; private BigDecimal price; private Integer stock; } ``` #### 2. 创建应用服务（Application Service） ```java package com.yourapp.application.service; import com.zijidelu.luframework.application.service.AbstractAppService; import com.yourapp.domain.model.entity.Product; import org.springframework.stereotype.Service; @Service public class ProductAppService extends AbstractAppService { @Override protected void beforeSave(Product product) { // 保存前的业务校验 if (product.getPrice().compareTo(BigDecimal.ZERO) < 0) { throw new IllegalArgumentException("价格不能为负数"); } } @Override protected void afterSave(Product product) { // 保存后的业务处理 log.info("产品已保存：{}", product.getName()); } } ``` #### 3. 创建API控制器（API Controller） ```java package com.yourapp.api.controller; import com.zijidelu.luframework.api.controller.AbstractCrudController; import com.yourapp.application.service.ProductAppService; import com.yourapp.domain.model.entity.Product; import org.springframework.web.bind.annotation.RequestMapping; import org.springframework.web.bind.annotation.RestController; @RestController @RequestMapping("/api/products") public class ProductController extends AbstractCrudController { // CRUD接口已自动实现： // GET /api/products/query - 查询列表 // GET /api/products/{id} - 查询详情 // POST /api/products/save - 保存数据 // POST /api/products/update - 更新数据 // POST /api/products/deleteByIds - 删除数据 } ``` #### 4. 配置数据源 ```yaml spring: datasource: url: jdbc:mysql://localhost:3306/yourdb?useUnicode=true&characterEncoding=utf8 username: root password: yourpassword driver-class-name: com.mysql.cj.jdbc.Driver mybatis-plus: configuration: map-underscore-to-camel-case: true log-impl: org.apache.ibatis.logging.stdout.StdOutImpl global-config: db-config: logic-delete-field: deleted logic-delete-value: 1 logic-not-delete-value: 0 ``` ### 使用分布式锁 #### 方式一：简单注解（基于SpEL表达式） ```java @Service public class OrderService { @TomLock( desc = "锁定用户订单操作", domain = "order", business = "create", paramExpression = {"#userId", "#orderType"}, timeout = 5000L, expire = 30000L ) public void createOrder(Long userId, String orderType, OrderDTO orderDTO) { // 业务逻辑 // 自动对userId和orderType加锁 } } ``` #### 方式二：高级注解（方法锁模式） ```java @Service public class PaymentService { @XTomLock( desc = "支付确认操作锁", mode = LockMode.METHOD, expire = 60000L ) public void confirmPayment(PaymentContext context) { // 整个方法加锁，基于方法签名 } } ``` #### 方式三：业务对象锁 ```java @Service public class InventoryService { @XTomLock( desc = "扣减库存锁", mode = LockMode.METHOD_ARGS ) public void deductStock(@TomLockParam(resolvers = ProductResolver.class) DeductRequest request) { // 根据ProductResolver解析的逻辑锁Key进行加锁 } } ``` ### 领域事件示例 #### 1. 定义领域事件 ```java public class OrderCreatedEvent extends AbstractDomainEvent { private final Long orderId; private final Long userId; public OrderCreatedEvent(Long orderId, Long userId) { super("ORDER_CREATED"); this.orderId = orderId; this.userId = userId; } } ``` #### 2. 创建事件处理器 ```java @Component public class OrderCreatedHandler implements DomainEventHandler { @Override public void handle(OrderCreatedEvent event) { // 发送通知 notificationService.sendOrderConfirmation(event.getUserId(), event.getOrderId()); // 更新统计 statisticsService.incrementOrderCount(); } } ``` #### 3. 发布领域事件 ```java @Service public class OrderAppService extends AbstractAppService { @Autowired private DomainEventBus eventBus; @Override @Transactional public boolean save(List orders) { boolean result = super.save(orders); // 发布领域事件 orders.forEach(order -> { eventBus.publish(new OrderCreatedEvent(order.getId(), order.getUserId())); }); return result; } } ``` --- ## 📦 模块详解 ### API层 (framework-api) **职责**：处理HTTP请求和响应，参数校验，提供RESTful API接口 **核心组件**： ```java // 基础控制器 public abstract class AbstractCrudController { // 提供完整的CRUD接口实现 // - query: 分页查询 // - getById: 根据ID查询 // - save: 保存数据 // - update: 更新数据 // - deleteByIds: 批量删除 } // 命令控制器（CUD操作） public interface CommandController { ApiResult save(ApiRequest> request); ApiResult update(ApiRequest> request); ApiResult deleteByIds(ApiRequest> ids); } // 查询控制器（查询操作） public interface QueryController { ApiResult getById(Long id); ApiResult> query(ApiRequest> request); } ``` **特点**： - 统一响应格式：`ApiResult` - 全局异常处理器：`DefaultExceptionHandler`, `ControllerExceptionHandler` - 自动数据转换：请求DTO ↔ 领域实体 ↔ 响应VO - 内置分页查询支持 - 参数校验集成（Hibernate Validator） ### 应用层 (framework-application) **职责**：编排领域对象，处理事务边界，发布领域事件 **核心组件**： ```java // 应用服务接口 public interface AppService { boolean save(List modelList); boolean update(List modelList); boolean deleteById(Collection ids); } // 抽象实现，提供生命周期钩子 public abstract class AbstractAppService implements AppService { protected void beforeSave(D model) { } protected void afterSave(D model) { } protected void beforeUpdate(D model) { } protected void afterUpdate(D model) { } protected void beforeDelete(D model) { } protected void afterDelete(D model) { } } // 领域事件发布器 @Component public class DefaultDomainEventBus implements DomainEventBus { // 支持同步/异步/批量事件发布 // 支持事件重试和修复机制 } ``` **特点**： - 业务编排，不包含核心业务规则 - 事务管理（支持@Transactional） - 领域事件发布和调度 - 事件重试和修复机制 ### 领域层 (framework-domain) **职责**：实现核心业务逻辑，业务规则的心脏 **核心概念**： ```java // 聚合根 public interface AggregateRoot extends Entity { void initialize(); void destroy(); void validate(); } // 抽象聚合根实现 public abstract class AbstractAggregateRoot extends AbstractAggregateCapability implements AggregateRootLifeCycle { // 封装聚合生命周期管理 // - 事件收集 // - 子实体管理 // - 初始化/销毁逻辑 } // 实体 public interface Entity extends Serializable { I getId(); void setId(I id); } // 值对象 public interface ValueObject extends Serializable { boolean validate(); } // 领域服务 public interface DomainService { T execute(DomainServiceContext context); } // 领域事件 public interface DomainEvent extends Serializable { String getEventType(); String getEventId(); Long getTimestamp(); } // 仓储接口 public interface AggregateRepository, I extends Serializable> { T findById(I id); void save(T aggregate); void delete(T aggregate); } // 规约 public interface Specification { boolean isSatisfiedBy(T t); Specification and(Specification other); Specification or(Specification other); } ``` **特点**： - DDD核心概念完整实现 - 聚合根封装一致性和不变量 - 领域事件解耦业务逻辑 - 规约封装业务规则 - 类型安全设计（泛型大量使用） ### 基础设施层 (framework-infrastructure) **职责**：技术实现细节，支持领域层和应用层 **核心组件**： ```java // 统一仓储 public interface UnifiedRepository extends Repository, DataProcessor, ConverterVault { // 集成业务签名、数据转换、持久化 } // 数据仓储 public interface DataRepository extends Repository { // 支持MyBatis Plus的CRUD操作 } // 数据处理器 public interface DataProcessor { boolean save(List modelList); boolean update(List modelList); boolean deleteById(Collection ids); } // 数据转换器 public interface DataConverter { E toEntity(D model); D toModel(E entity); } // 持久化上下文 public interface PersistenceContext { IService getBaseService(); } // 缓存处理器 public interface CoreCacheHandler { void cache(D data); void invalidate(D data); } ``` **特点**： - 统一仓储模式（Unified Repository） - MyBatis Plus深度集成 - 数据转换和验证链 - 缓存集成（支持业务签名） - 分布式锁基础设施 ### 分布式锁 (tom-lock) **职责**：提供完整分布式锁解决方案 **使用方式**： ```java // 核心注解 @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface TomLock { String desc(); // 锁描述 String domain(); // 模块名称 String business(); // 业务名称 String[] paramExpression(); // SpEL表达式 long timeout() default -1; // 超时时间 long expire() default -1; // 过期时间 boolean requireSysName() default false; // 是否需要系统名称 } // 高级注解 @Target(ElementType.METHOD) @Retention(RetentionPolicy.RUNTIME) public @interface XTomLock { String desc(); // 锁描述 LockMode mode(); // 锁模式 long timeout() default -1; // 超时时间 long expire() default -1; // 过期时间 } // 锁模式枚举 public enum LockMode { METHOD, // 方法级锁（基于方法签名） METHOD_ARGS, // 方法参数级锁（基于参数值） BUSINESS_SIG // 业务签名锁（基于@TomLockParam） } ``` **特点**： - 注解驱动，无侵入式 - 支持Redisson实现 - 多种锁模式选择 - SpEL表达式支持 - 可配置超时和过期时间 - 支持参数级别的细粒度锁 ### 代码生成器 (framework-generator) **职责**：自动化生成CRUD相关代码 **配置示例**： ```java @Data public class GeneratorConfig { private String author = "Your Name"; // 作者 private String commentDate = "yyyy/MM/dd HH:mm"; // 注释日期格式 private String outputDir = System.getProperty("user.dir"); // 输出目录 private boolean enableSwagger = false; // 是否启用Swagger private boolean enableLombok = true; // 是否启用Lombok private DataBaseConfig dataBaseConfig = new DataBaseConfig(); private MapperConfig mapperConfig = new MapperConfig(); private EntityConfig entityConfig = new EntityConfig(); private DataModelConfig dataModelConfig = new DataModelConfig(); private UnifiedRepositoryConfig unifiedRepositoryConfig = new UnifiedRepositoryConfig(); } ``` **可生成代码**： - Entity（实体类） - Mapper（数据访问层） - Service（服务层） - Controller（控制器） - DTO/VO（数据传输对象） ### Spring Boot Starter (framework-spring-boot-starter) **职责**：自动配置和集成所有模块 **核心功能**： ```java @AutoConfiguration @EnableConfigurationProperties(LuFrameworkProperties.class) @ComponentScan( basePackages = "com.zijidelu.luframework", excludeFilters = { @Filter(type = FilterType.ANNOTATION, classes = {ControllerAdvice.class, RestControllerAdvice.class}) } ) public class LuFrameworkAutoConfiguration { // 自动配置所有模块 // - 数据转换器扫描 // - 聚合根扫描 // - 异常处理器注册 } ``` **特点**： - Spring Boot自动配置 - 组件自动扫描 - 属性自动绑定 - 与其他Starter无冲突 --- ## 🎨 设计模式与原则 ### 使用的经典设计模式 1. **工厂模式**：`AggregateRootFactory` 2. **策略模式**：`EventDispatchStrategy`, `RepairStrategy` 3. **观察者模式**：`DomainEventBus`, `DomainEventHandler` 4. **代理模式**：`TomLockInterceptor`（AOP） 5. **模板方法模式**：`AbstractAggregateRoot`, `AbstractAppService` 6. **建造者模式**：`TomLockContext.Builder` 7. **单例模式**：工具类如`CastUtil` 8. **门面模式**：`UnifiedRepository` ### 架构原则 1. **关注点分离**：各层职责清晰，API→应用→领域→基础设施 2. **依赖倒置**：领域层定义接口，基础设施层实现 3. **接口隔离**：细粒度的接口设计 4. **单一职责**：每个类只做一件事 5. **开闭原则**：通过继承和扩展而非修改 6. **里氏代换**：子类可以替换父类 ### DDD原则 1. **聚合边界**：聚合根封装一致性和不变量 2. **实体 vs 值对象**：有标识 vs 无标识 3. **领域服务**：跨实体的业务逻辑 4. **领域事件**：解耦和最终一致性 5. **仓储**：聚合持久化抽象 --- ## 🛠️ 技术栈 ### 核心框架 | 技术 | 版本 | 用途 | |------|------|------| | Java | 21 | 编程语言 | | Spring Boot | 3.5.8 | 应用框架 | | MyBatis Plus | 3.5.15 | ORM框架 | ### 工具和库 | 技术 | 版本 | 用途 | |------|------|------| | Lombok | 1.18.42 | 减少样板代码 | | MapStruct | 1.5.5.Final | 对象映射 | | Hibernate Validator | 8.0.1.Final | 参数校验 | | Redisson | 3.29.0 | 分布式锁 | | Easy-ES | 2.0.0-beta1 | Elasticsearch集成 | | RocketMQ | 2.3.1 | 消息队列 | | Druid | 1.2.18 | 数据库连接池 | | Hutool | 5.8.42 | 工具类库 | | Guava | 33.5.0-jre | Google工具库 | ### 代码生成 | 技术 | 版本 | 用途 | |------|------|------| | MyBatis Plus Generator | 3.5.15 | 代码生成 | | FreeMarker | 2.3.34 | 模板引擎 | | JavaParser | 3.27.1 | Java代码解析 | | JavaPoet | 1.13.0 | Java代码生成 | ### 测试相关 | 技术 | 版本 | 用途 | |------|------|------| | JUnit | Jupiter | 单元测试 | | Mockito | 4.11.0 | 模拟对象 | | JMH | 1.37 | 性能基准测试 | --- ## 📋 开发规范 ### 命名规范 **类命名**： - 使用PascalCase（大驼峰） - 语义清晰，避免缩写 - 示例：`UserService`, `OrderRepository`, `ProductValidator` **方法命名**： - 使用camelCase（小驼峰） - 动词开头，表明操作 - 示例：`saveOrder()`, `validateProduct()`, `publishEvent()` **变量命名**： - 使用camelCase（小驼峰） - 名词或描述性词语 - 示例：`productList`, `orderRepository` **常量命名**： - 全部大写，下划线分隔 - 示例：`MAX_RETRY_COUNT`, `DEFAULT_TIMEOUT` ### 错误处理 **自定义异常**： ```java // 领域层异常 public class DomainBizException extends RuntimeException { private final String code; private final String message; } // 基础设施层异常 public class RepositoryException extends RuntimeException { private final String repositoryName; private final String operation; } // 分布式锁异常 public class TomLockException extends RuntimeException { private final String lockKey; private final LockMode lockMode; } ``` **异常处理规范**： 1. 领域层抛领域异常 2. 应用层捕获并转换为业务异常 3. API层统一处理并转换为ApiResult 4. 系统异常打日志，业务异常可不打 ### 日志规范 **日志级别使用**： - `ERROR`：系统异常、需要立即关注 - `WARN`：潜在问题、非关键异常 - `INFO`：业务流程、关键操作 - `DEBUG`：调试信息、开发环境 - `TRACE`：详细追踪、性能调试 **日志规范示例**： ```java @Slf4j @Service public class OrderService { public void createOrder(Order order) { log.info("开始创建订单 | userId={} | orderId={}", order.getUserId(), order.getId()); try { // 业务逻辑 log.debug("订单数据 | order={}", order); } catch (BusinessException e) { log.warn("创建订单失败 | userId={} | reason={}", order.getUserId(), e.getMessage()); throw e; } catch (Exception e) { log.error("创建订单系统异常 | userId={}", order.getUserId(), e); throw new SystemException("创建订单失败", e); } } } ``` **日志规范要求**： 1. 使用占位符`{}`而非字符串拼接 2. 关键业务参数必须输出 3. 敏感信息（密码、手机号）必须脱敏 4. 异常必须输出堆栈（最后一个参数传异常） ### 代码注释 **类注释**： ```java /** * 订单聚合根。 *

* 封装订单相关业务逻辑，管理订单行项、支付信息等子实体。 * 保证订单业务规则的一致性。 * * @author ZIJIDELU * @datetime 2025/10/17 10:54 * @see OrderLineItem * @see PaymentInfo */ ``` **方法注释**： ```java /** * 创建订单。 *

* 创建前会校验用户状态、商品库存、优惠券有效性。 *

* 前置条件： *

    *
  • 用户状态正常
    • *
  • 商品库存充足
    • *
  • 优惠券有效期内
    • *
*

* 后置条件： *

    *
  • 订单状态为"待支付"
    • *
  • 库存已预占
    • *
  • 优惠券已使用
    • *
* * @param createOrderRequest 创建订单请求 * @return 创建的订单聚合根 * @throws UserStatusException 用户状态异常 * @throws InsufficientStockException 库存不足 * @throws InvalidCouponException 优惠券无效 */ ``` **注释要求**： 1. 所有公共类和接口必须有注释说明 2. 复杂业务方法必须有详细文档 3. 参数含义必须清楚 4. 可能抛出的异常必须列出 5. 中文注释使用中文标点符号 --- ## 🤝 贡献指南 欢迎贡献代码、文档、测试用例等各种形式的贡献！ ### 开发环境搭建 1. Fork 本仓库到您的GitHub账号 2. Clone 您的Fork到本地 ```bash git clone https://github.com/YourUsername/lu-framework.git cd lu-framework ``` 3. 创建特性分支 ```bash git checkout -b feature/your-feature-name # 或 git checkout -b fix/your-bug-fix ``` 4. 构建项目 ```bash mvn clean install ``` 5. 运行测试（确保所有测试通过） ```bash mvn test ``` ### 提交规范 **Commit Message格式**： ``` ():