beyondsoft-web-spring3-starter 功能概览

1. 模块定位

beyondsoft-web-spring3-starter 是基于 Spring Boot 3 的 Web 基础模块，封装了 统一响应、参数校验、跨域配置、拦截器和常用 Web 工具，用于快速构建符合框架规范的 RESTful API。

2. 主要能力

• 统一响应处理

  • 通过统一响应处理器（如 UnifiedResponseHandler）对 Controller 返回值进行标准化包装，形成统一的成功响应结构。
  • 支持泛型响应、分页响应、文件下载等常见响应场景。

• 请求参数校验与错误处理

  • 集成 JSR-303/Bean Validation，支持 @Valid / @Validated 等注解。
  • 统一处理参数校验失败异常（通常由异常 Starter 进一步转换为标准错误响应）。

• 跨域配置与基础拦截

  • 提供默认的 CORS 配置，支持多域名、Cookie 跨域等常见场景配置。
  • 内置请求/响应拦截器，可用于请求日志、性能监控、统一响应封装等。

• 静态资源与文件相关支持

  • 辅助配置静态资源访问前缀、上传路径等；
  • 提供文件下载相关的工具和约定（与日志模块的文件下载日志规范协同使用）。

• Web 工具类与基础注解

  • 提供常用 Web 工具（请求参数解析、响应构建、文件处理等）。
  • 提供注解如 @OriginalResponse，用于声明该接口不参与统一响应包装。

3. 使用约定

• 默认使用统一响应结构

  • Controller 方法推荐直接返回业务数据对象，由统一响应处理器封装为标准成功结构。
  • 特殊场景（如文件流、第三方回调等）确需返回原始数据时，在类或方法上使用 @OriginalResponse 明确声明。

• 参数校验统一靠框架处理

  • 参数校验尽量通过 JSR-303 注解完成，校验失败交由异常 Starter 统一处理，而不是在 Controller 中手工判断和拼装错误返回。

• 避免在业务项目重复实现基础 Web 能力

  • 禁止在业务项目中再实现一套“统一响应封装、全局拦截器、通用 CORS 配置”等与本 Starter 职责重叠的基础设施，所有此类能力应优先依赖本模块提供的实现或扩展点。

• 与异常、日志、安全模块协同使用

  • 与 beyondsoft-exception-spring3-starter 搭配，形成完整的“统一响应 + 统一异常”链路。
  • 与 beyondsoft-log-spring3-starter 搭配，实现请求日志、操作日志等统一记录。
  • 与 beyondsoft-sercutiry-spring3-starter 搭配，可在统一响应基础上叠加请求加解密和安全防护。