# quick-start-boot-framwork **Repository Path**: roggie/quick-start-boot-framwork ## Basic Information - **Project Name**: quick-start-boot-framwork - **Description**: 一个面向 Spring Boot 的基础设施能力框架,提供可靠消息、MQTT 接入、Netty 协议服务端、统一缓存、统一 JSON、可观测性和敏感字段脱敏等通用模块。 - **Primary Language**: Java - **License**: Apache-2.0 - **Default Branch**: develop - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2025-04-25 - **Last Updated**: 2026-11-11 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # quick-start-boot-framwork ## 项目简介 这是一个基于 Maven 的多模块快速启动框架仓库,当前主要模块包括: - `quick-start-boot-core` - `quick-start-boot-web` - `quick-start-boot-upload` - `quick-start-boot-upload-s3` - `quick-start-boot-ratelimit` - `quick-start-boot-idempotent` - `quick-start-boot-codegen-annotations` - `quick-start-boot-codegen-processor` - `quick-start-boot-masking` - `quick-start-boot-json` - `quick-start-boot-mqtt` - `quick-start-boot-acl` - `quick-start-boot-spring-netty` - `quick-start-boot-cache` - `quick-start-boot-sample-order` ## 基础异常与错误码 ### 最小接入示例 非 Web 服务只需要 `quick-start-boot-core`。业务枚举实现 `ErrorCode`,抛出 `BusinessException`: ```java import quick.start.boot.core.exception.BusinessException; import quick.start.boot.core.exception.ErrorCode; enum OrderErrorCode implements ErrorCode { ORDER_CLOSED("10001", "订单已关闭"); private final String code; private final String message; OrderErrorCode(String code, String message) { this.code = code; this.message = message; } @Override public String getCode() { return code; } @Override public String getMessage() { return message; } } class OrderService { void check(boolean closed) { if (closed) { throw new BusinessException(OrderErrorCode.ORDER_CLOSED); } } } ``` ### 示例逐段解释 - `ErrorCode` 只约定字符串错误码和默认消息;领域码由业务枚举管理,避免在调用处重复拼字符串。 - 抽象 `BaseException` 负责错误码、消息、cause,不包含 HTTP 状态;技术模块可继承它定义异常。 - `BusinessException extends BaseException` 表示可预期的业务失败,消息允许对外展示。 技术异常不因继承 `BaseException` 就变成业务异常。 - `CommonErrorCode` 提供 `BUSINESS_ERROR`、`INVALID_ARGUMENT`、`INTERNAL_ERROR` 等通用码; 业务专属码优先放在自己的枚举中,实现相同接口即可使用。 - 未登录、登录失效、权限不足分别可抛出 `NotAuthenticatedException`、`LoginExpiredException`、 `PermissionDeniedException`,均继承 `BusinessException`。支持无参或传入 `Throwable cause`, 公开消息固定使用对应枚举默认值,不透传凭证、权限详情或 cause 消息。 - `getError()` 获取错误码对象,`getErrorCode()` 获取稳定字符串码,`getMessage()` 获取实际消息。 ### 数字错误码规则 枚举名称表达语义,对外错误码使用显式指定的数字字符串,例如 `JsonErrorCode.JSON_SERIALIZE_ERROR.getCode()` 返回 `"4002"`。 `ErrorCode.getCode()` 和 `ApiResponse.code` 保持 `String`,JSON 返回 `"code":"4002"`,前端按字符串比较。 | 号段 | 用途 | 已分配错误码 | | --- | --- | --- | | `0` | 成功 | `ApiResponse.success` | | `1000–1999` | core 通用错误 | `1001` 业务处理失败、`1002` 参数不正确、`1003` 服务器内部错误 | | `2000–2999` | 认证与权限 | `2001` 未登录、`2002` 登录失效、`2003` 权限不足 | | `3000–3999` | 请求控制 | `3001` 限流、`3002` 重复提交 | | `4000–4999` | JSON 技术错误 | `4001` 配置、`4002` 序列化、`4003` 反序列化、`4004` 类型转换 | | `5000–5999` | HTTP 框架错误 | `5000 + HTTP状态码`,如 `5400`、`5404`、`5500` | | `6000–9999` | 其他框架组件预留 | 新组件接入统一 `ErrorCode` 模型时先登记子号段 | | `10000–99999` | 应用业务错误 | 应用自行划分,如订单 `10000–10999`、库存 `11000–11999` | 框架四位码的首位表示类别,后三位在对应号段内分配;HTTP 号段的后三位直接沿用标准状态码。 应用五位码可按“前两位领域 + 后三位序号”分配,如 `10001` 表示订单已关闭。 这只是错误标识规则,HTTP 状态和错误类别分别由处理器、异常类型决定;业务失败仍返回 HTTP 200。 - 同一响应协议内错误码须唯一,`0` 只用于成功;新增码先在对应枚举和本文登记。 `BaseException`(含业务、技术异常)及 `ApiResponse.failure` 会拒绝 `"0"`,防止失败响应被前端判为成功。 - 固定码显式写入枚举,不使用 `ordinal()`、`name()` 或哈希生成;已发布码不得改义或复用,废弃后保留占用。 - 组件内部调用使用枚举,前端集中定义数字字符串常量;不根据消息文本或枚举名称判断结果。 - 接口保留扩展能力,不在运行时强制校验应用 `ErrorCode` 的数字格式;新业务按上述规则分配。 ### 常用构造与断言 ```java throw new BusinessException(OrderErrorCode.ORDER_CLOSED); throw new BusinessException(OrderErrorCode.ORDER_CLOSED, "该订单已取消,无法付款"); // catch 中可保留 cause;公开消息须由业务明确提供,不直接使用 cause.getMessage()。 throw new BusinessException(OrderErrorCode.ORDER_CLOSED, "订单不可用", cause); ``` `CheckUtil.notNull(value, OrderErrorCode.ORDER_CLOSED)`、 `CheckUtil.isTrue(condition, CommonErrorCode.INVALID_ARGUMENT, "订单状态不正确")` 也会抛出 `BusinessException`。错误码不能为空;未覆盖消息时使用枚举默认消息,显式空白消息会被拒绝。 ### 模块边界与迁移 `core` 不再依赖 Spring Web、Servlet、Tomcat 和 Bean Validation API。 HTTP 工具 `AnnotationHelper`、`AnnotationScanner` 移到 `quick.start.boot.web.utils`,由 Web 模块承载。 已有 Spring、Redis、AOP 等 core 依赖保持当前组织方式,本次仅拆除 Web 边界。 旧 `ErrorCodeException`、`ErrorCodeEnums` 已删除;原来直接构造 `BaseException` 或手写字符串码的调用, 改为 `new BusinessException(业务错误码枚举)`。`BaseException` 子类构造也改为传入 `ErrorCode`; JSON 技术异常使用 `JsonErrorCode`,具体异常类型保留,错误码改为上述数字字符串。 原公共名称码、`JSON_*` 名称码及 `HTTP_*` 名称码已迁移到数字码;前端码表、日志告警条件与 按错误码匹配的事务处理配置需同步更新,组件不会在同一字段同时返回新旧两套码。 这是源码不兼容调整,下游应用需要同步迁移,不能直接替换二进制包。 ## HTTP 统一异常处理与返回值 ### 最小可运行示例 Spring Boot 3 / Spring MVC 应用显式引入 `quick-start-boot-web`(会传递依赖 core 和 MVC starter), 依赖版本由父 POM 管理: ```xml org.dw quick-start-boot-web ``` 在 `application.yml` 显式启用: ```yaml quick: start: boot: web: exception-handling: enabled: true ``` Controller 示例: ```java import java.util.Map; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import quick.start.boot.core.exception.BusinessException; import quick.start.boot.web.ApiResponse; @RestController public class OrderController { @GetMapping("/orders/check") public ApiResponse> check(@RequestParam boolean closed) { if (closed) { throw new BusinessException(OrderErrorCode.ORDER_CLOSED); } return ApiResponse.success(Map.of("available", true)); } } ``` ### 示例逐段解释 - `OrderErrorCode` 使用上一节的业务枚举;自动配置只对 Servlet Web 应用生效,无需扫描组件包。 - 成功返回 HTTP 200 和 `{"code":"0","msg":"成功","data":{"available":true}}`。 - 业务异常同样返回 HTTP 200 和 `{"code":"10001","msg":"订单已关闭","data":null}`。 仅 `BusinessException` 的业务消息允许公开展示。 - 客户端通过响应体的 `code` 判断业务结果:`"0"` 表示成功,其他业务码表示具体失败;不能仅凭 HTTP 200 判断业务成功。 - `ApiResponse.code` 始终为字符串,支持业务自定义码;它与 HTTP 状态相互独立。 MVC 框架错误使用 `5000 + HTTP状态码`,例如 `5400`、`5404`、`5500`。 - 成功结果由 Controller 显式调用 `ApiResponse.success`,组件只统一异常响应。 ### 常用属性与默认处理 | 属性 | 默认值 | 说明 | | --- | --- | --- | | `quick.start.boot.web.exception-handling.enabled` | `false` | 引入 Web 模块后显式启用 | | 异常或场景 | HTTP 状态 | 行为 | | --- | --- | --- | | `BusinessException` | 200 | 通过业务 ErrorCode 区分失败,保留公开消息 | | 其他 `BaseException`(如 JSON 技术异常) | 500 | 保留错误码,消息统一为“服务器内部错误” | | 缺少参数、类型转换、JSON 解析、Bean Validation 校验失败 | 400 | 返回统一参数错误消息,不回传拒绝值和原始异常 | | MVC 方法返回值校验失败 | 500 | 保留 Spring 的服务端错误语义 | | 无接口或静态资源、方法不支持、媒体类型不支持、上传超限 | 404 / 405 / 415 / 413 | 保留 Spring MVC 状态和协议响应头,例如 `Allow` | | `ResponseStatusException`、`ErrorResponse`、异常类上的 `@ResponseStatus` | 声明的状态 | 包含包装异常的 cause 链,从外到内采用首个声明状态,保留相应响应头并隐藏内部 reason/detail | | 其他未处理异常 | 500 | 返回“服务器内部错误”,服务端记录异常堆栈 | 常见框架异常的具体覆盖如下,均返回相同的 `code/msg/data` 结构: | 异常类型 | 处理入口 | HTTP 状态 / 响应 `code` | | --- | --- | --- | | `DataAccessException` 及其子类 | 通用兜底,记录服务端堆栈,不回传 SQL、表名或连接信息 | 500 / `5500` | | `NoHandlerFoundException`、`NoResourceFoundException` | Spring MVC 父处理器,统一重写响应体 | 404 / `5404` | | `HttpRequestMethodNotSupportedException` | Spring MVC 父处理器,保留 `Allow` 响应头 | 405 / `5405` | | `MethodArgumentTypeMismatchException` | Spring MVC 父处理器的类型转换分支 | 400 / `5400` | | `jakarta.validation.ConstraintViolationException` | 显式区分参数约束与方法返回值约束失败 | 输入 400 / `5400`;返回值 500 / `5500` | | `org.springframework.validation.BindException` | 显式处理普通绑定失败 | 400 / `5400` | | `MethodArgumentNotValidException` | Spring MVC 父处理器,参数绑定或校验失败 | 400 / `5400` | 框架异常复用 `ResponseEntityExceptionHandler` 的分发机制,无需为每种类型重复添加 `@ExceptionHandler`。 普通 `BindException` 在 Spring 6 中不再由父处理器覆盖,单独补充处理;其子类 `MethodArgumentNotValidException` 仍使用父处理器更具体的匹配。参数错误统一提示“请求参数不正确”, 不直接回传异常消息、校验拒绝值或任意自定义校验消息。 `@Validated` 的 AOP 方法校验同样区分输入与输出:约束路径含 `RETURN_VALUE` 节点时返回 500, 参数约束失败返回 400;服务端返回值校验失败会记录异常堆栈。 数据库唯一约束冲突等只有在业务明确识别后才能转换为对应 `BusinessException`; 不能将所有 `DataAccessException` 当成重复提交或其他业务失败。 以下可预期失败在 MVC 中均由现有业务处理器返回 HTTP 200,无需另写 Advice: | 异常 | `CommonErrorCode` | 响应 `code` | 默认公开消息 | | --- | --- | --- | --- | | `NotAuthenticatedException` | `AUTHENTICATION_REQUIRED` | `2001` | 请先登录 | | `LoginExpiredException` | `LOGIN_EXPIRED` | `2002` | 登录已失效,请重新登录 | | `PermissionDeniedException` | `PERMISSION_DENIED` | `2003` | 无权执行该操作 | | `RateLimitExceededException` | `RATE_LIMITED` | `3001` | 请求过于频繁,请稍后重试 | | `DuplicateExecutionException` | `DUPLICATE_REQUEST` | `3002` | 请求重复,请勿重复提交 | 认证、权限异常及公共码位于 core,不依赖 Web 或 Spring Security;应用负责识别登录态、凭证失效和权限。 这部分提供错误模型,`quick-start-boot-acl` 当前仍未实现认证鉴权流程。 限流和重复请求异常分别由对应组件抛出,Web 通过 `BusinessException` 处理它们,生产依赖无需互相引入。 使用 `@Valid` / 方法约束时,业务应用须引入 `org.springframework.boot:spring-boot-starter-validation` 或提供自己的校验实现。Web 模块生产依赖仅包含校验 API,core 不引入校验依赖。 原 `PageResult` 是带 `map` 的进程内转换工具,并非完整的 HTTP 返回协议。 保留它的 `code/msg/data`、`getError()` 和转换行为,但 `error` 不再参与 JSON 序列化, 防止堆栈、cause、内部消息泄露。新 HTTP 接口推荐使用 `ApiResponse`;旧接口迁移时注意整数码与字符串码的差异。 `ResPayLoad` 属于设备二进制协议应答,不参与 HTTP 返回值统一。 ### 进阶场景与边界 处理器以 `Ordered.LOWEST_PRECEDENCE` 运行。应用可使用更高优先级的 `@RestControllerAdvice` 处理特定异常、覆盖公开提示,或将应用特有异常转换为 `BusinessException`。 组件不把通用 `IllegalArgumentException` 一律当作客户端错误,内部编程错误默认保留 HTTP 500。 需要完整替换时,声明 `GlobalWebExceptionHandler` 子类 Bean,默认 Bean 自动退让。 作用范围为 DispatcherServlet 处理的 MVC 异常;Filter、Spring Security 认证/鉴权链、 容器 `/error`、后台线程及 WebFlux 不由此 Advice 处理,应在各自入口接入对应处理器。 例如,应用的 Servlet Filter 已确认登录凭证失效时,可使用注入的 `ObjectMapper` 直接写入统一响应并结束处理: ```java // response 为 HttpServletResponse,objectMapper 由应用注入。 response.setStatus(HttpServletResponse.SC_OK); response.setContentType(MediaType.APPLICATION_JSON_VALUE); objectMapper.writeValue(response.getOutputStream(), ApiResponse.failure(CommonErrorCode.LOGIN_EXPIRED)); return; // 不再调用 filterChain.doFilter ``` 以上使用 `jakarta.servlet.http.HttpServletResponse`、`org.springframework.http.MediaType`、 `quick.start.boot.core.enums.CommonErrorCode` 和 `quick.start.boot.web.ApiResponse`。 Spring Security 的 `AuthenticationEntryPoint` / `AccessDeniedHandler` 也可按同样方式写响应, 应用须在各自认证链配置中注册;仅抛出 core 异常不会自动接入这些入口。 前端通过 `"2001"` / `"2002"` 引导登录,通过 `"2003"` 提示无权操作; `"3001"` 提示稍后重试,`"3002"` 提示避免重复提交。 响应已经提交、流式下载已经写出或客户端断连时无法保证追加 JSON 错误体; 客户端须接受 JSON,不能依赖不支持 JSON 的 `Accept` 得到统一返回体。 Netty、MQTT 等协议继续使用各自异常处理链路。 ## 幂等与限流组件 ### 最小可运行示例 两个模块独立接入、独立启用,依赖版本由本仓库父 POM 管理: ```xml org.dw quick-start-boot-ratelimit org.dw quick-start-boot-idempotent ``` 准备 Redis,配置连接及组件开关: ```yaml spring: data: redis: host: localhost port: 6379 quick: start: boot: ratelimit: enabled: true idempotent: enabled: true ``` 在 Spring 管理的同步业务方法上使用两个独立注解: ```java import org.dw.ratelimit.RateLimit; import org.dw.idempotent.Idempotent; import org.springframework.stereotype.Service; @Service public class OrderService { @RateLimit(resource = "order:create", key = "#p0", limit = "20", window = "1s") @Idempotent(resource = "order:create", key = "#p1", retention = "24h") public String create(String userId, String requestId) { // 在这里调用有数据库唯一约束保护的业务事务。 return requestId; } } ``` ### 示例解释 - `RateLimitOperations.acquire(RateLimitRequest)` 是限流编程接口;`IdempotentOperations.execute(IdempotentRequest, IdempotentAction)` 是幂等编程接口。两者互不依赖,可分别提供自定义 Bean 替换默认实现。 - `resource` 标识业务,`key` 是 SpEL,支持 `#p0`、`#a0` 和保留参数名的 `#userId`;也可用 `keyResolver` 指定类型化解析器。限流两者均不填写表示该业务的全局额度;幂等必须选择一种入口提供业务请求标识,不自动摘要整个请求。 - 限流使用 Redis 原子固定窗口,从首个请求起计时;超额抛出 `RateLimitExceededException`,结果包含剩余额度和窗口剩余时间。窗口边界可能短时间出现两倍阈值的突发。 - 幂等先原子获取执行租约,重复调用抛出 `DuplicateExecutionException`;成功后保留防重记录,失败后仅释放自己的租约。重复成功请求会被拒绝,不重放第一次的返回值。 - 注解遵循 Spring AOP 代理规则,Bean 内部自调用不生效。默认先限流再幂等,因此重复请求也消耗限流额度。引入并启用 `quick-start-boot-web` 后,限流和重复请求异常自动返回 HTTP 200,分别使用 `"3001"`、`"3002"`;没有 Web 处理器时由调用方捕获。 - `RateLimitExceededException`、`DuplicateExecutionException` 的构造签名保留,现继承 `BusinessException`;`getMessage()` 改为面向用户的统一提示。内部资源标识改用 `getResource()` 读取,限流的 `getResult()` 保留,均不进入统一响应体。`IdempotentLeaseLostException` 表示执行结果无法安全确认,Redis 故障同样属于技术失败,默认仍返回 HTTP 500。 - 注解可声明在业务接口或实现方法上,实现方法的规则优先;JDK 与 CGLIB 代理使用相同的注解查找逻辑。启动检查拒绝 `private`、`static` 方法;CGLIB 下拒绝 `final` 方法,JDK 下要求方法属于代理暴露的接口,接口调用可以拦截实现类的 `final` 方法。关闭 Spring AOP 时,已有带注解的业务 Bean 不会静默放行,而是启动报错。 ### 上下文取键与类型化解析器 上下文取键推荐使用类型化解析器。两个模块分别定义 `RateLimitKeyResolver` 与 `IdempotentKeyResolver`,不共享业务接口。以下限流解析器由应用注册为 Spring Bean: ```java import org.dw.ratelimit.KeyResolutionContext; import org.dw.ratelimit.RateLimitKeyResolver; import org.springframework.stereotype.Component; @Component public class LoginUserKeyResolver implements RateLimitKeyResolver { private final LoginContext loginContext; public LoginUserKeyResolver(LoginContext loginContext) { this.loginContext = loginContext; } @Override public String resolve(KeyResolutionContext context) { return loginContext.requireUserId(); } } // 业务方法上: @RateLimit(resource = "order:create", keyResolver = LoginUserKeyResolver.class) ``` `LoginContext` 是应用自己的上下文服务,可封装登录态或 ThreadLocal。解析器可通过 `context.target()`、`context.method()` 和 `context.arguments()` 读取调用信息;参数数组使用防御性复制。幂等使用独立接口,示例: ```java import org.dw.idempotent.IdempotentKeyResolver; import org.dw.idempotent.KeyResolutionContext; @Component public class RequestIdKeyResolver implements IdempotentKeyResolver { @Override public String resolve(KeyResolutionContext context) { var attributes = (ServletRequestAttributes) RequestContextHolder.currentRequestAttributes(); return attributes.getRequest().getHeader("X-Request-Id"); } } @Idempotent(resource = "order:create", keyResolver = RequestIdKeyResolver.class) ``` `key` 与 `keyResolver` 不得同时填写。解析器类型受 Java 编译器约束;启动时要求该类型恰好对应一个 Bean(多个候选即使有 `@Primary` 也拒绝)。组件使用 Spring 管理的实例,支持构造注入和作用域代理,不自行反射创建解析器。使用 JDK 代理时应引用代理暴露的解析器接口类型。 启用注解时启动检查方法规则、SpEL 语法、表达式中引用的 Bean 是否存在,以及解析器缺失/重复/入口冲突。不会调用解析器或求值表达式,因此业务上下文、返回值及复杂表达式的方法可调用性仍在运行时检查。懒加载 Bean 会按可获得的类型元数据检查;无法预测产品类型的 FactoryBean 不会为检查而提前实例化,其产品规则仍在调用时检查。禁用 `annotation-enabled` 时不进行注解启动检查。 标识在请求头或上下文中时,可通过 Spring Bean 读取,无须加入业务方法参数: ```java @Component("requestIdentity") public class RequestIdentity { public String requestId() { var attributes = (ServletRequestAttributes) RequestContextHolder.currentRequestAttributes(); return attributes.getRequest().getHeader("X-Request-Id"); } } // 业务方法上的注解: @Idempotent(resource = "order:create", key = "@requestIdentity.requestId()") @RateLimit(resource = "order:create", key = "@userContext.currentUserId()") ``` 示例类型分别来自 `org.springframework.stereotype.Component`、`org.springframework.web.context.request.ServletRequestAttributes` 和 `org.springframework.web.context.request.RequestContextHolder`。`userContext` 由应用提供,封装登录上下文或 ThreadLocal 的读取。Bean 方法每次调用时求值;返回 null 或空白标识会在业务执行前报错。请求编号应按用户/租户隔离,例如将可信用户标识与请求编号组合为键。ThreadLocal 由应用设置并在请求结束时清理;线程切换时需要显式传播上下文。组件不自动扫描请求头或 ThreadLocal,也不缓存当前用户标识。 ### 常用属性 | 属性前缀 | 属性 | 默认值 | 说明 | | --- | --- | --- | --- | | `quick.start.boot.ratelimit` | `enabled` | `false` | 开启限流 | | 同上 | `annotation-enabled` | `true` | 启用限流注解切面 | | 同上 | `key-prefix` | `quick:ratelimit:` | Redis 键隔离前缀 | | 同上 | `limit` / `window` | `100` / `1s` | 注解默认请求数与窗口 | | 同上 | `order` | `-200` | 切面顺序 | | `quick.start.boot.idempotent` | `enabled` | `false` | 开启幂等 | | 同上 | `annotation-enabled` | `true` | 启用幂等注解切面 | | 同上 | `key-prefix` | `quick:idempotent:` | Redis 键隔离前缀 | | 同上 | `processing-timeout` | `30s` | 执行租约;应大于业务最大耗时 | | 同上 | `retention` | `24h` | 业务成功后防重记录保留时间 | | 同上 | `order` | `-100` | 默认包裹 Spring 默认事务切面 | 注解的 `resource`、规则数值与时间支持 `${...}` 占位符。编程接口的规则由调用方显式提供。Redis 故障默认传播异常、阻止执行,不静默放行。不同应用/租户应设置独立前缀,使用相同资源键的调用方必须保持规则一致。 ### 进阶场景与边界 实现使用内部封装的 Redis 操作及单键 Lua,支持 Redis Cluster;业务键使用 SHA-256 摘要避免直接暴露标识。Redis 连接、认证、TLS 和超时由 Spring Boot / Redisson 配置管理,不新建独立连接池。 幂等仅支持同步完成的动作,禁止 `Future`、`CompletionStage` 和响应式返回值;不要与 `@Async` 组合。执行租约不自动续期,租约过期可能允许另一个请求执行;旧请求无法删除或覆盖新请求的记录,完成时会抛出 `IdempotentLeaseLostException`。进程崩溃、Redis 数据丢失、业务成功而 Redis 完成记录失败,以及业务副作用后抛异常,都可能导致再次执行,因此业务数据库仍应使用唯一约束或业务状态检查。这不是跨 Redis / 数据库的 exactly-once 保证。 默认 Redis 幂等实现在已有 Spring 同步事务中调用时,将成功确认延迟到事务提交后,回滚后才释放自己的租约;事务结果不明时保留租约直至超时。回调抛出的异常若被外层捕获且事务最终提交,仍保留成功防重记录,保护可能已经提交的业务副作用。事务提交后的 Redis 确认异常会从事务提交入口传播,此时数据库已经提交,不能将其当作业务已回滚后直接重试。事务存在但未启用同步回调时,会在获取租约和执行业务前拒绝调用。 将注解放在调用事务服务的外层同步入口仍是推荐方式;无外层事务且回调内部开启并结束事务时,回调返回后直接确认幂等成功。编程接口使用默认实现时遵循相同规则,自定义 `IdempotentOperations` 需自行维护事务时序。同步回调跟踪的是当前完整事务,业务副作用应参与该事务;内部 `REQUIRES_NEW` 独立提交、保存点局部回滚和外部系统副作用仍需业务状态检查或唯一约束保护。租约不会因等待事务提交而自动续期,`processing-timeout` 应覆盖业务执行及事务完成的总耗时。 默认构建运行单元测试;真实 Redis 测试可使用本地独立测试实例(以下端口为示例),执行: ```bash mvn -pl quick-start-boot-ratelimit,quick-start-boot-idempotent -am verify "-Dquick.redis.test.port=16379" ``` 集成测试仅写入随机 `test:` 前缀的短期记录,不执行 `FLUSHDB`。Redis Cluster 和故障切换需要在实际部署环境补充验收。 ## 仓库统一依赖规范 当前仓库的 Maven 依赖分层约定统一按下面这套规则执行: ### 1. `boot-parent` 只负责版本和编译配置 - `boot-parent` 负责统一: - 依赖版本 - `maven-compiler-plugin` - 注解处理器链路 - 通用插件默认配置 - `boot-parent` 中的 `dependencyManagement` 只做“版本约束”,不等于子模块已经自动引入了这些依赖 - 子模块真正是否拥有某个依赖,仍然取决于它自己或它的上游模块有没有在 `` 里声明 ### 2. 通用依赖放在 `quick-start-boot-core` - 仓库级通用依赖统一由 `quick-start-boot-core` 收口 - 目前 `lombok` 就属于这一类通用依赖 - 也就是说: - `boot-parent` 负责给 `lombok` 定版本和注解处理器 - `quick-start-boot-core` 负责真正声明 `lombok` - 其他模块如果已经依赖 `quick-start-boot-core`,就不需要再重复显式声明 `lombok` 这套设计是合理的,原因是: - 版本统一在 parent,避免各模块自己写版本 - 通用依赖统一在 core,避免每个子模块重复声明一遍 - 子模块 `pom.xml` 更干净,也更符合当前仓库“core 兜通用能力”的组织方式 “通用”不包含特定传输协议:Spring MVC starter、Servlet、HTTP 处理器和 HTTP 工具放在 `quick-start-boot-web`。需要 Web 的模块显式声明相应依赖,不能依赖 core 顺带引入。 ### 3. 配置处理器是例外,谁定义配置谁声明 像 `spring-boot-configuration-processor` 这类依赖,不属于“通用业务依赖”,而属于“谁定义配置元数据谁负责声明”的范畴。 统一规则是: - 哪个模块里定义了 `@ConfigurationProperties` - 哪个模块就在自己的 `pom.xml` 里显式声明 `spring-boot-configuration-processor` 不要把这类依赖也统一塞进 `quick-start-boot-core`,否则会把模块边界搞混。 ### 4. 编译期代码生成按“注解 API + 处理器实现”分层 仓库内编译期代码生成统一由 `quick-start-boot-codegen-*` 模块承载: - `quick-start-boot-codegen-annotations` - 只放对业务源码可见的 SOURCE 注解 - 业务模块可以作为普通依赖声明 - `quick-start-boot-codegen-processor` - 只放 annotation processor 实现 - 只能由需要生成代码的模块在 `maven-compiler-plugin.annotationProcessorPaths` 中显式启用 不要把 codegen processor 放进 `quick-start-boot-core`,也不要放进父 POM 的全局注解处理器链路。这样可以避免编译期工具污染普通依赖边界,也能让“谁需要生成代码谁声明”这件事足够清晰。 当前 codegen 注解均使用“标记类触发生成”的方式,业务模型无需直接依赖编译期处理器: ```java import org.dw.quickstart.boot.codegen.annotation.AutoConvert; import org.dw.quickstart.boot.codegen.annotation.DeepCloneConvert; import org.dw.quickstart.boot.codegen.annotation.EntityRef; import org.dw.quickstart.boot.codegen.annotation.GenerateProtobufPayloadExtractor; @AutoConvert(source = UserDto.class, target = UserDo.class) @DeepCloneConvert(UserDto.class) @EntityRef(User.class) @GenerateProtobufPayloadExtractor(MessageProto.MessageEnvelope.class) final class CodegenMarker { } ``` 生成规则统一如下: - `@AutoConvert` 生成 `.generated.Mapper` - `@DeepCloneConvert` 生成 `.generated.DeepCloneMapper` - `@EntityRef` 生成 `.generated.Ref` - `@GenerateProtobufPayloadExtractor` 生成 `.generated.PayloadExtractor` 业务模块接入时,只把注解 API 放进普通依赖;处理器只放进当前模块自己的 `maven-compiler-plugin.annotationProcessorPaths`: ```xml org.dw quick-start-boot-codegen-annotations org.apache.maven.plugins maven-compiler-plugin org.dw quick-start-boot-codegen-processor ${quick-start-boot-codegen-processor.version} ``` 使用 `@AutoConvert` 或 `@DeepCloneConvert` 的模块,还需要把 `org.mapstruct:mapstruct` 作为普通编译依赖声明;codegen processor 仍然只放在 `annotationProcessorPaths` 中。 ### 5. JSON 统一依赖路径 仓库内 JSON 能力统一由 `quick-start-boot-json` 模块族提供。 面向使用方的统一入口固定是: - `quick-start-boot-json-starter` 统一约定如下: - 业务应用、业务 starter、自动装配模块 - 优先依赖 `quick-start-boot-json-starter` - 这样可以同时拿到 `JsonOperations`、统一 `ObjectMapper` 和自动装配 - 纯接口契约模块 - 只依赖 `quick-start-boot-json-api` - 只暴露接口,不引入具体实现 - 只在测试或底层实现里需要 `DefaultJsonOperations` - 才依赖 `quick-start-boot-json-core` 需要单独说明的例外: - 如果某个模块只是提供 Jackson 注解、序列化器、反序列化器这类 SPI 扩展 - 它本身并不负责提供统一 `ObjectMapper` 或 `JsonOperations` - 那么可以直接依赖 Jackson 基础库,而不是强行依赖 `quick-start-boot-json-starter` 例如当前仓库里的 `quick-start-boot-masking-jackson` 就属于这一类:它提供数据掩码注解和 Jackson 扩展,不承担统一 JSON 运行时入口职责。 不要在业务模块里直接 new `ObjectMapper`,也不要绕开统一入口自己拼一套 JSON 自动装配。 ## Excel 批量导入与分批导出 ### 最小可运行示例 Spring Boot 应用按需引入独立组件;使用本仓库父 POM 时可以省略版本: ```xml org.dw quick-start-boot-excel 1.0.1 ``` 引入后自动装配 `ExcelOperations`,无需开启上传下载、配置组件扫描或手动创建监听器。 **导入定位:常规 XLSX 表格,默认读取一个 Sheet;也支持一次指定多个 Sheet。整个工作簿合计不超过 100000 条非空数据行且输入文件不超过 20MB, 同步分批处理。** 这是当前组件的设计范围和可配置保护值,不是经过压测认证的性能上限, 不承诺指定耗时、固定内存或百万行导入性能。超出该范围优先拆分文件,不为超大导入引入专用调度体系。 业务只需引入该组件,Fesod 随依赖传递并由框架管理版本。常规场景使用 `excel.read/write`, 可配置 Fesod 原生 Converter 和 WriteHandler;完整原生流程直接 import `org.apache.fesod.sheet.FesodSheet`,无需额外引入依赖,也不经过组件工厂转发。 统一流程内置 Jakarta Validation 实现,无需再引入 validation starter。下面的 HTTP 示例要求应用自行 引入 `spring-boot-starter-web`;非 Web 应用也可以直接处理输入输出流。 ```java import jakarta.validation.constraints.Min; import jakarta.validation.constraints.NotBlank; import java.io.IOException; import java.util.List; import java.util.concurrent.atomic.AtomicLong; import org.apache.fesod.sheet.annotation.ExcelIgnoreUnannotated; import org.apache.fesod.sheet.annotation.ExcelProperty; import org.springframework.http.ResponseEntity; import org.springframework.web.bind.annotation.GetMapping; import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestParam; import org.springframework.web.bind.annotation.RestController; import org.springframework.web.multipart.MultipartFile; import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody; import quick.start.boot.excel.ExcelDownload; import quick.start.boot.excel.ExcelImportResult; import quick.start.boot.excel.ExcelOperations; @RestController public class ExcelExampleController { private final ExcelOperations excel; public ExcelExampleController(ExcelOperations excel) { this.excel = excel; } @PostMapping("/examples/excel/import") public ExcelImportResult importUsers(@RequestParam("file") MultipartFile file) throws IOException { AtomicLong accepted = new AtomicLong(); try (var input = file.getInputStream()) { return excel.read(input, UserRow.class, batch -> accepted.addAndGet(batch.size())); } } @GetMapping("/examples/excel/export") public ResponseEntity exportUsers() { List rows = List.of(new UserRow("张三", 20)); return ResponseEntity.ok().headers(ExcelDownload.headers("用户清单")) .body(output -> excel.write(output, UserRow.class, "用户", rows)); } @ExcelIgnoreUnannotated public static class UserRow { @ExcelProperty("姓名") @NotBlank(message = "姓名不能为空") private String name; @ExcelProperty("年龄") @Min(value = 0, message = "年龄不能小于零") private Integer age; public UserRow() { } public UserRow(String name, Integer age) { this.name = name; this.age = age; } public String getName() { return name; } public void setName(String name) { this.name = name; } public Integer getAge() { return age; } public void setAge(Integer age) { this.age = age; } } } ``` 启动应用后,下载 `/examples/excel/export`,将得到的文件作为 multipart 字段 `file` POST 到 `/examples/excel/import`,即可完成最小闭环。示例的回调仅累计接收数量,不写数据库; 实际接入时将该回调替换为业务 Service 的批次处理方法。 Web 上传请求另受 `spring.servlet.multipart.max-file-size` 和 `max-request-size` 限制,需与组件上限协调。 ### 示例逐段解释 **组件统一能力和业务边界:** | 环节 | 组件统一负责 | 业务负责 | | --- | --- | --- | | 数据模型 | 复用 Fesod 列映射、转换器和格式注解,不新建注解体系 | 专用导入导出 DTO、列名、字段格式;避免直接导出实体 | | 导入结构 | 一次读取指定的一个或多个 Sheet;分别检查表头、定位类型转换错误 | 选择 Sheet、模型、表头行数和处理回调 | | 行校验 | 自动执行默认 Jakarta Validation 约束,收集结构化错误 | 字段约束、字典及跨字段规则;业务校验回调 | | 批次处理 | 只将通过校验的行分批交付,同步执行、不自动重试 | 查重、批量入库、事务、幂等、权限和租户隔离 | | 结果 | 统计扫描、拒绝、处理行数;限制错误明细数量 | 判断结果是否满足业务成功条件、展示或持久化错误 | | 导出 | 分批获取和写入、自动分 Sheet、空模板、中文文件名响应头 | 查询条件、稳定排序或游标、数据权限、脱敏与字段选择 | | 文件和任务 | 处理调用方提供的流,释放内部读写资源 | 文件鉴权、存储、留存、异步任务、进度、取消和重试 | 首版统一入口只处理 `.xlsx`。`read(input, Row.class, handler)` 默认读取第 0 个 Sheet、1 行表头, 跳过空行。行类型使用带无参构造器和 getter/setter 的普通 Java Bean;推荐 `@ExcelIgnoreUnannotated` 配合 `@ExcelProperty` 明确列白名单。命名列可重排,所有映射列必须存在且名称唯一; 显式 `index` 列还校验位置和标题。额外未映射列忽略,多级表头按最后一行标题匹配。 表头不符、Sheet 不存在或文件损坏会中止,不会按空文件成功返回。 组件先进行类型转换,再执行默认组字段校验,最后执行可选的业务行校验; 只有全部通过的行才进入批次回调。回调接收的列表不可修改,最大长度为 `batch-size`,末批自动提交给回调。 统一 `read/write` 的 `InputStream` / `OutputStream` 由调用方管理,组件不关闭它们; Spring MVC 管理示例中的响应输出流。直接使用 Fesod 时按其原生配置管理流,见进阶示例。 组件 Bean 无请求状态,每次导入的监听器、缓冲和错误列表相互独立。 默认监听器是组件内部实现,业务不需要创建或注册,也不作为可替换的单例 Bean 暴露。 业务通过行校验器、Converter、批次回调和分页数据源扩展流程;需要自行处理原生读取事件时使用 `FesodSheet`。 结果 `ExcelImportResult` 的字段含义: | 字段/方法 | 含义 | | --- | --- | | `totalRows` | 已扫描的非空数据行,含类型转换、字段校验和业务行校验失败的行;不含表头 | | `processedRows` | 批次回调正常返回的行数,表示业务已确认接收,不代表数据库已经提交 | | `rejectedRows` | 因行错误拒绝的行数,同一行有多个错误只计一行 | | `pendingRows()` | 已扫描但尚未确认处理或拒绝的行数;正常返回为 0,中止时可能包含未交付缓冲或失败批次,不代表数据库中未写入的行数 | | `errorCount` | 全部行错误条数,可能大于拒绝行数 | | `errors` / `errorsTruncated()` | 前 `max-errors` 条明细及是否已截断;截断后继续统计和处理 | 自定义实现构造结果时,统计值须非负,处理与拒绝行数之和不得超过扫描行数,错误明细数不得超过错误总数;不满足时立即拒绝。 每条 `ExcelError` 包含 `sheetNo/sheetName/rowNumber/columnNumber/field/kind/message`。 Sheet 编号从 0 开始,行号和列号从 1 开始;实际行号包含表头及空行,便于使用者定位。 无法定位字段对应列时 `columnNumber` 为 `null`。类型转换错误统一使用安全提示,不返回原始单元格值; 字段约束和业务回调自行提供适合展示的消息。字段、转换、业务行错误分别标记为 `VALIDATION`、`CONVERSION`、`BUSINESS`。 **默认行错误策略为 `ExcelRowErrorPolicy.CONTINUE`。** 有行错误时跳过错误行、继续处理有效行并返回结果, 业务不能仅以 HTTP 200 或方法正常返回表示整文件成功。每次导入可选择 `FAIL_FAST`,记录首个错误行后立即中止。 解析/表头失败、资源超限、校验器或批次回调异常,以及 `FAIL_FAST` 遇到行错误,均抛出 `ExcelImportException`, 通过 `reason()` 区分 `FORMAT/LIMIT/PROCESSING/ROW_ERROR`,通过 `result()` 获取中止时的统计快照。 输入流本身的 I/O 故障归为 `PROCESSING`,保留原始故障供内部诊断;损坏的 XLSX 内容仍归为 `FORMAT`。 处理异常不会伪装成可跳过的行错误;失败批次可能已发生部分副作用,组件不自动重试、补偿或回滚。 `processedRows` 只表示回调正常返回,外层事务仍可能随后提交失败或回滚;异常也不表示先前批次已撤销。 应用负责将异常映射为自己的 HTTP 返回协议,不能直接向外序列化异常、cause 或堆栈。 ### 常用属性说明 全部参数位于 `quick.start.boot.excel.*`,默认无需配置;除 `enabled` 控制 Bean 装配外, 以下处理参数应用于统一 `read/write`(含自定义 Converter / WriteHandler),不注入业务自行创建的 Fesod 原生 Builder: | 属性 | 默认值 | 用途 | | --- | --- | --- | | `enabled` | `true` | 引入组件即装配无状态服务;设为 `false` 关闭默认装配 | | `batch-size` | `500` | 导入批次最大行数和导出每次请求的数据量 | | `max-file-size` | `20MB` | 本次导入输入流可消费的最大字节数,非解压后大小 | | `max-import-rows` | `100000` | 非空导入数据行数上限,含转换失败行;超过立即中止 | | `max-errors` | `1000` | 最多保留的错误明细条数,不改变错误总数统计 | | `max-export-rows` | `1000000` | 单次导出总数据行数上限,超过立即失败 | | `rows-per-sheet` | `1000000` | 每个 Sheet 的数据行数上限,范围 1~1000000,达到后自动续 Sheet | 数值均须为正数,错误配置在启动时失败。组件保留 POI 默认的压缩文件保护,不修改进程级 POI 安全参数。 流式处理仍可能使用临时磁盘;输入字节和行数限制不等于对解压体积、总内存、并发数或执行时长的完整约束, 部署时由应用控制并发、请求超时和临时目录容量。Spring MVC 流式响应还需配置适当的异步执行器和超时。 **导入规模与超限行为:** `100000` 行、`20MB` 是面向常规后台导入选择的工程保护默认值,不是 Fesod 的能力上限, 也不能仅按行数推导资源消耗;列数、字符串长度、错误比例和业务查询/写入都会影响成本。 当前默认设计范围同时受两项限制,较先达到者生效;批次和错误缓冲有界,不等于解析缓存、解压体积及临时磁盘有固定上限。 2026-11-07 本机容量验证使用 Windows、Ryzen 7 8845H、32GB 内存、JDK 17、`-Xmx512m`、8 列 DTO、默认配置和单任务执行; 导入含字段校验,批次回调只检查数据并计数,不访问数据库。两个导入 Sheet 各约 5 万行,全部数据按 500 行分批处理。 | 场景 | 验证结果 | 本次耗时 | 采样已用堆 / 临时磁盘峰值 | | --- | --- | --- | --- | | 10 万行双 Sheet 导入,文件约 4.45MiB | 处理 100000 行 | 1.68 秒 | 305MiB / 4.45MiB | | 100001 行双 Sheet 导入 | 第 100001 行触发 `LIMIT`,此前已确认 100000 行 | 1.67 秒 | 301MiB / 4.45MiB | | 10 万行中含 1% 错误行 | 处理 99000 行、拒绝 1000 行;2000 条错误只保留 1000 条明细 | 1.68 秒 | 234MiB / 4.45MiB | | 百万行导出,文件约 44.8MiB | 写出 1000000 行 | 19.88 秒 | 309MiB / 504MiB | 堆和临时磁盘每 100ms 采样;已用堆包含尚未回收的对象。这是上述模型的一次本机容量验证, 不代表 20MB 文件、宽表、复杂样式、数据库回调或并发任务的统一性能保证,也未验证百万行导入。 同一环境和 `-Xmx512m` 下,另用同一个 `ExcelOperations` 实例并发执行两个上述 10 万行导入任务, 每个任务独立打开输入流,并通过首批回调屏障确认处理重叠。两轮独立 JVM 均各自完整处理 100000 行, 单任务耗时 1.64~1.67 秒;进程采样已用堆峰值为 249~280MiB,临时磁盘峰值约 8.9MiB,任务结束后临时文件清空。 回调逐行检查 8 列数据并计数,不访问数据库;这些结果不作为默认并发数或生产容量承诺。 恰好达到配置上限允许处理;需要消费第 `max-import-rows + 1` 条非空数据行或超过 `max-file-size` 的字节时, 抛出 `ExcelImportException`,`reason()` 为 `LIMIT`,消息包含生效的配置限额及拆分文件提示。 行数限制包含转换和校验失败的行,不含表头和空行;`CONTINUE` 也不会忽略超限。 检查发生在读取过程中,行数超限前可能已有批次落库,不承诺在任何业务副作用前拒绝整个文件。 `result()` 只反映已扫描部分;资源超限不是可跳过的行错误。 若 HTTP multipart 限制先触发,请求可能在进入组件之前就被 Web 容器拒绝,不会抛出组件异常。 业务可以调整上述属性,但提高数值不表示组件已验证或承诺更大规模。 放宽前需以实际模型、回调和部署环境验证耗时、堆内存、GC、临时磁盘及并发;默认设计范围内也没有统一吞吐保证。 几十万、百万行等超出当前定位的任务,优先拆分为多个可控导入,或由独立数据导入任务处理; 本组件保持解析、校验、分批交付和限额职责,不增加并行解析、断点恢复、任务调度及全文件事务。 导出的 `max-export-rows`、`rows-per-sheet` 是独立配置,不能用来推断导入能力。 **执行线程与异步边界:** `read/write` 都在调用线程执行;导入逐行校验、批次回调串行执行,回调正常返回后才继续读取。 组件没有异步入口、内部线程池或线程池配置;无状态服务可以被多个线程调用,但不会自动限制并发。 默认实现的读取监听器、统计、错误缓冲和读写器按调用创建。并发测试覆盖 4 路导入时的批次、转换器、 错误和限额隔离,以及单任务失败后的其他任务完成;另覆盖并发导出的分页、分 Sheet、转换器、样式处理和流所有权。 每个任务须独立管理输入输出流及可变业务状态;有状态的校验器、Converter、WriteHandler、批次回调和分页源不能跨任务共享。 业务有后台导入需求时,任务服务先保存上传文件并创建任务记录,再提交到 Spring 管理的有界执行器; 执行器线程里同步调用 `excel.read(...)`。例如: ```java @Async("excelImportExecutor") public CompletableFuture runImport(Path stagedFile) throws IOException { try (var input = Files.newInputStream(stagedFile)) { return CompletableFuture.completedFuture( excel.read(input, UserRow.class, userService::saveBatch)); } } ``` `excelImportExecutor` 由应用配置为有界线程池并限制队列容量。任务服务负责落库任务状态、并发准入、结果查询、 异常映射、文件保留和清理;组件只在该任务线程中同步解析。跨请求后台执行前先将上传文件保存到任务可访问的存储, 任务内打开并关闭输入流, 不能依赖请求结束后的 `MultipartFile` 临时资源或已关闭的流。 批次回调应在实际处理完成后返回;不要只提交异步保存任务就返回,否则统计只代表提交成功, 后续失败也无法由组件感知,且会破坏原有串行消费节奏。异步执行也不会提高限额或自动提供更大规模的处理保证。 ### 进阶场景 **选择行错误策略:** ```java import quick.start.boot.excel.ExcelImport; import quick.start.boot.excel.ExcelRowErrorPolicy; var specification = ExcelImport.of(UserRow.class) .rowErrorPolicy(ExcelRowErrorPolicy.FAIL_FAST); try (var input = file.getInputStream()) { ExcelImportResult result = excel.read(input, specification, userService::saveBatch); } ``` 遇到行错误时,交由应用的异常处理器识别 `ExcelImportException.Reason.ROW_ERROR`, 将异常的 `result()` 明细和部分统计映射为业务错误响应,不能按整文件处理成功返回。 | 情况 | `CONTINUE`(默认) | `FAIL_FAST` | | --- | --- | --- | | 类型转换、字段约束、业务校验返回错误 | 记录错误、跳过该行并继续 | 记录首个错误行后抛出 `ROW_ERROR` | | 文件损坏、表头错误 | 中止,`FORMAT` | 中止,`FORMAT` | | 超出输入字节或导入行数限制 | 中止,`LIMIT` | 中止,`LIMIT` | | 输入流 I/O 故障、校验器或批次回调异常 | 中止,`PROCESSING` | 中止,`PROCESSING` | `FAIL_FAST` 按错误行终止,不是发现第一条约束就停止检查:保留该行当前校验阶段返回的全部错误计数, 明细仍受 `max-errors` 限制;字段约束失败后不执行该行的业务校验,类型转换失败后不执行行校验。 中止后不继续扫描,也不将尚未凑满批次的缓冲交给回调;已完成批次仍计入 `processedRows`, 未交付缓冲计入 `pendingRows()`。策略配置不可变,只影响当前导入,不修改其他调用的策略或组件限额。 该策略不控制事务;“遇错中止”不等于“整文件无副作用”,也不等于“全部校验通过才入库”。 **指定 Sheet、表头和业务行校验:** ```java var specification = ExcelImport.of(UserRow.class).sheet(0).headRows(1).validate(row -> { if (row.data().getAge() == null) { return List.of(new ExcelViolation("age", "此业务要求填写年龄")); } return List.of(); }); try (var input = file.getInputStream()) { ExcelImportResult result = excel.read(input, specification, userService::saveBatch); } ``` 以上使用 `quick.start.boot.excel.ExcelImport` 和 `ExcelViolation`。业务行校验只对通过字段约束的行执行; 预期的数据问题返回错误列表,外部查询或程序异常应抛出以中止导入。不要将数据库不可用返回为某一行“不合法”。 事务应放在独立业务 Service 的代理方法上;组件不创建事务,也不默认开启异步线程。 若要求整文件无错误后才入库,应先验证到业务暂存区,再确认提交;不要用当前逐批回调模式假装实现整文件原子性。 **一次读取多个 Sheet:** ```java import java.util.List; import quick.start.boot.excel.ExcelImport; import quick.start.boot.excel.ExcelSheetImport; var result = excel.read(input, List.of( ExcelSheetImport.of( ExcelImport.of(UserRow.class).sheet(0), userService::saveBatch), ExcelSheetImport.of( ExcelImport.of(DepartmentRow.class).sheet(1).headRows(2).validate(departmentValidator), departmentService::saveBatch))); ``` 每项分别声明 Sheet 序号、行模型、表头行数、错误策略、转换器/校验器及批次回调; 各 Sheet 在同一个 Fesod Reader 中处理,不重复打开和解析工作簿。Sheet 序号不可重复, 执行遵循工作簿内的 Sheet 顺序,配置列表的先后不决定回调顺序;跨 Sheet 依赖应由业务显式编排。 结果的行数和错误统计聚合整个工作簿,错误明细保留 Sheet 序号和名称。 `max-import-rows` 与 `max-errors` 按整个工作簿共享;任一 Sheet 超限都会中止整次读取。 未配置的 Sheet 会跳过。多个 Sheet 之间的关联校验和跨 Sheet 事务仍由业务编排。 **Spring 默认实现与业务扩展:** 对外注入 `ExcelOperations` 接口,自动配置通过 `@ConditionalOnMissingBean(ExcelOperations.class)` 提供内部的 `DefaultExcelOperations`。优先组合 `ExcelRowValidator`、原生 Converter / WriteHandler、 批次 `Consumer>` 和 `ExcelPageSource`;行校验器 Bean 需显式传给 `.validate(...)`,不会自动应用到所有导入。 组件不为每个内部类创建接口,也不扫描和共享持有导入状态的监听器。 确需整体替换时,在业务配置类中注册接口 Bean: ```java @Bean ExcelOperations excelOperations() { return new BusinessExcelOperations(); } ``` `BusinessExcelOperations` 是业务自行实现的类,需实现接口的 `read(input, specification, batchHandler)` 和 `write(output, specification, source)` 方法,其他便捷重载由接口提供。 声明该 Bean 后默认实现自动退让,无需开启 Bean 覆盖或添加 `@Primary`。 替换实现应遵守接口契约,负责自己的校验、统计、策略、限额和资源管理;自动配置不再额外叠加这些能力。 多 Sheet 重载默认兼容单个 Sheet 配置;要支持一次读取多个 Sheet,自定义实现需覆盖 `read(input, sheets)`。 默认实现提供完整的多 Sheet 读取及工作簿级共享限额。 默认实现和内部监听器保持包内可见,不作为业务继承或替换监听器的扩展入口。 **从数据库分批导出:** ```java excel.write(output, UserRow.class, "用户", (pageNumber, pageSize) -> userService.findExportPage(pageNumber, pageSize)); ``` 页码从 0 开始,每次必须返回不超过 `pageSize` 的列表;空列表表示结束,非空短页仍会继续请求, `null` 或超量列表立即失败。数据源可以在本次调用内维护游标,以避免深分页;查询一致性、排序和权限仍由业务保证。 `write` 成功返回实际写入的数据行数,不表示客户端已收到文件;异常时输出流可能已包含部分内容。 数据不足一页不要求补齐。小列表可以直接使用列表重载; 空列表生成带表头的模板。多 Sheet 沿用相同模型,续 Sheet 名称追加序号并适配 Excel 的 31 字符限制。 `ExcelDownload.headers("用户清单")` 生成 XLSX 类型、支持中文的 attachment 文件名和私有禁止缓存响应头, 自动补 `.xlsx` 后缀;拒绝控制字符和路径分隔符。该辅助类需要应用提供 Spring Web,核心读写不需要。 动态生成响应不声明文件长度或 Range;响应开始后失败只能中断,不能再追加 JSON 错误。 需要“生成成功后才可下载”、断点下载或长期留存时,先生成到业务独占临时文件,成功后再发布到文件存储, 由现有上传下载组件管理完成文件。生成、存储发布、业务记录绑定与鉴权由应用编排,不强制走分片上传。 **自定义转换、样式与统一校验组合:** 仅需自定义转换或导出样式时,继续使用统一流程。配置对象直接接收 Fesod 原生 SPI, 不用重新实现组件监听器,也不开放可替换输入流、模型、监听器或文件类型的任意 Builder 回调: ```java import quick.start.boot.excel.ExcelExport; import quick.start.boot.excel.ExcelImport; // departmentConverter 是业务实现的 Fesod Converter。 // 新配置不改变原配置,链式调用会保留已注册的 Converter。 var imported = ExcelImport.of(UserRow.class) .converter(departmentConverter) .sheet(0) .headRows(1) .validate(userRowValidator); try (var input = file.getInputStream()) { ExcelImportResult result = excel.read(input, imported, userService::saveBatch); } // styleHandler 是 Fesod WriteHandler,例如 SheetWriteHandler、单元格样式或列宽策略。 var exported = ExcelExport.of(UserRow.class, "用户") .converter(departmentConverter) .writeHandler(styleHandler); excel.write(output, exported, (page, size) -> userService.findExportPage(page, size)); // 同样支持列表和空模板:excel.write(output, exported, rows); ``` 导入的 Converter 在字段和业务行校验之前运行。转换失败仍记录为 `CONVERSION`, 转换成功的数据继续执行 Jakarta Validation 和 `ExcelRowValidator`;批次处理、错误明细上限、 字节和行数限制仍生效。导出的 Converter 和 WriteHandler 应用于续建的每个 Sheet, 分页、总行数限制、自动分 Sheet 和调用方管理输出流的约定仍生效。 WriteHandler / 数据源异常不会当作成功吞掉,输出可能只有部分内容,业务应丢弃或中断响应。 Converter 的 Java 类型、单元格类型和匹配优先级遵循 Fesod。DTO 上显式指定的字段 Converter 优先于 按类型注册的转换器;读取时要实现 `supportJavaTypeKey` 和 `supportExcelTypeKey`, XLSX 常规写出按 Java 类型匹配(`supportExcelTypeKey()` 返回 `null`),有不同匹配键时使用独立转换器。 仅在 Spring 注册 Converter Bean 不会自动影响所有导入导出,需要在本次配置显式注册或在 DTO 注解指定。 转换器只负责转换;外部查询、业务校验、入库应放在对应业务扩展点。 配置集合做不可变快照,但不会克隆 Converter、WriteHandler 和业务校验器实例。 无状态实现可以复用;有状态处理器每次操作新建,避免并发请求共享状态。处理器能够访问原生工作簿, 业务应按 Fesod 契约使用,不在处理器中额外写入绕过组件计数的数据或提前关闭组件管理的 Writer。 **直接使用完整 Fesod 原生能力:** 复杂模板填充、图片、动态表头,以及在一个工作簿中写入多个不同模型的 Sheet,直接使用随组件传递的 Fesod 类型。 不继承静态工厂、不反射转发,也不复制原生方法和全部重载。 Fesod 新增工厂方法或 Builder 能力时,升级依赖后即可按原生 API 调用,无需等待组件增加包装方法。 升级产生的原生类型或方法不兼容仍需修改调用代码,不承诺跨版本兼容。 | 使用路径 | 默认处理约定 | 适用需求 | | --- | --- | --- | | `excel.read/write`,配合 `ExcelImport` / `ExcelExport` | 组件校验、错误报告、分批处理和资源限制;调用方关闭流 | 常规表格、自定义转换和导出样式 | | `FesodSheet` / 原生 Builder、Reader、Writer | Fesod 原生配置、异常和流关闭行为 | 完整模板、图片、动态列及复杂多 Sheet | 已有 XLSX 模板使用 Fesod 占位符,例如 `{title}` 为普通字段、`{.name}` 为列表字段。 在前述 Controller 中 import `org.apache.fesod.sheet.FesodSheet` 后,以下方法可使用从业务模板仓 读取的内容填充标题和列表: ```java public byte[] fillReport(byte[] templateBytes) throws java.io.IOException { try (var template = new java.io.ByteArrayInputStream(templateBytes); var output = new java.io.ByteArrayOutputStream(); var writer = FesodSheet.write(output) .withTemplate(template).autoCloseStream(false).build()) { var sheet = FesodSheet.writerSheet(0, "报表").build(); writer.fill(java.util.Map.of("title", "月度报表"), sheet); writer.fill(List.of(java.util.Map.of("name", "张三"), java.util.Map.of("name", "李四")), sheet); // finish 后 XLSX 才完整;close 是幂等的,try-with-resources 在异常时仍会释放 writer。 writer.finish(); return output.toByteArray(); } } ``` 上例用小文件展示,较大输出应直接写入业务提供的输出流或独占临时文件。 模板中的区域、样式和列表填充策略遵循 Fesod,可继续使用 `FillConfig` 等原生类型。 模板内容与读取权限、版本选择由业务管理,组件不新增模板注册表。 需要多模型多 Sheet 导出,或需要在读取时自行控制原生监听器时,由业务通过原生 Reader/Writer 编排。 常规多模型多 Sheet 导入可使用前述 `ExcelOperations.read(input, sheets)`: ```java try (var writer = FesodSheet.write(output).autoCloseStream(false).build()) { writer.write(users, FesodSheet.writerSheet(0, "用户").head(UserRow.class).build()); writer.write(orders, FesodSheet.writerSheet(1, "订单").head(OrderRow.class).build()); } // 读取多个 Sheet 时,分别注册业务原生监听器;各 Sheet 的模型和规则相互独立。 try (var reader = FesodSheet.read(input).autoCloseStream(false).build()) { reader.read(FesodSheet.readSheet(0).head(UserRow.class).registerReadListener(userListener).build(), FesodSheet.readSheet(1).head(OrderRow.class).registerReadListener(orderListener).build()); } ``` `FesodSheet` 的完整重载以及原生 `Converter`、`ReadListener`、`WriteHandler`、`FillConfig` 等均可直接使用。 原生 Builder、Reader 和 Writer 的状态由本次业务调用独占。 **原生路径不会自动执行 Jakarta Validation、`ExcelRowValidator`、结构模板校验、 `ExcelImportResult` 错误统计、自动分 Sheet 或组件资源限制,也不将异常包装成 `ExcelImportException`。** 原生 `doReadSync()` 可能将数据全量载入内存,分页、校验和资源控制由调用方配置。 原生流关闭行为沿用 Fesod(默认自动关闭读写流),如上例显式设置 `autoCloseStream(false)` 后由业务管理流; Reader/Writer 使用 try-with-resources,或按 Fesod 规则完成并释放。直接引用原生类型意味着高级调用代码与 框架选择的 Fesod 版本关联,升级时应验证使用到的高级功能;组件不宣称能无缝替换底层 Excel 引擎。 底座使用 `org.apache.fesod:fesod-sheet:2.1.0-incubating`,由父 POM 管理版本; 引入现有含 POI 的应用时,应检查实际依赖树并验证兼容性,避免混用不兼容的 POI 组件版本。 ### 扩展能力归属 当前组件刻意保持“稳定内核 + 业务扩展点”的边界: | 需求 | 当前处理方式 | 是否进入基础组件 | | --- | --- | --- | | 字段约束、类型转换和表头校验 | `ExcelOperations` 自动处理 | 是 | | 业务行校验 | `ExcelRowValidator` 返回 `ExcelViolation` | 组件提供接口,规则由业务实现 | | 自定义枚举、金额、日期转换 | DTO 注解,或 `ExcelImport` / `ExcelExport` 注册原生 `Converter` | 与统一流程组合,不固化业务规则 | | 固定列模板 | DTO、`@ExcelProperty`、`headRows` 和 Sheet 配置 | 是,限于结构校验 | | 已有 `.xlsx` 模板填充 | 直接使用 `FesodSheet.write(...)` 的 `withTemplate` / `fill` | 传递原生依赖,不重建填充流程 | | 模板版本、模板下载和模板权限 | 业务模板服务 | 否 | | 导出列宽、冻结窗格和样式 | `ExcelExport.writeHandler(...)` 接收原生策略 | 与统一导出流程组合 | | 图片、动态列、复杂公式和模板布局 | 直接使用原生 API | 不限制原生 API,由业务配置 | | 常规多 Sheet 导入 | `ExcelOperations.read(input, sheets)` 按 Sheet 配置 DTO、校验和批次回调;共享工作簿级行数及错误明细上限 | 业务负责跨 Sheet 关联校验、事务和数据编排 | | 复杂多 Sheet 布局或原生事件处理 | 直接使用 Fesod Reader/Writer | 传递原生依赖,不限制原生 API,由业务配置 | | 异步任务、进度、取消和重试 | 业务任务服务或独立任务模块 | 否 | | 数据库事务、整文件回滚、去重和幂等 | 业务 Service | 否 | | 文件存储、留存和下载授权 | 业务编排现有上传下载组件 | 否 | 其中“固定列模板”是指组件校验导入文件是否符合 DTO 的列结构,不代表组件拥有模板文件管理能力。 例如业务可以通过模板版本选择不同 DTO: ```java ExcelImport specification = switch (templateVersion) { case "v1" -> ExcelImport.of(UserImportV1Row.class); case "v2" -> ExcelImport.of(UserImportV2Row.class).headRows(2); default -> throw new IllegalArgumentException("Unsupported template version"); }; ``` 业务优先使用统一流程的 Converter / WriteHandler 扩展,需要完整原生流程时直接使用 Fesod; 只有多个业务仍重复出现相同的模板填充约定时, 才考虑增加独立的 `ExcelTemplateOperations`,由同一组件体系提供按需能力。 模板版本、字段语义、权限和业务数据仍由业务负责,不将模板管理、数据库事务和异步任务并入基础组件。 ## 大文件分片上传 ### 最小可运行示例 Spring Boot 应用引入独立上传模块,再开启配置即可注入统一接口 `quick.start.boot.upload.UploadOperations`。未开启时不创建上传 Bean、目录或 S3 客户端。 ```xml org.dw quick-start-boot-upload 1.0.1 ``` 使用本仓库父 POM 管理版本时可省略 `version`。上传模块不依赖 `quick-start-boot-core`, 可供其他业务模块或外部 Spring Boot 应用单独使用;自动装配由 `AutoConfiguration.imports` 注册,无需组件扫描或手动 `@Import`。 ```yaml quick: start: boot: upload: enabled: true storage: file workspace: ./runtime/uploads ``` 代码示例是可嵌入业务应用的 Service,不包含应用启动类或 HTTP Controller。想先验证组件而不准备真实文件或 S3, 可在仓库根目录运行本地上传模块测试;测试用临时目录和小数据,不依赖外部存储: ```shell mvn -pl quick-start-boot-upload -am test ``` 业务类通过构造器注入接口。本地和 S3 使用相同的方法及结果类型: ```java import java.io.ByteArrayInputStream; import java.io.IOException; import java.nio.charset.StandardCharsets; import java.util.Arrays; import org.springframework.stereotype.Service; import quick.start.boot.upload.UploadHashes; import quick.start.boot.upload.UploadOperations; import quick.start.boot.upload.UploadRequest; import quick.start.boot.upload.StoredFile; @Service public class AttachmentService { private final UploadOperations uploads; public AttachmentService(UploadOperations uploads) { this.uploads = uploads; } public StoredFile uploadExample(String scope) throws IOException { byte[] content = "分片上传示例".getBytes(StandardCharsets.UTF_8); String hash = UploadHashes.sha256(new ByteArrayInputStream(content)); var task = uploads.init(scope, new UploadRequest("示例.txt", content.length, hash, 8)); if (!task.completed()) { for (int i = UploadOperations.FIRST_CHUNK_NUMBER; i <= task.totalChunks(); i++) { if (task.uploadedChunks().contains(i)) { continue; } int offset = Math.toIntExact((i - UploadOperations.FIRST_CHUNK_NUMBER) * task.chunkSize()); byte[] chunk = Arrays.copyOfRange(content, offset, Math.min(content.length, Math.toIntExact(offset + task.chunkSize()))); try (var input = new ByteArrayInputStream(chunk)) { uploads.uploadChunk(scope, task.uploadId(), i, input, null); } } } return uploads.complete(scope, task.uploadId()); } } ``` ### 示例逐段解释 模块职责:`quick-start-boot-upload` 提供公开上传接口、任务管理、内容校验、续传、本地存储及 Spring Boot 自动装配; `quick-start-boot-upload-s3` 依赖前者,提供 S3 存储与对象直传。内部实现保留包内可见,不作为外部扩展入口。 业务依赖并注入 `UploadOperations`,自定义存储实现 `FileStorage` 并注册 Bean;无需依赖内部任务仓或文件布局。 原 `quick.start.boot.core.upload` 包已迁到 `quick.start.boot.upload`,使用方需更新依赖及 import,配置前缀保持不变。 - `init(scope, request)`:按权限范围、整个文件 SHA-256 和大小复用任务,返回服务端计算的 `totalChunks` 与成功落盘的 `uploadedChunks`;已有完成文件时返回 `completed=true`,可直接秒传。 - `status(scope, uploadId)`:查询进度;进程重启后从持久化任务仓恢复,客户端只补传缺失分片。 - `uploadChunk(scope, uploadId, chunkNo, input, expectedHash)`:从 1 编号,与对象存储直传一致,可选分片 SHA-256 校验。 最后一片允许不足 `chunkSize`,其他分片大小必须精确匹配;校验成功才原子发布,同编号重传可替换旧分片。 - `complete(scope, uploadId)`:确认分片齐全,流式合并并强制校验大小及整个文件 SHA-256,随后发布到所选存储。 所有后端都返回 `StoredFile(location, fileName, sha256, metadata)`;只有后端成功才清理分片,重复调用返回相同结果。 - `cleanExpired()`:后台自动发现所有范围的过期任务并清理,完成文件不删除;`cleanExpired(scope)` 可按指定范围清理。 - `UploadHashes.sha256(input)`:独立的流式校验工具;所有接收 `InputStream` 的方法均由调用方关闭输入流。 只有 `init` 创建任务目录和锁文件;对不存在任务调用 `status/uploadChunk/complete` 会拒绝请求,不产生任务文件。 示例仅用小文件演示流程。实际大文件由客户端切片,服务端直接接收分片流,避免 `MultipartFile.getBytes()` 和整文件 `Files.readAllBytes()`。空文件使用 0 个分片,直接调用 `complete`。 `scope` 是业务隔离范围,不要求有租户,也不需要在配置中枚举用户。按应用需求选择一种稳定规则,由服务端统一生成: | 业务需求 | scope 的生成方式 | 说明 | | --- | --- | --- | | 按登录用户隔离 | `"user:" + currentUserId` | ID 从现有登录上下文取得,自动生成,无需手写名单 | | 无需用户或租户隔离 | 固定 `"app"` 或业务名 `"documents"` | 所有调用使用同一值,共享该范围的未完成任务额度 | | 已有多租户隔离 | `"tenant:" + currentTenantId + "/user:" + currentUserId` | 仅在业务需要时组合租户与用户 | 例如,没有租户概念、按当前登录用户隔离时: ```java String scope = "user:" + currentUserId; var task = uploads.init(scope, request); uploads.status(scope, task.uploadId()); ``` `currentUserId` 来自应用现有的登录上下文,不能直接取客户端传入的 ID; 初始化、续传、分片、完成都使用同一生成规则。scope 是稳定的权限范围,不是文件名、随机数或每次请求的新 ID。 组件统一校验:1~128 个 ASCII 字符,以字母或数字开头,其余仅允许字母、数字、`:`、`_`、`/`、`-`; 空白、控制字符、其他符号及过长值直接抛 `IllegalArgumentException`,不自动修剪或改大小写。 过期清理只需开启调度,组件会从工作目录自动发现所有已有任务;不需要填写 scope 列表: ```yaml quick: start: boot: upload: cleanup: enabled: true interval: 1h ``` 上传范围默认校验格式;组件不了解应用的用户或业务目录,不能自行判断一个格式合法的 ID 是否存在。 固定业务范围可以配置 `scope.allowed: [documents, imports]` 拦截拼写错误,无需维护用户名单。 动态范围需要进一步校验时,可提供业务校验 Bean: ```java @Bean UploadScopePolicy uploadScopePolicy(UploadAccessService access) { return scope -> { if (!access.isUploadScopeEnabled(scope)) { throw new IllegalArgumentException("Unknown or disabled upload scope"); } }; } ``` `UploadAccessService` 是应用自己的访问校验服务,示例方法应校验该范围是否存在且可用;异常直接传播,不在服务故障时放行。 自定义 Bean 替代配置白名单的语义校验,组件的基础格式校验仍然生效。所有按 scope 的操作都会校验, 并在创建本地任务、创建远端 multipart 或签发 URL 之前拒绝非法范围;当前用户的操作权限由业务鉴权确认。 后台无参 `cleanExpired()` 仅针对工作目录中的已有任务,不依赖登录态或当前白名单;用户被停用后,其过期任务仍会回收。 业务调度平台也可直接调用无参入口,无需枚举用户。该入口用于后台管理,不应作为普通用户的 HTTP 接口开放。 `location` 是供服务端使用的 URI,不代表公开下载授权;下载及业务文件绑定仍须校验权限。 ### 常用属性说明 以下参数均通过 `quick.start.boot.upload.*` 绑定,支持 Spring Boot 的容量和时长写法: | 属性 | 默认值 | 用途 | | --- | --- | --- | | `enabled` | `false` | 显式开启,避免 core 被依赖后自动创建存储资源 | | `storage` | `file` | 选择 `file` 或 `s3`;选中但未安装的后端会导致启动失败,不自动回退 | | `workspace` | `./runtime/uploads` | 服务独占目录;任务暂存放在 `tasks`,本地完成文件放在 `files` | | `max-file-size` | `20GB` | 文件大小上限,使用 `long` | | `max-chunk-size` | `8MB` | 客户端单片上限,每个请求仍须声明 `chunkSize` | | `max-chunks` | `100000` | 单任务分片数量上限 | | `buffer-size` | `64KB` | 暂存及合并流缓冲区 | | `max-file-name-length` | `255` | 展示文件名长度上限,文件名不参与存储路径拼接 | | `idle-timeout` | `24h` | 自最后一次成功写入起计算的过期时间 | | `cleanup.enabled` | `false` | 是否启用组件内置过期清理调度;自动发现全部范围的持久化任务 | | `cleanup.interval` | `1h` | 清理调度周期 | | `scope.allowed` | 空 | 可选的固定范围白名单;空时仅校验格式,动态校验使用 `UploadScopePolicy` Bean | | `resources.max-active-tasks-per-scope` | `4` | 每个可信 scope 的未完成任务上限;服务端接收与 S3 直传分别计数 | | `resources.max-staging-size` | `40GB` | 服务端接收的任务暂存预算;所有 scope 共用,按每个文件大小的两倍预留 | | `resources.max-concurrent-publishes` | `2` | 服务端接收同时合并并发布的任务数,覆盖合并、存储发布和暂存清理 | 三项资源限制默认开启,必须填写正数;`0` 和负数都会导致启动失败。默认值按 20 GiB 文件上限预留两份暂存空间。 未完成任务不能修改分片布局;切换存储后端或 bucket 时使用新的 `workspace`。 分片由客户端按 `init` 返回的分片大小切分;单分片文件使用编号 `1`,空文件没有分片。 当前编号统一为 `1…totalChunks`,不兼容此前从 `0` 开始的未完成任务,升级时需清理旧暂存任务并重新初始化。 固定的锁条带、元数据字段和文件布局属于内部实现,不作为业务配置开放。 ### 图片、Excel、PDF 的文件类型 两种上传模式均可在初始化时指定文件级 `contentType`,省略或传 `null` 时默认 `application/octet-stream`。例如: ```java var pdf = new UploadRequest("合同.pdf", fileSize, sha256, chunkSize, "application/pdf"); var image = new UploadRequest("头像.png", fileSize, sha256, chunkSize, "image/png"); var excel = new UploadRequest("报表.xlsx", fileSize, sha256, chunkSize, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"); // 直传仍由客户端将文件字节直接 PUT 到对象存储。 var directPdf = new S3DirectUploadOperations.Request("合同.pdf", fileSize, "application/pdf"); ``` 类型在任务初始化时持久化,`init` / `status` 返回 `contentType`,重启续传沿用原值;S3 发布时设置最终对象的 `Content-Type`,空对象同样支持。 直传在 `CreateMultipartUpload` 设置类型,分段 PUT 不需要额外签名 `Content-Type`。 同一权限范围内,服务端秒传按文件 SHA-256、大小和类型复用对象,不同类型分别创建任务。 完成结果携带文件名及 `FileMetadata(fileSize, contentType, eTag, lastModified, versionId)`,下载组件复用同一快照,无需回查上传任务。自定义 `FileStorage` 的 `find` / `store` 接收文件名并须返回完整表示快照;`metadata` 必须验证快照仍可用。 组件接受具体媒体类型(含合法参数),统一规范化,拒绝空白、通配类型、控制字符及超过 256 字符的值。 类型由业务提供,组件不依据扩展名猜测,也不验证实际文件格式;需预览的业务应校验文件类型并配置自己的下载授权。 ### 进阶场景 #### HTTP 接口接入 业务 Controller 同样只注入 `UploadOperations`: | 业务接口 | 统一方法 | | --- | --- | | `POST /api/uploads/init` | `init(scope, request)`,JSON 字段为 `fileName/fileSize/fileHash/chunkSize` | | `GET /api/uploads/{uploadId}` | `status(scope, uploadId)` | | `PUT /api/uploads/{uploadId}/chunks/{chunkNo}` | `uploadChunk(scope, uploadId, chunkNo, input, hash)` | | `POST /api/uploads/{uploadId}/complete` | `complete(scope, uploadId)`,所有后端使用同一返回类型 | 分片接口使用 `try (InputStream input = file.getInputStream())` 获取并关闭输入流。 业务异常处理器可将可预期的非法参数、未完成任务转换为携带不同错误码的 `BusinessException`,统一返回 HTTP 200;I/O 失败保留为服务端错误。 8 MiB 分片的 multipart 配置可设为 `max-file-size: 12MB`、`max-request-size: 16MB`。 客户端建议限制 3~6 个并发请求。 #### 两种上传方式与资源限制 服务端接收适合本地存储、客户端无法访问对象存储、需要完整文件 SHA-256 或在发布前进行可信内容处理的场景。 S3 直传适合大型附件、视频等主要由应用授权和登记的场景;内容检查需另行安排可信处理,不能只相信扩展名或客户端类型。 两条路径可同时使用,不按文件扩展名或某个固定大小自动切换。 资源保护默认开启,以下示例展示如何按部署资源调整: ```yaml quick: start: boot: upload: max-file-size: 2GB resources: max-active-tasks-per-scope: 4 max-staging-size: 10GB max-concurrent-publishes: 2 cleanup: enabled: true interval: 1h ``` 服务端接收在创建任务时按 `2 × fileSize` 预留暂存额度,覆盖分片和合并文件同时存在的阶段; 即使任务尚未传入字节,也会占额。上述预算可同时接纳两个 2 GiB 文件,剩余额度还能接纳更小的任务。 预算由同一个 `workspace/tasks` 下的全部 scope 共用,不计最终完成文件、Servlet 临时文件、日志或自定义存储产生的额外副本。 分片重传或合并前清理崩溃残留的临时工作文件,避免其叠加在预留的两份数据之外。 任务数和暂存额度来自持久化任务记录,不使用易失计数器;重复初始化同一服务端任务不重复占额,重启后仍识别已有占用。 成功完成并清理分片后释放额度,失败的任务继续占额以便重试;过期任务在 `cleanExpired(scope)` 成功清理后才释放。 完成记录已保存但暂存未清理时仍占额,重试 `complete` 可继续回收。仅等待过期不会自动释放容量,应用仍需调度清理。 过期清理也会回收已完成任务遗留的暂存文件,同时保留完成记录和最终文件。 未完成任务先删除所有分片与临时工作文件(含 `task.tmp`、`completed.tmp`),最后删除任务记录; 清理成功后该任务作废,需重新初始化上传。中途失败保留任务记录和额度,下一次清理继续重试。 单个任务的 I/O 故障不会中断同一 scope 中其他任务的清理,失败原因汇总后交给调度器记录。 锁文件和空任务目录保留以维持跨进程互斥,不包含文件内容。 调低限制不会终止已有任务;已有占用超过新预算时拒绝新任务,继续完成或清理原任务后恢复接纳。 S3 直传使用 S3 multipart 协议,适用于 AWS S3 及符合该协议的兼容对象存储。它只应用每个 scope 的未完成任务数限制, 并在调用 `CreateMultipartUpload` 之前完成准入检查;超额请求不会创建远端 multipart 任务。 不使用本地文件暂存预算和合并发布槽位。两种模式分别计数,例如上限为 4 时,各自最多保留 4 个未完成任务。 直传中止失败时保留任务和占额,完成确认、成功中止或过期清理成功后释放。 远端任务创建与本地记录保存之间仍存在进程中断窗口,bucket 必须配置未完成 multipart 的生命周期清理。 容量不足或创建任务的容量检查正被其他请求使用时,抛出 `UploadLimitExceededException`,通过 `limit()` 区分 `ACTIVE_TASKS`、`STAGING_BYTES`、`CONCURRENT_PUBLISHES`、`ADMISSION_BUSY`。 组件不等待空位;业务可映射为 HTTP 429 并提示稍后重试。文件系统和存储故障仍作为 I/O 错误处理。 这些限制保护组件自身的任务和暂存流程,不是文件系统硬配额。 Servlet 在进入组件前可能已解析 multipart 并写临时盘,仍须配置独立的 `spring.servlet.multipart.location`、 请求大小限制及解析前的入口限流;原始字节流 PUT 可绕过 multipart 解析。 直传 URL 签发后的字节不经过组件,限制授权接口不能限制真实上传并发或带宽,需要客户端和对象存储配合。 下载的 Java 中转与预签名传输也有相同边界;本节三项参数不限制下载并发。 #### S3 存储 应用按需添加 S3 模块,SDK 不进入 core 的依赖: ```xml org.dw quick-start-boot-upload-s3 ``` 只更改配置,业务类继续注入同一个接口: ```yaml quick: start: boot: upload: enabled: true storage: s3 workspace: ./runtime/uploads-s3 s3: bucket: business-files region: ap-southeast-1 key-prefix: attachments part-size: 16MB api-call-timeout: 5m api-call-attempt-timeout: 2m ``` 默认客户端使用 AWS SDK for Java v2;未显式配置凭据时使用 SDK 默认凭据链,支持环境变量、配置文件或工作负载身份, 并在 Spring 容器关闭时关闭客户端。云上优先使用角色身份;自建对象存储可通过 Spring 外部配置注入凭据: ```yaml quick: start: boot: upload: enabled: true storage: s3 s3: bucket: ${S3_BUCKET} endpoint: ${S3_ENDPOINT} region: ${S3_REGION:us-east-1} path-style: true access-key: ${S3_ACCESS_KEY} secret-key: ${S3_SECRET_KEY} # 临时凭据可增加 session-token: ${S3_SESSION_TOKEN} ``` `access-key` 和 `secret-key` 必须成对配置;`session-token` 不能单独使用。不配置这三个属性即回退默认凭据链, 例如使用 `AWS_ACCESS_KEY_ID`、`AWS_SECRET_ACCESS_KEY`、可选 `AWS_SESSION_TOKEN` 或 `~/.aws/credentials`。 不要将真实凭据提交到仓库;配置对象的 `toString()` 会隐藏凭据。 可提供自定义 `S3Client` Bean 控制凭据、连接池、重试等行为;已有 Bean 时默认客户端退让,生命周期由其配置管理。 `quick.start.boot.upload.s3.*` 支持以下属性: | 属性 | 默认/约束 | 用途 | | --- | --- | --- | | `bucket` | 必填,须已存在 | 不自动建桶或修改权限 | | `region` | 默认客户端创建时必填 | 提供自定义 `S3Client` 时由该 Bean 决定 | | `endpoint` | AWS SDK 默认 endpoint | MinIO 等 S3 兼容服务的访问地址 | | `path-style` | `false` | 兼容服务可设为 `true` | | `access-key` / `secret-key` | 无,必须成对配置 | 显式凭据优先于 SDK 默认凭据链;支持 Spring 环境变量占位符 | | `session-token` | 无 | 临时凭据令牌,须同时配置 AK/SK | | `key-prefix` | `uploads` | 对象名前缀,最终 key 最多 1024 UTF-8 字节 | | `part-size` | `8MB`,5 MiB~5 GiB | 服务端向 S3 发送的段大小,独立于客户端 `chunkSize` | | `checksum-algorithm` | `SHA256` | 显式选择 `SHA256`、`SHA1`、`CRC32` 或 `CRC32C`;两种上传模式共用 | | `encryption` | 遵循桶策略 | 可指定 `AES256` 或 `AWS_KMS` | | `kms-key-id` | 无 | 指定时须同时配置 `AWS_KMS` | | `api-call-timeout` | `5m` | 默认客户端的完整调用超时 | | `api-call-attempt-timeout` | `2m` | 单次尝试超时,不能超过完整调用超时 | S3 特有配置只在选中 S3 且需要默认实现时校验;仅添加依赖不会创建 S3 客户端。 内部采用“服务端收分片 → 完整校验 → S3 multipart 发布”,最多 10000 段,当前对象上限 5 TiB。 每段发送所选算法的 checksum,并核对上传响应中的校验值;完整文件 SHA-256 仍写入对象元数据,秒传规则不变。 multipart ETag/组合 checksum 不作为整文件 hash。 秒传查询校验对象大小及 `sha256` 元数据,权限/网络错误直接失败;远端已完成但响应丢失时通过 HEAD 恢复结果。 失败时尝试中止远端 multipart,本地分片保留供重试;中止失败信息保留在异常的 suppressed 中。 进程中断可能遗留远端分段,请配置 bucket 的 `AbortIncompleteMultipartUpload` lifecycle 规则。 兼容后端必须支持 multipart 和所选算法的分段校验。MinIO、RustFS 等 S3 兼容服务优先复用本模块,通过 endpoint、 region、path-style 和凭据配置接入,无需为每种服务引入专用 SDK;具体版本兼容性仍需真实服务验证。 例如,确认后端支持完整的 CRC32C 分段校验流程后,可配置: ```yaml quick.start.boot.upload.s3.checksum-algorithm: CRC32C ``` 默认继续使用 SHA-256。CRC 算法用于检测传输损坏,不提供密码学抗碰撞保证;SHA-1 也不适合作为抗碰撞安全依据。 本模块不自动探测、不自动降级,也没有关闭 checksum 的选项。不支持所选算法时上传失败; 直传还要求 `ListParts` 返回相应校验字段,否则拒绝完成。只有原生 MD5/CRC64 能力的服务不能仅改算法配置接入。 `CRC64NVME` 涉及不同的整对象校验流程,本次不支持。 2026-10-10 使用现有 AWS SDK v2 `2.31.78` 对真实容器服务实测,未接入厂商 SDK。下表为 SHA256 配置的结果: | 服务版本 | 服务端统一接收 | 对象存储直传 | 实测结果 | | --- | --- | --- | --- | | MinIO `RELEASE.2025-09-07T16-13-09Z` | 通过 | 通过 | 5 个兼容测试全部通过 | | SILO `RELEASE.2026-09-16T00-00-00Z` | 通过 | 通过 | SHA256、SHA1、CRC32、CRC32C 各 5 项测试,20/20 通过 | | RustFS `1.0.1`(commit `6de965ae3c965a78ff819fbcd7acd4aa44177d92`) | 通过 | 完成阶段受阻 | 5 个测试中 4 个通过;`ListParts` 原始 XML 缺少分段 `ChecksumSHA256`,当前完整性校验拒绝合并 | 算法配置扩展后,MinIO 对 SHA256、SHA1、CRC32、CRC32C 分别运行同一套真实服务测试,合计 20/20 通过。 SILO 使用 [PGSTY 官方标准镜像](https://silo.pgsty.com/download/),从新增 Compose 启动后实测,继续复用 AWS SDK。 四种算法均覆盖服务端分段发布与空对象、直传乱序/缺段/重启续传/重复完成、错误内容和签名篡改拒绝、中止幂等; 直传测试客户端直接 PUT 到对象存储,应用 workspace 只保存控制文件。 三套独立单机编排包含固定镜像、持久化、账号配置与健康检查,入口为 [MinIO](docker/minio/README.md)、[RustFS](docker/rustfs/README.md)、[SILO](docker/silo/README.md)。 RustFS 能拒绝错误分段内容和被篡改的签名 checksum,`UploadPart` 也返回 SHA-256 checksum; 但 `ListParts` 未返回该字段,换用厂商 SDK 无法补出服务响应缺失的信息。 当前不降低直传校验要求;RustFS 直传需等待服务修复,并重新验证。 MinIO 已验证多段发布、空文件、hash 秒传、直传乱序上传与重启续传、重复完成、内容及签名篡改拒绝、中止幂等。 直传测试由测试客户端直接 PUT 到对象存储,并确认应用 workspace 仅保存控制文件。 以上结论限于所列版本和本地 HTTP 环境,尚未验证云厂商、浏览器 CORS、TLS、SSE/KMS 或高并发。 兼容测试默认跳过。复现时启动独立的本地测试服务,例如: ```shell docker run --detach --name upload-compat-minio -p 127.0.0.1:19000:9000 -e MINIO_ROOT_USER=upload-compat-access -e MINIO_ROOT_PASSWORD=upload-compat-secret minio/minio@sha256:14cea493d9a34af32f524e538b8346cf79f3321eff8e708c1e2960462bd8936e server /data docker run --detach --name upload-compat-rustfs -p 127.0.0.1:29000:9000 -e RUSTFS_ACCESS_KEY=upload-compat-access -e RUSTFS_SECRET_KEY=upload-compat-secret rustfs/rustfs@sha256:1803faef57627e2d9c2e7d89d655d712ddded5389040054987163043fecb6a3c mvn -q -pl quick-start-boot-upload-s3 -am verify -Dtest=S3StorageCompatibilityTest -Ds3.compat.endpoint=http://127.0.0.1:19000 -Dfile.encoding=UTF-8 # 将 endpoint 改为 http://127.0.0.1:29000 可复现 RustFS 的失败断言。 docker stop upload-compat-minio upload-compat-rustfs docker rm --volumes upload-compat-minio upload-compat-rustfs ``` 固定凭据仅用于上述隔离测试容器。测试会创建随机命名的独立 bucket,结束时清理该 bucket 的对象、未完成分段和 bucket 本身; 不要将此测试指向生产服务。 可额外传入 `-Ds3.compat.checksum-algorithm=CRC32C`(或其他受支持算法),按指定算法运行两种模式的全部兼容测试。 #### 对象存储大文件直传 服务端统一接收模式继续使用 `UploadOperations`;直传是独立且可同时启用的控制接口,文件分段不经过应用服务端。 在上述 S3 配置下增加: ```yaml quick: start: boot: upload: s3: direct: enabled: true signature-duration: 15m ``` 业务服务注入 `quick.start.boot.upload.s3.S3DirectUploadOperations`,从可信鉴权上下文获取 scope。 以下业务方法覆盖初始化、授权、恢复和完成;HTTP Controller 由应用实现: ```java import java.io.IOException; import quick.start.boot.upload.StoredFile; import quick.start.boot.upload.s3.S3DirectUploadOperations; public class DirectAttachmentService { private final S3DirectUploadOperations uploads; public DirectAttachmentService(S3DirectUploadOperations uploads) { this.uploads = uploads; } public S3DirectUploadOperations.Status init(String scope, String fileName, long size) throws IOException { return uploads.init(scope, new S3DirectUploadOperations.Request(fileName, size)); } public S3DirectUploadOperations.PartUrl authorizePart(String scope, String id, int number, String checksumHex) throws IOException { return uploads.presignPart(scope, id, number, checksumHex); } public S3DirectUploadOperations.Status resume(String scope, String id) throws IOException { return uploads.status(scope, id); } public StoredFile complete(String scope, String id) throws IOException { return uploads.complete(scope, id); } } ``` 客户端流程: 1. 调用初始化接口,保存 `uploadId`;按返回的 `partSize` 切片,分段从 **1** 编号。 2. 根据 `init` / `status` 返回的 `checksumAlgorithm` 计算当前分段校验值,使用十六进制请求 `presignPart`: SHA256 为 64 位、SHA1 为 40 位、CRC32/CRC32C 为 8 位(大端顺序,保留前导零)。获得 `url`、签名 `headers`、`size` 和 `expiresAt`。 checksum 绑定到本次上传授权,对象存储验证实际分段内容;服务端不持久化分段 checksum 清单。 3. 使用 **PUT** 将该分段原始字节发送到 URL,不能使用 multipart/form-data。必须保持签名请求头及分段长度一致; 浏览器的 Host、Content-Length 由浏览器生成,其余签名头按返回值设置。URL 是短期授权,不应记录或转发给其他用户。 4. 失败后重签当前分段;断点恢复调用 `status`,`uploadedParts` 来自对象存储实际的 `ListParts`,仅补传缺失分段。 5. 调用 `complete`,服务端自行读取全部分页,校验连续编号、数量、长度、ETag 和任务算法对应的 checksum 格式, 将对象存储实际返回的 ETag 和 checksum 提交到完成请求。网络失败使用同一 `uploadId` 重试; 远端已完成时通过 HEAD、对象大小和任务标识恢复结果。对象目录须由服务独占维护。 | 配置/边界 | 说明 | | --- | --- | | `s3.direct.enabled` | 默认 `false`,仅在上传开启且选中默认 S3 后端时生效 | | `s3.direct.signature-duration` | 默认 `15m`,必须为正、最多 7 天且不超过 `idle-timeout`;临时凭据可能更早失效 | | `s3.part-size` | 直传分段大小的起点,超大文件自动增大至不超过 10000 段,与服务端 `max-chunk-size` 独立 | | `max-file-size` / `max-file-name-length` | 两种模式共用限制;直传最多 5 TiB,空文件使用服务端接收模式 | | `idle-timeout` | 直传任务按最后一次签发分段 URL 的时间计时;到期后不能继续签发或完成,可查询状态并清理 | | `workspace/direct-tasks` | 保存任务元数据和锁,不保存文件分段;进程重启可恢复,多实例须共用支持文件锁和原子移动的目录 | `abort(scope, uploadId)` 中止未完成的远端 multipart 并移除任务元数据;重复中止幂等,不删除已完成对象。 组件提供可选的清理调度器。配置 `cleanup.enabled=true` 后,组件会按 `cleanup.interval` 调用 无参 `cleanExpired()`,自动发现全部范围的已有任务;单个任务清理失败不阻断其他任务,失败记录在下一周期重试。 未启用调度器时,应用仍可自行调用该后台管理方法,无需维护用户或租户列表。 远端中止失败时保留任务以便重试。完成任务元数据和锁文件保留。 创建远端任务后、保存本地记录前的进程中断仍可能遗留分段,必须配置 bucket 的未完成 multipart lifecycle 清理规则。 例如 AWS CLI 可为整个 bucket 设置 1 天后中止未完成 multipart: ```shell aws s3api put-bucket-lifecycle-configuration --bucket uploads --lifecycle-configuration '{"Rules":[{"ID":"abort-incomplete-multipart","Status":"Enabled","Filter":{"Prefix":""},"AbortIncompleteMultipartUpload":{"DaysAfterInitiation":1}}]}' ``` 该命令会替换 bucket 的整个 lifecycle 配置;已有规则应先读取后合并,且按实际文件前缀限制作用范围。 生命周期按任务创建时间计时,与组件按闲置时间过期不同,期限应大于允许的最长上传总时长,避免中止仍活跃的长任务。 MinIO、Silo、RustFS 等兼容服务需确认对应版本的 lifecycle 支持并配置同等规则;该规则中止未完成 multipart,不删除已完成对象。 两种模式都提供完整性校验:服务端接收会计算完整文件 SHA-256;直传由对象存储验证签名绑定的所选分段 checksum, 服务端确认实际分段的顺序、数量、大小及完成对象大小,并以远端分段清单提交合并,保障传输与组装完整性。 直传**不读取整个对象重新计算完整文件 SHA-256,也不提供完整文件 hash 秒传**。 直传同样返回 `StoredFile(location, fileName, sha256, metadata)`,其中 `sha256=null`;对象使用独立的 `direct/` 前缀。 预期分段 checksum 来自调用方,不代表文件来源可信。 需要标准整文件 SHA-256 比对、内容审查或转换时,应使用服务端接收模式或在直传后另做可信处理。 任务仓兼容已有任务记录;旧的额外 checksum 清单和完成准备字段会被忽略,后续保存时移除,无需重新登记分段。 直传任务持久化创建时的算法,重启或修改配置不会改变旧任务;旧记录没有算法字段时按 SHA256 恢复。 `Part.checksum` 为 Base64 校验值,`checksumAlgorithm` 标识算法;原 `checksumSha256()` 仅在 SHA256 任务中返回值。 浏览器必须能访问签名使用的对象存储 endpoint;反向代理不能改变已签名的 Host、路径或查询参数。 bucket CORS 至少应允许业务前端来源、PUT 和签名使用的请求头(默认包括 `x-amz-checksum-sha256`,其他算法使用对应请求头)。 签名服务身份需要 multipart 创建、分段上传、ListParts、完成、中止及 HEAD 所需权限,SSE-KMS 还需相应 KMS 权限。 默认 `S3Presigner` 复用注入客户端的 region、凭据提供器和 endpoint,path-style 使用组件配置;自定义客户端有特殊地址策略时, 可同时提供自定义 `S3Presigner` Bean。提供自定义 `S3DirectUploadOperations` 时默认直传设施退让。 #### 接口扩展与运行边界 普通服务端上传和下载只需注入 `UploadOperations` 和 `DownloadOperations`;S3 直传与预签名分别使用 `S3DirectUploadOperations` 和 `S3DownloadOperations`,作为传输方式的高级能力。 `FileStorage` 是统一的文件读写 SPI, 封装完成文件的发布、查找、元数据查询和固定版本区间读取。生命周期编排、任务仓、锁、校验合并、 本地和 S3 存储实现均封装在内部。应用注册自定义 `FileStorage` Bean 后,默认存储退让; 仅开启上传时,其默认 S3 客户端也退让;S3 预签名和直传使用客户端及签名器。 注册自定义 `UploadOperations` Bean 时,默认上传基础设施整体退让。 自动配置通过 `AutoConfiguration.imports` 发现,不依赖扫描内部实现,也不需要手动创建上传服务。 同一任务的写入、合并和清理通过 JVM 锁及文件锁串行执行,不同任务可以并行。 任务状态和完成表示持久化,重复完成及重启恢复绑定同一快照;文件名沿用同一去重任务首次初始化的名称, 需要展示其他名称时由业务重命名,不改变内容去重。进程中断后的临时合并文件在重试时覆盖;锁文件和空任务目录保留,避免替换锁对象。 合并阶段本地空间需要覆盖分片与完整文件两份数据;可启用上述任务暂存预算,完成文件容量仍由存储侧管理。 目录及完成对象由服务独占维护,拒绝符号链接;外部改写同长度对象不会在 HEAD 时重新计算文件 hash。 原子移动保障进程中断时的可见性,不承诺断电时的数据持久性。 #### 多实例部署限制 多实例指同一个上传服务运行多个副本,由负载均衡分发请求。例如初始化请求到实例 A,后续分片、状态查询或完成请求可能到实例 B。 当前任务仓基于文件;各实例使用独立本地 `workspace` 时,B 无法读取 A 的任务记录,不能接续同一任务。 共用同一个 S3 bucket 不会自动同步任务仓。重启恢复也依赖原任务目录仍然存在,Pod 临时磁盘丢失后无法仅凭 `uploadId` 恢复任务。 | 上传方式 | 当前多实例部署要求 | | --- | --- | | 服务端接收分片(本地或 S3 后端) | 共享任务记录、锁、分片和合并工作目录;即使最终文件存入 S3,上传期间仍依赖共享 `workspace` | | S3 直传 | 分片保存在 S3,但任务记录和锁仍在 `workspace/direct-tasks`,该目录必须由各实例共享 | 共享目录必须在实例之间提供有效的文件锁及原子移动语义;各实例还需使用一致的任务与存储配置。 开启资源限制的所有实例还须使用一致的限制配置。任务准入和发布槽位使用共享工作目录内的文件锁协调; 进程退出后操作系统释放槽位,锁文件保留;不同本地工作目录之间不提供集群总额度。 本地文件后端还需共享完成文件目录,确保各实例都能访问同一文件。仅配置会话粘滞只能让请求尽量回到原实例,不能替代实例故障后的任务接管。 当前不提供 Redis 或数据库任务仓,也没有可单独替换的公开任务仓 SPI。应用需要其他任务持久化方案时,可通过自定义 `UploadOperations` 或 `S3DirectUploadOperations` 替换相应默认实现。 未来若提供 Redis 或数据库任务仓,S3 直传可解除任务仓对共享文件系统的依赖;普通分片上传仍需同时解决分片跨实例访问问题。 任务仓还需处理并发状态迁移、完成结果持久化、过期回收,以及任务状态与 S3 操作之间的失败恢复;仅保存元数据或增加分布式锁不足以保证任务可接管。 ## 文件下载与断点续传 ### 最小可运行示例 下载复用 `quick-start-boot-upload` 依赖,单独开启下载即可注入 `DownloadOperations`; 本地与 S3 共用该入口,按配置装配 `FileStorage`,不要求开启上传。本地只读访问不创建任务或存储目录。 业务应用使用自己的 `spring-boot-starter-web` 提供 HTTP 接口。 ```yaml quick: start: boot: upload: storage: file workspace: ./runtime/uploads download: enabled: true ``` 以下服务可以直接放入 Spring MVC 应用。Controller 先按业务 `fileId` 校验登录用户权限, 从业务文件表读取上传完成时保存的完整 `StoredFile`,再调用该服务;不要从请求体构造文件引用。 ```java import java.io.IOException; import org.springframework.http.HttpHeaders; import org.springframework.http.HttpMethod; import org.springframework.http.ResponseEntity; import org.springframework.stereotype.Service; import org.springframework.web.servlet.mvc.method.annotation.StreamingResponseBody; import quick.start.boot.upload.DownloadOperations; import quick.start.boot.upload.DownloadRequest; import quick.start.boot.upload.StoredFile; @Service public class AttachmentDownloadService { private final DownloadOperations downloads; public AttachmentDownloadService(DownloadOperations downloads) { this.downloads = downloads; } public ResponseEntity download(StoredFile authorizedFile, HttpMethod method, HttpHeaders requestHeaders) throws IOException { var result = downloads.prepare(new DownloadRequest(authorizedFile), method, requestHeaders); return ResponseEntity.status(result.statusCode()) .headers(result.headers()).body(result::writeTo); } } ``` Controller 将 `GET` / `HEAD /api/files/{fileId}` 映射到该方法,传入原始请求方法及请求头,直接返回其结果。 下载准备阶段的文件不存在可映射为 404,越权由业务鉴权层返回 403;其他 I/O 错误保留为服务端错误。 流式写出由 Spring MVC 管理,业务应配置适合下载时长的异步超时和执行器。 ### 示例逐段解释 - `StoredFile` 是本地、服务端 S3 上传和 S3 直传共用的完成文件记录,保存 `location/fileName/sha256/metadata`,其中 `metadata` 保存大小、类型、ETag、修改时间和版本号; 上传完成确定快照,下载校验并复用。直传没有完整文件 SHA-256,`sha256` 为 `null`。 S3 开启版本管理时保存上传完成的 `versionId`,之后查询和下载始终读取该版本;本地及无版本对象为 `null`。 - `DownloadRequest(file)` 默认沿用上传文件名;业务重命名使用 `DownloadRequest(file, fileName)`。 只接受业务鉴权后的记录,文件名用于 `Content-Disposition: attachment`; 支持中文文件名,拒绝控制字符和路径分隔符。展示文件名属于业务记录,不影响存储位置和内容去重。 - `prepare` 返回状态码、只读响应头和按需写出的响应体;不依赖上传任务、不保存服务端下载进度, 不打开 HEAD、304、412 或 416 的文件流。`writeTo` 以 64 KiB 缓冲区读取指定区间,不关闭业务输出流。 本地和 S3 都通过同一流程传输,客户端断开时关闭文件流或中止未消费的 S3 响应。 - `metadata(authorizedFile)` 返回存储查询的 `FileMetadata(fileSize, contentType, eTag, lastModified, versionId)`, 供业务查询文件信息,结果须与 `authorizedFile.metadata()` 相同。存储表示被替换时失败,不能重新采集快照后静默接受。 `FileStorage.open` 须按该快照读取,版本变化或返回区间不符时失败。 - 本地仅允许当前 `workspace/files` 内的完成文件布局,拒绝符号链接和任意路径。 完成目录须由服务独占维护;ETag 根据文件 hash、大小、修改时间和文件标识生成,避免每次下载重新扫描大文件。 首次请求返回 `200`,包含 `Content-Length`、`Content-Type`、`Content-Disposition`、 `Accept-Ranges: bytes`、`ETag`、`Last-Modified` 和 `Cache-Control: private, no-store`。 客户端保存已下载字节数和 ETag,恢复时发送: ```http GET /api/files/{fileId} Range: bytes=10485760- If-Range: "<首次响应的 ETag>" ``` ETag 匹配时返回 `206` 和 `Content-Range`,客户端追加响应字节;不匹配时返回 `200`, 客户端必须丢弃旧片段并重新下载。下载速度、进度、暂停、重试及本地片段持久化由客户端实现。 | 请求情况 | DownloadOperations 响应 | | --- | --- | | 无 Range | `200`,完整文件 | | `bytes=start-end`、`bytes=start-`、`bytes=-length` | `206`,指定区间;结束位置超过文件长度时截断 | | 区间越界、无效 bytes 区间、空文件带区间 | `416`,`Content-Range: bytes */`,空响应体 | | If-Range 不匹配或弱 ETag | `200`,完整文件 | | If-Range 日期 | 精确匹配 Last-Modified 且文件至少 60 秒未修改时续传,否则返回 `200`;推荐使用 ETag | | If-Match 不满足,或无 If-Match 时 If-Unmodified-Since 不满足 | `412`,空响应体 | | If-None-Match 命中,或无 If-None-Match 时 If-Modified-Since 未修改 | `304`,空响应体 | | HEAD | 条件请求检查后返回状态及元数据,忽略 Range,空响应体 | | 合法多区间或未知 Range 单位 | `200`,完整文件,不生成 multipart/byteranges | 条件请求先于 Range 求值。If-Match 使用强 ETag 比较,If-None-Match 允许弱 ETag; 无效日期忽略。文件流延迟到写出时打开,准备之后发生存储变化或读取失败时中止响应; 客户端必须按响应声明的长度检查完整性,不能把中断响应当成下载完成。 ### 常用属性说明 | 属性 | 默认值 | 用途 | | --- | --- | --- | | `quick.start.boot.download.enabled` | `false` | 独立开启下载,默认不暴露 Controller | | `quick.start.boot.download.signature-duration` | `15m` | S3 GET 授权时长,1 秒至 7 天;临时凭据可能更早失效 | | `quick.start.boot.upload.storage` | `file` | 下载后端与上传共用 `file` / `s3` 选择 | | `quick.start.boot.upload.workspace` | `./runtime/uploads` | 本地下载读取 `files`,不读取 `tasks` | | `quick.start.boot.upload.s3.*` | 同上传配置 | 共用 bucket、key-prefix、endpoint、region 和凭据 | ### 进阶场景:S3 预签名下载 添加 `quick-start-boot-upload-s3`,沿用上文的 S3 配置,再开启 `quick.start.boot.download.enabled`。 S3 默认也支持上述 `DownloadOperations` 流式下载。大文件希望由对象存储直接传输时, 业务注入 `S3DownloadOperations` 签发授权,客户端直接连接 S3。 上传关闭时也可单独签发下载授权;与上传同时开启时复用同一个 `S3Client` 和 `S3Presigner`。 ```java import quick.start.boot.upload.DownloadRequest; import quick.start.boot.upload.s3.S3DownloadOperations; // authorizedFile 来自业务鉴权后的完整文件记录。 var authorization = downloads.presign(new DownloadRequest(authorizedFile)); // 将 authorization 返回给客户端,包含 url、headers、expiresAt、eTag、versionId。 ``` 客户端使用 **GET** 访问 `url`,携带返回的全部 `headers`;Host 由 HTTP 客户端生成。 Range 不参与签名,同一个授权可下载完整内容或指定区间。预签名绑定下载文件名、类型及 `If-Match`; 完成记录携带 `versionId` 时固定该版本,同名对象更新后仍可读取原内容并重新签发授权。 无版本对象通过 `If-Match` 防止同一次授权混用内容;对象被替换后旧授权返回 `412`,客户端应停止追加, 使用原完成记录重新授权也会失败。业务更新文件时必须保存新上传返回的完整记录。 ETag 是版本校验标识,不能把 S3 multipart ETag 当作完整文件 SHA-256。 URL 过期时重新调用业务授权接口;继续追加前须比较新授权的 `eTag` / `versionId` 与已保存值, 不同则重新下载。签名要求携带 `If-Match`,因此不能直接用普通浏览器链接或重定向省略请求头。 大文件客户端应将响应流写入文件,不将整个文件读成 `byte[]` 或 Blob。 bucket CORS 应允许前端来源、GET、HEAD 和 `Range` / `If-Match` 请求头,并暴露 `ETag`、`Content-Length`、`Content-Range`、`Accept-Ranges`、`Content-Disposition`。 签名服务需要对象 HEAD/GET 权限;固定版本下载需 `s3:GetObjectVersion`,SSE-KMS 需解密权限。 预签名 URL 是临时授权,不记录到公开日志;只授权当前配置 bucket 和 key-prefix 内的完成对象。 可注册自定义 `DownloadOperations` 或 `S3DownloadOperations` Bean 替换对应默认实现。 2026-10-13 下载实测:本地真实 HTTP 请求覆盖完整下载、Range 续传、HEAD 和 416; MinIO `RELEASE.2025-09-07T16-13-09Z` 覆盖服务端上传对象和直传对象的统一流式下载及预签名下载、 空对象、中文文件名、Range、条件请求、签名篡改拒绝、无版本对象替换后的 412, 以及开启版本管理后更新同名对象仍可读取并重新授权完成版本。RustFS `1.0.1` 的服务端上传对象和空对象预签名下载通过; 直传仍受上文已有的 ListParts checksum 缺失限制。未实测云端 AWS、浏览器 CORS、TLS、SSE/KMS 和高并发。 ## 数据掩码模块 ### 最小可运行示例 业务模块统一依赖启动器: ```xml org.dw quick-start-boot-masking-starter ``` 在字符串属性上通过类型安全的注解声明策略: ```java public record UserView( @Mask(strategy = MobilePhoneMaskingStrategy.class) String mobilePhone, @Mask(strategy = EmailMaskingStrategy.class) String email) { } ``` 启动器会把数据掩码模块注册到仓库统一的 `ObjectMapper`。属性值为 `null` 时保持 `null`;策略、决策器配置错误或执行失败时直接抛出异常,不会降级输出原始值。 ### 注解参数 - `strategy`:必填,指定实现 `MaskingStrategy` 的掩码策略类型。 - `policy`:选填,指定实现 `MaskingPolicy` 的决策器类型,默认使用 `AlwaysMaskingPolicy`。 - 注解仅允许用于字符串字段、访问方法或记录组件。 ### 内置策略 模块内置身份证号码、手机号码、地址、电子邮箱、银行卡号、中文姓名、固定电话号码、用户标识、密码、互联网协议地址、机动车号牌、首字符保留、空字符串和空值等策略。使用方直接在 `@Mask` 中引用对应策略类型,不使用字符串策略名。 ### 自定义策略和决策器 自定义策略与决策器均作为 Spring Bean 注册,自动配置会在应用启动时收集并冻结组件索引: ```java @Bean CurrentUserMaskingPolicy currentUserMaskingPolicy() { return new CurrentUserMaskingPolicy(); } ``` ```java @Mask( strategy = ChineseNameMaskingStrategy.class, policy = CurrentUserMaskingPolicy.class ) private String name; ``` `MaskingPolicy` 可自行读取当前业务上下文;数据掩码核心模块不认识角色、权限或具体认证框架。本次重构不提供兼容层。 ### 6. 当前仓库 JSON 依赖路径核对结论 这次也顺手把整个仓库里引用 `quick-start-boot-json-*` 的模块扫了一遍,当前结论是统一的,主要分成三类: - 业务 starter / 自动装配入口走 `quick-start-boot-json-starter` - 例如: - `quick-start-boot-cache-starter` - `spring-boot-starter-netty` - `quick-start-boot-reliable-message` 各 producer / consumer starter - 纯契约模块走 `quick-start-boot-json-api` - 例如: - `quick-start-boot-reliable-message-core` - `spring-boot-starter-netty-api` - `spring-boot-starter-netty-common` - 底层实现或测试辅助按需走 `quick-start-boot-json-core` - 例如: 也就是说,当前仓库里没有发现“业务 starter 绕开 `quick-start-boot-json-starter`,自己重新拼一套 JSON 运行时”的情况。 后续新增模块时,统一按这条规则判断即可: - 只要模块要对外提供统一 JSON 运行时能力,就走 `quick-start-boot-json-starter` - 只暴露接口契约,就走 `quick-start-boot-json-api` - 只在实现层或测试层需要底层实现,再按需走 `quick-start-boot-json-core` ## MQTT 模块 `quick-start-boot-mqtt` 已统一为单核心、多适配器结构,当前定位是: - `quick-start-boot-mqtt-api` 与 `quick-start-boot-mqtt-core` 作为唯一公共契约与核心能力 - 业务侧统一通过 `BusinessProtocolAdapter`、`ProtocolMessageHandler`、`ProtocolGateway` 扩展 - 底层传输通过适配器模块接入,Spring Integration 不再作为独立框架产品存在 - 框架统一提供配置校验、异常模型、默认拦截器、统一失败链路与生命周期管理 ### 传输适配模块 - `quick-start-boot-mqtt-transport-paho-v3` - `quick-start-boot-mqtt-transport-paho-v5` - `quick-start-boot-mqtt-transport-spring-integration-v3` - `quick-start-boot-mqtt-transport-spring-integration-v5` ### 依赖方式 同一应用在同一协议版本下只能引入一个传输实现,请勿同时引入 Paho 与 Spring Integration 的同版本模块。 使用 Paho MQTT v3: ```xml org.dw quick-start-boot-mqtt-transport-paho-v3 ${project.version} ``` 使用 Paho MQTT v5: ```xml org.dw quick-start-boot-mqtt-transport-paho-v5 ${project.version} ``` 使用 Spring Integration MQTT v3: ```xml org.dw quick-start-boot-mqtt-transport-spring-integration-v3 ${project.version} ``` 使用 Spring Integration MQTT v5: ```xml org.dw quick-start-boot-mqtt-transport-spring-integration-v5 ${project.version} ``` ### 配置结构 统一使用 `spring.mqtt` 前缀: ```yaml spring: mqtt: connection: protocol-version: v3 uris: - tcp://localhost:1883 username: demo password: demo clean-session: true automatic-reconnect: true connection-timeout: 30 keep-alive-interval: 60 max-reconnect-delay: 10000 inbound: client-id: demo-inbound auto-startup: true subscriptions: - topic: device/+/up qos: 1 allowed-topic-patterns: - device/+/up max-payload-size: 1048576 max-messages-per-second: 1000 outbound: client-id: demo-outbound default-topic: device/reply default-qos: 1 retained: false protocol: strict-matcher-validation: true ``` ### 协议接入示例 定义业务协议适配器: ```java package demo.mqtt; import java.nio.charset.StandardCharsets; import java.util.List; import java.util.Map; import org.dw.mqtt.api.model.MqttInboundEnvelope; import org.dw.mqtt.api.model.MqttOutboundEnvelope; import org.dw.mqtt.api.model.ProtocolSendRequest; import org.dw.mqtt.api.spi.BusinessProtocolAdapter; import org.springframework.stereotype.Component; @Component public class DeviceUpProtocolAdapter implements BusinessProtocolAdapter { @Override public String protocolId() { return "device-up"; } @Override public Class payloadType() { return DeviceUpMessage.class; } @Override public List inboundTopicPatterns() { return List.of("device/+/up"); } @Override public boolean supports(MqttInboundEnvelope envelope) { return envelope.topic().startsWith("device/") && envelope.topic().endsWith("/up"); } @Override public DeviceUpMessage decode(MqttInboundEnvelope envelope) { String body = new String(envelope.payload(), StandardCharsets.UTF_8); return new DeviceUpMessage(envelope.topic(), body); } @Override public MqttOutboundEnvelope encode(ProtocolSendRequest request) { return new MqttOutboundEnvelope( "device/reply", request.payload().body().getBytes(StandardCharsets.UTF_8), 1, false, Map.of("protocolId", request.protocolId())); } } ``` 定义业务处理器: ```java package demo.mqtt; import org.dw.mqtt.api.model.MqttInboundEnvelope; import org.dw.mqtt.api.spi.ProtocolMessageHandler; import org.springframework.stereotype.Component; @Component public class DeviceUpMessageHandler implements ProtocolMessageHandler { @Override public Class payloadType() { return DeviceUpMessage.class; } @Override public void handle(DeviceUpMessage payload, MqttInboundEnvelope envelope) { System.out.println("收到设备上报:" + payload.body()); } } ``` 统一发送业务消息: ```java package demo.mqtt; import org.dw.mqtt.api.gateway.ProtocolGateway; import org.dw.mqtt.api.model.ProtocolSendRequest; import org.springframework.stereotype.Service; @Service public class DeviceMessagePublisher { private final ProtocolGateway protocolGateway; public DeviceMessagePublisher(ProtocolGateway protocolGateway) { this.protocolGateway = protocolGateway; } public void publish(String body) { protocolGateway.send(ProtocolSendRequest.of( "device-up", new DeviceUpMessage("device/reply", body))); } } ``` 当业务确实需要直接操作原始 topic/qos/retain 时,可以注入 `MqttTransportClient`。 ### 默认能力与异常模型 默认启用以下全局入站能力: - `LoggingInterceptor`:记录基础接收日志 - `PayloadValidationInterceptor`:校验主题白名单与最大载荷 - `RateLimitInterceptor`:按配置限制入站吞吐 统一异常基类为 `MqttException`,常见子类包括: - `MqttConfigurationException` - `MqttConnectionException` - `MqttPublishException` - `MqttSubscribeException` - `ProtocolDecodeException` - `ProtocolEncodeException` - `ProtocolRouteNotFoundException` - `BusinessHandlerException` 所有异常统一携带 `errorCode`、`category`、`retryable`、`context`,入站未处理异常会发布 `MqttInboundFailureEvent`。 ## Jackson 模块 `quick-start-boot-json` 当前定位不是“可切换实现的通用 JSON 抽象层”,而是**面向 Jackson 的统一封装层**。 这样定义它的目的有两个: - 第一,让仓库内所有 Jackson 配置、序列化入口、异常语义和多态扩展点有统一收口,不再散落在各模块里各写一套。 - 第二,让业务应用接入时只需要关心统一入口,不需要自己拼装 `ObjectMapper`、时间模块、大整数序列化规则和多态注册逻辑。 当前它采用聚合工程结构,形式与 `quick-start-boot-spring-netty`、`quick-start-boot-cache` 保持一致: - 物理目录:`quick-start-boot-json/api` - 对外 `artifactId`:`quick-start-boot-json-api` - 物理目录:`quick-start-boot-json/core` - 对外 `artifactId`:`quick-start-boot-json-core` - 物理目录:`quick-start-boot-json/autoconfigure` - 对外 `artifactId`:`quick-start-boot-json-autoconfigure` - 物理目录:`quick-start-boot-json/starter` - 对外 `artifactId`:`quick-start-boot-json-starter` - 聚合目录 `quick-start-boot-json` 本身只负责组织子模块,不作为业务应用依赖入口 这几个目录名为什么要收短: - 物理目录短,避免出现 `quick-start-boot-json/quick-start-boot-json-core/...` 这种重复路径 - 对外 `artifactId` 仍然保持完整语义,业务接入和文档说明不会变模糊 - 后续如果继续扩子模块,路径层级也更容易维护 ### 推荐使用方式 业务应用依赖方式如下: - 这里依赖的是 `quick-start-boot-json-starter` - 它会把 Jackson 基础依赖和本项目自己的自动装配一起带进来 - 业务项目通常不需要单独再拼 `api/core/autoconfigure` ```xml org.dw quick-start-boot-json-starter ${project.version} ``` - 业务侧统一注入 `JsonOperations` - 不再使用旧的 `JsonUtils` - 不再在业务代码中重复创建全局 `ObjectMapper` 下面这个示例为什么这样写: - `JsonOperations` 是对业务开放的统一 Jackson 入口 - 业务服务只依赖这个接口,不需要知道底层 `ObjectMapper` 是怎么装配的 - `toJson` 调用走的是项目统一配置,因此会自动继承时间格式、大整数安全序列化等规则 ```java package demo.json; import org.springframework.stereotype.Service; import quick.start.boot.json.api.JsonOperations; @Service public class DemoJsonService { // 统一注入 Jackson 封装入口,而不是在服务里自己 new ObjectMapper private final JsonOperations jsonOperations; public DemoJsonService(JsonOperations jsonOperations) { this.jsonOperations = jsonOperations; } // 执行后会按框架统一规则完成序列化 public String toJson(Object value) { return jsonOperations.toJson(value); } } ``` ### 配置前缀 统一使用 `quick.start.boot.json`: 这段配置里最常用的几个参数含义如下: - `date-format` - 影响传统 `Date` / `Calendar` 类型的输出格式 - `local-date-time-format` - 影响 `LocalDateTime` 的统一输出格式 - `write-dates-as-timestamps` - 控制日期是否按时间戳输出;大多数业务场景建议保持 `false` - `safe-number-to-string` - 控制超出 JavaScript 安全整数范围的 Long / BigInteger 是否转字符串;前后端交互场景建议保持 `true` ```yaml quick: start: boot: json: date-format: yyyy-MM-dd HH:mm:ss local-date-time-format: yyyy-MM-dd HH:mm:ss pretty-print: false write-dates-as-timestamps: false fail-on-unknown-properties: false field-visibility: false safe-number-to-string: true ``` ### 扩展点 - 需要注册 JSON 多态子类型时,声明 `JsonSubtypeRegistrar` Bean - 上层模块不应再直接接管全局 `ObjectMapper` - `spring-boot-starter-netty` 已改为通过公开扩展点注册 `Message` 多态类型 ## 提交前 Java 自动格式化 本仓库统一使用 Spring Java Format 0.0.41,并通过根目录的 `.springjavaformatconfig` 固定为 Spring Java Format 11 基线和 4 空格缩进。项目编译版本仍为 JDK 17,格式基线不改变编译版本。 项目级 pre-commit hook 只格式化 Git index 中准备提交的 Java 版本,并将格式化结果写回当前 commit。 同一个 Java 文件可以在 IDEA 中按 ChangeList 拆分提交;未选择的代码不会进入 Git index。 首次克隆后,在仓库内执行一次以下命令。该命令可直接用于 PowerShell、CMD、Bash、Zsh 和 IDEA Terminal: ```bash git config --local core.hooksPath .githooks ``` 执行以下命令确认配置已经生效,预期输出为 `.githooks`: ```bash git config --local --get core.hooksPath ``` 手动格式化整个 Maven reactor: ```bash mvn -DskipTests spring-javaformat:apply ``` 只检查格式而不修改文件: ```bash mvn -DskipTests spring-javaformat:validate ``` 标准 Maven 门禁绑定在 `verify` 阶段,后续 CI 直接执行以下命令即可同时完成构建和格式检查: ```bash mvn verify ``` 注意事项: - `mvn compile` 和 `mvn test` 不会自动修改或校验源码格式。 - `mvn verify` 发现格式违规时会失败,但不会修改源码。 - 未执行 git add 的 Java 文件不会参与本次格式化。 - 同一个 Java 文件同时存在已暂存和未暂存修改时,hook 会在临时目录分别格式化暂存版本和工作区版本, 只将暂存版本写入 commit,并保留工作区中的未提交内容。若工作区版本暂时无法格式化,hook 会尝试通过 三方合并同步格式变化;只有无法安全合并时才会保持工作区和 Git index 不变并中止提交。此时请先在 IDEA 中格式化该文件,或调整 ChangeList 后重试。 - Java 源码在 source root 下的相对路径包含逗号时,由于 `spring-javaformat.includes` 使用逗号分隔, hook 会安全中止并提示调整路径。 - Maven 或格式化插件执行失败时,hook 会中止 commit,并保持工作区和 Git index 不变。