# lucy-spring-boot-starter **Repository Path**: lboot/lucy-spring-boot-starter ## Basic Information - **Project Name**: lucy-spring-boot-starter - **Description**: SpringBoot开发脚手架，鉴权、缓存、注解、全局配置、通用数据对象、通用接口、工具类等，详细介绍可参阅README。 - **Primary Language**: Java - **License**: LGPL-3.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 5 - **Forks**: 3 - **Created**: 2022-12-12 - **Last Updated**: 2026-05-20 ## Categories & Tags **Categories**: Uncategorized **Tags**: SpringBoot, Java, 脚手架 ## README

logo

Lucy v2

不断迭代的技术解决方案

JDK 21+ Spring Boot 3.x License

--- ## 1. 概述与快速开始 ### 1.1 项目介绍 **Lucy** 是一系列技术方案的整合框架，也可以视作一个完整项目多个不同模块的拆分，支持按需引入，秉承着高可用的观念，通过对`POM`文件修改完成解决方案的更迭，并提供配套前端方案。同时也支持自定义拓展实现方案，更好适配业务系统。 该框架核心为`lucy-spring-boot-starter`，是多种解决方案的必需依赖。 ### 1.2 环境要求 - **JDK**: 21+ - **Spring Boot**: 3.x - **构建工具**: Maven 3.6+ ### 1.3 快速开始 #### 1.3.1 仓库配置 在引入任何 `Lucy`系列依赖之前，需要完成`jitpack`镜像仓库的配置。 ```xml jitpack.io https://www.jitpack.io ``` #### 1.3.2 依赖引入 在`pom`文件中直接引入，`version`与发行版本号一致，版本列表点击[查看](https://gitee.com/lboot/lucy-spring-boot-starter/releases) ```xml com.gitee.lboot lucy-spring-boot-starter x.x.x ``` #### 1.3.3 基础配置 ```properties # 应用名称 spring.application.name=lucy-spring-boot-starter # 服务端口（支持环境变量） server.port=${SERVER_PORT:8080} # JPA 允许 bean 定义覆盖 spring.main.allow-bean-definition-overriding=true ``` --- ## 2. JPA 数据持久化 ### 2.1 数据源与 JPA 配置 #### 2.1.1 数据源配置 ```properties # 数据库驱动 spring.datasource.driver-class-name=com.mysql.cj.jdbc.Driver # 数据库连接 spring.datasource.url=jdbc:mysql://localhost:3306/lucy?allowPublicKeyRetrieval=true&useSSL=false&serverTimezone=Asia/Shanghai spring.datasource.username=root spring.datasource.password=root # HikariCP 连接池配置 spring.datasource.hikari.auto-commit=true spring.datasource.hikari.connection-timeout=30000 ``` #### 2.1.2 JPA 配置 ```properties # 自动更新表结构 spring.jpa.hibernate.ddl-auto=update # 显示 SQL spring.jpa.show-sql=false # 物理命名策略：驼峰转下划线 spring.jpa.hibernate.naming.physical-strategy=org.hibernate.boot.model.naming.PhysicalNamingStrategyStandardImpl # 禁用 open-in-view spring.jpa.open-in-view=false ``` ### 2.2 实体基类体系 提供 14 个实体相关基类/接口，支持两种主键策略（雪花 String ID / 自增 Long ID）、四种审计模式，并扩展逻辑删除（`Logic*`）与乐观锁能力： | 类名 | 主键类型 | 审计字段 | 说明 | |------|----------|----------|------| | `BaseEntity` | String (雪花) | 创建者、修改者、创建时间、修改时间 | 完整审计，使用 Spring Data JPA 自动审计 | | `LongBaseEntity` | Long (自增) | 创建者、修改者、创建时间、修改时间 | 完整审计，使用 Spring Data JPA 自动审计 | | `DateAuditBaseEntity` | String (雪花) | 创建时间、修改时间 | 仅日期审计 | | `DateAuditLongBaseEntity` | Long (自增) | 创建时间、修改时间 | 仅日期审计 | | `CustomAuditBaseEntity` | String (雪花) | 创建者、修改者、创建时间、修改时间 | 自定义审计（手动赋值，不自动填充） | | `CustomAuditLongBaseEntity` | Long (自增) | 创建者、修改者、创建时间、修改时间 | 自定义审计（手动赋值） | | `NoAuditBaseEntity` | String (雪花) | 无 | 仅包含 ID | | `NoAuditLongBaseEntity` | Long (自增) | 无 | 仅包含 ID | | `LogicBaseEntity` | String (雪花) | `BaseEntity` 全字段 + deleted、deletedTime、deleteUserId、version | 带逻辑删除 + 乐观锁 | | `LogicLongBaseEntity` | Long (自增) | `LongBaseEntity` 全字段 + deleted、deletedTime、deleteUserId、version | 带逻辑删除 + 乐观锁 | | `LogicDateAuditBaseEntity` | String (雪花) | `DateAuditBaseEntity` 全字段 + deleted、deletedTime、version | 日期审计 + 逻辑删除 + 乐观锁 | | `LogicDateAuditLongBaseEntity` | Long (自增) | `DateAuditLongBaseEntity` 全字段 + deleted、deletedTime、version | 日期审计 + 逻辑删除 + 乐观锁 | | `LogicCustomAuditBaseEntity` | String (雪花) | `CustomAuditBaseEntity` 全字段 + deleted、deletedTime、deleteUserId、version | 自定义审计 + 逻辑删除 + 乐观锁 | | `LogicCustomAuditLongBaseEntity` | Long (自增) | `CustomAuditLongBaseEntity` 全字段 + deleted、deletedTime、version | 自定义审计 + 逻辑删除 + 乐观锁 | **使用示例：** ```java @Entity @Table(name = "sys_user") public class User extends BaseEntity { private String username; private String email; // ... } ``` ### 2.3 CRUD 数据访问服务 提供丰富的 CRUD 操作接口： | 服务接口 | 功能说明 | |---------|----------| | `BaseService` | 基础 CRUD 接口（分页、查询、保存、删除） | | `BatchService` | 批量操作接口（批量保存、查询、删除） | | `SpecService` | 谓词条件查询接口（Specification 动态查询） | | `UnwrapService` | 数据脱壳服务（查询不到时抛异常） | | `UniService` | 聚合服务接口，继承以上所有服务 | **使用示例：** ```java @Service public class UserService extends AbstractJpaCurdExt implements UniService { // 自动获得所有 CRUD 方法 } ``` ### 2.4 逻辑删除 实现 `LogicEntity` 接口的实体自动获得逻辑删除能力，查询时自动过滤已删除记录。 ```java @Bean public class User extends LogicBaseEntity { private String username; } @Service public class UserService extends AbstractJpaLogicCurdExt { // logicDeleteOne / recoverOne 等方法自动可用 } ``` 提供四个抽象实现类： | 抽象类 | 说明 | |--------|------| | `AbstractJpaCurd` | 基础 CRUD 实现 | | `AbstractJpaCurdExt` | 扩展 CRUD（支持 Example + Specification） | | `AbstractJpaLogicCurd` | 逻辑删除 CRUD（自动过滤 deleted=false） | | `AbstractJpaLogicCurdExt` | 扩展逻辑删除 CRUD（支持自定义 Specification） | ### 2.5 JPA 类型转换器 提供数据库字段与 Java 类型的自动转换： | 转换器 | 功能 | |--------|------| | `EncryptConverter` | 字段 DES 加密存储（已废弃） | | `JpaListStringConverter` | List\ 与 JSON 互转 | | `JpaListLongConverter` | List\ 与 JSON 互转 | | `JpaListObjectConverter` | List\ 与 JSON 互转 | ```java @Convert(converter = JpaListStringConverter.class) private List tags; ``` --- ## 3. 认证与鉴权 ### 3.1 鉴权服务接口体系 `AuthService` 聚合四个子接口，提供完整的鉴权能力： | 接口 | 功能 | |------|------| | `BasicAuthService` | 基础登录/登出（doLogin / doLogout） | | `AuthDataService` | 用户数据（getUid / getToken） | | `AccessControlService` | 访问控制（isLogin / isAdmin / hasRole / hasPerm） | | `RiskAuthService` | 风险控制（doBan / isBan） | **使用条件：** 1. 引入`lucy-spring-boot-starter` 2. 自定义实现`AuthService`或直接引入解决方案 **服务使用：** ```java public class DemoCtl { @Autowired AuthService authService; } ``` **方法列表：** | 方法 | 功能 | 返回值 | 备注 | |:------------------------------| :------------------------------------------- | :------- | :----- | | getUid | 获取登录用户ID | String | 1.0.0+ | | getUserName | 获取登录用户账号 | String | 1.0.0+ | | getNickName | 获取登录用户昵称 | String | 1.0.0+ | | getUser | 获取登录用户信息 | BaseUser | 1.0.0+ | | getToken | 获取会话令牌 | String | 1.0.0+ | | isLogin | 判断会话是否处于登录态 | Boolean | 1.0.0+ | | isAdmin | 判断登录用户是否为管理员 | Boolean | 1.0.0+ | | hasRole(String roleKey) | 判断用户是否拥有角色标识 | Boolean | 1.0.0+ | | hasPerm(String perm) | 判断用户是否拥有权限标识 | Boolean | 1.0.0+ | | getRoles | 获取用户拥有角色标识列表 | List | 1.0.0+ | | getPerms | 获取用户拥有权限标识列表 | List | 1.0.0+ | | doLogin(Object id) | 登录操作 | Boolean | 1.0.0+ | | doLogout(Object id) | 登出操作，不传递id默认登出当前登录用户 | Boolean | 1.0.0+ | | doBan(Object id,Integer hour) | 封禁操作，封禁账户id时长{hour}小时 | Void | 1.0.0+ | | isBan(Object id) | 查询${id}是否处于封禁状态 | Boolean | 1.0.0+ | | getDeptId() | 获取当前用户部门ID（不存在返回空） | String | 1.0.3+ | | getRoleIds() | 获取当前用户拥有的角色ID列表 | List | 1.0.3+ | ### 3.2 注解鉴权 #### 3.2.1 @AuthLogin > 校验用户是否登录 > 依赖于鉴权服务 #### 3.2.2 @CheckRole > 角色核验 > 依赖于鉴权服务 | 参数 | 类型 | 说明 | 默认值 | | ------ | ------ | -------- | ------ | | value | string | 角色标识 | admin | | orPerm | string | 权限标识 | | 该注解用于方法拦截，当前登录用户拥有`value`对应的角色标识**或**拥有`orPerm`对应的权限，即可继续执行该方法，否则该方法会被拦截。 #### 3.2.3 @CheckPerm > 权限核验 > 依赖于鉴权服务 | 参数 | 类型 | 说明 | 默认值 | | ------ | ------ | -------- | ------ | | value | string | 权限标识 | * | | orRole | string | 角色标识 | | 该注解用于方法拦截，当前登录用户拥有`value`对应的权限**或**拥有`orRole`对应的角色，即可继续执行该方法，否则该方法会被拦截。 --- ## 4. 接口防护 ### 4.1 幂等控制 @Idempotent 支持基于 Redis 或本地降级的幂等性保证： | 实现方式 | 说明 | |---------|------| | Redis 版本 | 基于 `SET NX` 原子操作，分布式环境下推荐使用 | | 本地降级 | 基于 `ConcurrentHashMap`，单机环境或 Redis 不可用时使用 | **注解参数：** | 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | value | String | 幂等 key 前缀 | idempotent | | keyType | KeyType | key 获取类型 | HEADER | | paramName | String | 参数名称（PARAM 模式） | idempotentKey | | keySpEL | String | SpEL 表达式（SPEL 模式） | | | expire | int | 结果缓存时长（秒） | 60 | | message | String | 提示信息 | 请勿重复提交 | **三种 KeyType 模式：** - **HEADER**（默认）：从请求头 `Idempotent-Key` 获取 - **PARAM**：从方法参数获取 - **SPEL**：通过 SpEL 表达式动态构建 **使用示例：** ```java // HEADER 模式（默认） @Idempotent(value = "pay", expire = 30, message = "支付处理中") @PostMapping("/pay") public ResponseDTO pay(@RequestBody PayDTO pay) { // 支付逻辑 } // PARAM 模式 @Idempotent(value = "order", keyType = KeyType.PARAM, paramName = "orderNo") @PostMapping("/order") public ResponseDTO createOrder(@RequestBody OrderDTO order) { // 业务逻辑 } // SPEL 模式 @Idempotent(value = "refund", keyType = KeyType.SPEL, keySpEL = "#dto.orderNo") @PostMapping("/refund") public ResponseDTO refund(@RequestBody RefundDTO dto) { // 业务逻辑 } ``` **自动选择机制**：配置 `spring.redis.host` 时自动启用 Redis 版本，否则降级为本地缓存版本（基于 `ConcurrentHashMap` + 惰性过期）。 ### 4.2 表单防重复提交 @FormLock > 表单重复提交拦截 | 参数 | 类型 | 说明 | 默认值 | | ----- | ------ | ---------------- | ------ | | key | string | 锁定key 别名 | ALL | | value | string | 锁定key 别名 | ALL | | sec | int | 锁定时长 单位 秒 | 5 | 该注解会优先从登录ID和key判断进行拦截，如果没有登录，会从IP和key进行拦截限制判定。 **使用示例：** ```java @FormLock("rbac-reg") public ResponseDTO demoMethod(@RequestBody @Validated DemoParams params){ // todo } ``` ### 4.3 接口限流 @RateLimit 基于 Redis + 滑动窗口算法，支持三种限流维度： | 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | key / value | String | 限流 key 前缀 | rate_limit | | permits | int | 窗口内允许的请求次数 | 1 | | refresh | int | 窗口大小（秒） | 60 | | limitType | LimitType | 限流维度 | IP | | message | String | 拒绝提示 | 请求过于频繁，请稍后再试 | **三种限流模式：** - **IP**：按客户端 IP 限流 - **USER**：按登录用户限流（未登录时降级为 IP） - **GLOBAL**：全局限流 **使用示例：** ```java // 按 IP 限流：60 秒内最多 1 次（短信验证码场景） @RateLimit(key = "sms", permits = 1, refresh = 60, limitType = LimitType.IP, message = "验证码已发送，请稍后重试") @PostMapping("/sms/send") public ResponseDTO sendSms(@RequestBody SmsDTO dto) { ... } // 按用户限流：60 秒内最多 30 次 @RateLimit(key = "api", permits = 30, refresh = 60, limitType = LimitType.USER) @GetMapping("/data") public ResponseDTO queryData() { ... } // 全局限流：60 秒内最多 100 次 @RateLimit(key = "search", permits = 100, refresh = 60, limitType = LimitType.GLOBAL) @GetMapping("/search") public ResponseDTO search(@RequestParam String q) { ... } ``` 无 Redis 时自动降级为本地 `ConcurrentHashMap` 实现。 ### 4.4 防护注解联合使用 ```java @FormLock("order-submit") @RateLimit(key = "order", permits = 10, refresh = 3600, limitType = LimitType.USER, message = "每小时最多下单 10 次") @PostMapping("/order") public ResponseDTO submitOrder(@RequestBody OrderDTO dto) { ... } ``` --- ## 5. AI 智能能力 ### 5.1 AI 平台配置 `lucy-spring-boot-starter` 基于 LangChain4j 集成 AI 能力，默认接入 DeepSeek 模型，支持多平台配置。 **配置参数：** | 参数 | 说明 | 默认值 | |------|------|--------| | baseUrl | API 地址 | `https://api.deepseek.com/v1` | | model | 模型名称 | `deepseek-v4-flash` | | maxTokens | 最大 Token 数 | 5000 | | temperature | 温度参数 | 0.3 | | timeout | 超时时间（秒） | 30 | | responseFormat | 响应格式 | `json_object` | ```properties # 默认平台配置 lucy.ai.api-key=your-api-key lucy.ai.base-url=https://api.deepseek.com/v1 lucy.ai.model=deepseek-v4-flash ``` 支持注册多个命名平台，通过注解中的 `platform` 参数选择。 ### 5.2 字段驱动校验与增强 @AiDriven + @AiField 通过 AI 对请求字段进行自动校验或数据增强。 **@AiDriven** 标注在方法上，**@AiField** 标注在实体字段上。 **@AiField 参数：** | 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | value | String | 校验规则或增强指令 | 必填 | | mode | AiField.Mode | 模式 | VALIDATE | **两种模式：** - **VALIDATE**：AI 校验字段值是否符合规则，不合规时抛出异常 - **ENRICH**：AI 根据上下文自动生成字段值 **使用示例：** ```java public class UserCreateDTO { @AiField("name must not be empty and length 2-50") private String name; @AiField("age must be between 1 and 150") private Integer age; @AiField(value = "generate a bio based on name and age", mode = AiField.Mode.ENRICH) private String bio; } @AiDriven @PostMapping("/user") public ResponseDTO createUser(@RequestBody UserCreateDTO dto) { // dto 经过 AI 校验和增强后进入业务逻辑 return ResponseDTO.succ(); } ``` ### 5.3 内容安全审计 @AiAudit 通过 AI 对请求内容进行风险评级，超过阈值时自动拦截。 | 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | platform | String | AI 平台名称 | default | | prompt | String | 审计提示词，优先级大于 promptId | | | promptId | String | 提示词模板 ID | | | blockThreshold | AuditLevel | 拦截阈值 | HIGH | **风险等级：** LOW(1) / WARN(2) / HIGH(3) **使用示例：** ```java @AiAudit(prompt = "检查该申请是否合理合规", blockThreshold = AuditLevel.HIGH) @PostMapping("/apply") public ResponseDTO submitApply(@RequestBody ApplyDTO dto) { ... } @AiAudit(prompt = "审核评论内容是否包含不当言论", blockThreshold = AuditLevel.WARN) @PostMapping("/review") public ResponseDTO submitReview(@RequestBody ReviewDTO dto) { ... } ``` ### 5.4 智能路由分发 @AiRouter 通过 AI 根据请求内容动态选择目标方法执行。 | 参数 | 类型 | 说明 | |------|------|------| | platform | String | AI 平台名称 | | rules | @Rule[] | 路由规则数组 | | prompt | String | 系统提示词 | **@Rule 参数：** | 参数 | 说明 | |------|------| | rule | 自然语言路由规则描述 | | method | 目标方法名称 | **使用示例：** ```java @AiRouter( rules = { @AiRouter.Rule(rule = "when priority is HIGH", method = "handleUrgent"), @AiRouter.Rule(rule = "when priority is LOW", method = "handleNormal") }, prompt = "You are a ticket routing assistant." ) @PostMapping("/ticket/dispatch") public ResponseDTO dispatch(@RequestBody TicketDTO dto) { return ResponseDTO.succMsg("default dispatch"); } public ResponseDTO handleUrgent(TicketDTO dto) { return ResponseDTO.succMsg("urgent: " + dto.getContent()); } public ResponseDTO handleNormal(TicketDTO dto) { return ResponseDTO.succMsg("normal: " + dto.getContent()); } ``` ### 5.5 AI 调用追踪 @AiTrace 记录 AI 模型调用的输入、输出、提示词，支持敏感信息脱敏。 | 参数 | 类型 | 说明 | 默认值 | |------|------|------|--------| | recordInput | boolean | 记录输入 | true | | recordOutput | boolean | 记录输出 | true | | recordPrompt | boolean | 记录提示词 | true | | maskSensitive | boolean | 脱敏敏感信息 | true | 脱敏范围：手机号（138****1234）、身份证号、银行卡号、邮箱。 **使用示例：** ```java @AiTrace(recordInput = true, recordOutput = true, maskSensitive = true) @AiAudit(prompt = "审核内容安全性", blockThreshold = AuditLevel.WARN) @PostMapping("/content") public ResponseDTO submitContent(@RequestBody ContentDTO dto) { ... } ``` 追踪事件通过 Spring 事件机制发布，可自定义监听： ```java @Component public class AiTraceListener { @EventListener public void onAiTrace(AiTraceEvent event) { AiTraceRecord record = event.getTraceRecord(); // 持久化或日志记录 } } ``` ### 5.6 自定义提示词服务 实现 `AiPromptService` 接口可自定义提示词模板： ```java @Component public class MyPromptService implements AiPromptService { @Override public String getPrompt(String id) { // 从数据库或配置文件获取 return promptMap.getOrDefault(id, ""); } } ``` ### 5.7 AI切面执行顺序 执行链路：字段校验（Order 20）→ 内容审计（Order 25）→ 路由分发（Order 30）→ 原始方法 --- ## 6. 缓存与数据服务 ### 6.1 Redis 缓存服务 `lucy-spring-boot-starter`集成默认的缓存策略，配置`spring.redis.host`后自动开启`Redis`缓存策略。 ```properties ###################### Redis 配置(可选，不配置 RedisCache 不生效) ############################ # Redis数据库索引（默认为0） spring.redis.database=0 # Redis服务器地址 spring.redis.host=127.0.0.1 # Redis服务器连接端口 spring.redis.port=6379 # Redis服务器连接密码 spring.redis.password=123456 # 连接池最大连接数（使用负值表示没有限制） spring.redis.jedis.pool.max-active=200 spring.data.redis.repositories.enabled = false # 连接池中的最大空闲连接 spring.redis.jedis.pool.max-idle=10 # 连接池中的最小空闲连接 spring.redis.jedis.pool.min-idle=0 # 连接超时时间（毫秒） spring.redis.timeout=2000ms # 最大等待时间 (毫秒) spring.redis.jedis.pool.max-wait=-1ms ``` **使用示例：** ```java @Autowired RedisCache redisCache; ``` **方法列表：** | 方法 | 功能 | 返回值 | | :----------------------------------------------------------- | :------------------------- | :------ | | setCacheObject(final String key, final T value) | 设置缓存 | void | | setCacheObject(final String key, final T value, final Integer timeout, final TimeUnit timeUnit) | 设置定时缓存 | void | | expire(final String key, final long timeout) | 设置过期时间,默认单位（s） | boolean | | expire(final String key, final long timeout, final TimeUnit unit) | 设置过期时间 | boolean | | getCacheObject(final String key) | 查询缓存信息 | object | | deleteObject(final String key) | 删除缓存信息 | object | | deleteObject(final Collection collection) | 批量删除缓存信息 | void | | keys(final String pattern) | 获取符合前缀的缓存key列表 | list | ### 6.2 统一响应模型 **ResponseDTO** 封装统一响应格式： | 静态方法 | 说明 | |---------|------| | `succ()` | 成功无数据（200） | | `succData(T data)` | 成功带数据（200） | | `succMsg(T data)` | 成功带消息（200） | | `wrap(HttpStatus)` | 自定义状态 | | `wrap(HttpStatus, T data)` | 自定义状态带数据 | ```java return ResponseDTO.succ(); return ResponseDTO.succData(user); return ResponseDTO.succMsg("操作成功"); ``` **PageResultDTO** 分页结果： | 字段 | 说明 | |------|------| | number | 当前页码 | | size | 每页大小 | | totalElements | 总记录数 | | totalPages | 总页数 | | content | 数据列表 | **PageParamDTO** 分页参数（默认 pageNum=0, pageSize=30, sortBy=createdTime, order=DESC）。 ### 6.3 全局异常处理 `lucy-spring-boot-starter`存在默认的异常拦截处理策略，默认开启，如果需要关闭，需要在配置文件中声明。 ```properties # 异常处理策略 lucy.exception.handle=false ``` | 异常类型 | 处理结果 | |---------|----------| | `BusinessException` / `AsyncBusinessException` | 自定义业务异常 | | `MethodArgumentNotValidException` | 参数校验失败 (400) | | `MissingServletRequestParameterException` / `IllegalArgumentException` | 参数错误 (400) | | `AccessDeniedException` | 未授权 (401) | | `NoHandlerFoundException` | 404 | | `HttpRequestMethodNotSupportedException` | 405 | | `HttpMediaTypeNotSupportedException` | 415 | | `NullPointerException` | 500 | --- ## 7. 基础设施 ### 7.1 虚拟线程池 基于 JDK 21 Virtual Thread 实现： - 无需传统线程池调优 - 支持 `@Async` 异步任务 提供两种执行器，按需选择： | 执行器 | 上下文透传 | 使用方式 | |--------|-----------|---------| | `threadExecutor` | ❌ | `@Async` | | `decoratedThreadExecutor` | ✅ 自动透传 RequestAttributes | `@Async("decoratedThreadExecutor")` | ```java @Component public class AsyncTask { // 使用默认虚拟线程执行器，无上下文透传 @Async public CompletableFuture loadUserAsync(String id) { User user = userRepository.findById(id).orElse(null); return CompletableFuture.completedFuture(user); } // 使用装饰器执行器，自动透传 Web 请求上下文 @Async("decoratedThreadExecutor") public CompletableFuture loadUserWithContextAsync(String id) { // 此处可访问 HttpServletRequest、AuthService 等请求作用域 Bean User user = userRepository.findById(id).orElse(null); return CompletableFuture.completedFuture(user); } } ``` ### 7.2 文件服务 FileApi 提供文件预览（inline）和下载（attachment）的统一接口，内置完整的 MIME 类型映射。 ```java @Autowired FileApi fileApi; // 文件预览 fileApi.preview(inputStream, request, "report.pdf"); // 文件下载 fileApi.download(inputStream, request, "data.xlsx"); ``` ### 7.3 CORS 跨域配置 默认开启全局跨域，允许所有来源和方法： ```properties # 允许所有来源，支持 GET/POST/PUT/OPTIONS/DELETE，凭证 true，预检缓存 3600s ``` 无外部实现时默认按此配置执行。如需自定义，声明 `WebMvcConfigurer` Bean 即可叠加规则： ```java @Configuration public class CustomCorsConfig implements WebMvcConfigurer { @Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping("/api/**") .allowedOriginPatterns("https://yourdomain.com") .allowedMethods("GET", "POST") .allowCredentials(true) .maxAge(1800); } } ``` ### 7.4 API 文档配置 --- ## 8. 附录 ### 8.1 自定义注解速查表 | 注解 | 目标 | 模块 | 说明 | |------|------|------|------| | `@AuthLogin` | Method/Type | core.auth | 校验用户登录态 | | `@CheckRole` | Method/Type | core.auth | 角色核验，支持 orPerm | | `@CheckPerm` | Method/Type | core.auth | 权限核验，支持 orRole | | `@Idempotent` | Method | starter | 幂等控制 | | `@FormLock` | Method | starter | 防重复提交 | | `@RateLimit` | Method | starter | 接口限流 | | `@AiDriven` | Method | ai | AI 字段处理触发 | | `@AiField` | Field | ai | AI 字段规则定义 | | `@AiAudit` | Method/Type | ai | AI 内容审计 | | `@AiRouter` | Method | ai | AI 路由分发 | | `@AiTrace` | Method/Type | ai | AI 调用追踪 | ### 8.2 项目结构 ``` lucy-spring-boot-starter ├── org.lboot.core # 核心模块 │ ├── auth # 认证鉴权 │ ├── config # 配置类 │ ├── domain # 领域对象 │ ├── exception # 异常类 │ └── service # 服务接口 ├── org.lboot.jpa # JPA 数据模块 │ ├── entity # 实体基类 │ ├── service # 数据访问服务 │ ├── jpa # CRUD 抽象实现 │ ├── converter # 类型转换器 │ └── generator # ID 生成器 ├── org.lboot.starter # Starter 模块 │ ├── auto # 自动配置 │ ├── anno # 自定义注解 │ ├── aspect # AOP 切面 │ ├── handler # 异常处理器 │ ├── redis # Redis 缓存 │ └── config # 配置类 ├── org.lboot.ai # AI 智能模块 │ ├── anno # 自定义注解 │ ├── aspect # AOP 切面 │ ├── auto # 自动配置 │ ├── config # 配置类 │ ├── service # AI 服务 │ ├── constant # 常量定义 │ ├── event # 追踪事件 │ └── vo # 值对象 └── org.lboot.thread # 虚拟线程模块 ``` ### 8.3 更新日志 **2.1.0-beta** - 新增 AI 智能模块（@AiDriven / @AiField / @AiAudit / @AiRouter / @AiTrace） - 新增接口限流注解 @RateLimit（IP / USER / GLOBAL） - 新增文件服务 FileApi（预览 / 下载 / MIME 映射） - 新增 CORS 跨域自动配置 - 新增统一响应模型（ResponseDTO / PageResultDTO / PageParamDTO） - 新增 API 文档集成（Knife4j + Springdoc OpenAPI） - 新增数据校验工具 ValidationUtil - Idempotent 注解支持 keyType（HEADER / PARAM / SPEL） **2.0.0** - 升级至 JDK 21 + Spring Boot 3.x - 时间字段从 `Date` 升级为 `LocalDateTime` - 雪花ID生成器优化为静态单例，提升性能 - 数据库配置支持环境变量，增强部署灵活性 - 线程池升级为 JDK 21 虚拟线程 - 文档统一移至 `docs/` 目录 **1.1.2** - 将`JPA`功能特性设置为拓展包 - `Redis`依赖排除，根据配置文件自动判定注入 - 移除`lucy-core`，`lucy-redis`库依赖 [更多...](https://gitee.com/lboot/lucy-spring-boot-starter/releases) ### 8.4 License [MIT License](LICENSE)