Web组件 (yudao-spring-boot-starter-web)

引用文件

本文引用的文件

简介

本文件面向 yudao-spring-boot-starter-web Web组件，系统性梳理其全局异常处理、Web配置、安全防护、日志与脱敏、文档与横幅、以及可扩展点。重点覆盖：

全局异常处理器的异常捕获机制、统一响应格式、错误码处理策略
Web配置（跨域、参数校验、拦截器、路径前缀）的实现与扩展
XSS防护、SQL注入防护、敏感信息脱敏等安全能力
Swagger/OpenAPI 文档集成、Banner启动横幅、Jackson序列化配置
自定义拦截器、过滤器、异常处理器的接入方式

项目结构

Web组件位于 yudao-framework 子模块下，核心由以下层次构成：

配置层：WebProperties、YudaoWebAutoConfiguration
异常处理层：GlobalExceptionHandler
工具层：WebFrameworkUtils
安全与防护：XSS(jsoup)、脱敏注解与处理器
文档与横幅：Knife4j/SpringDoc OpenAPI、Banner自动配置
API日志：ApiAccessLogFilter/Interceptor/Advice

Mermaid Diagram Code:

graph TB
subgraph "Web组件"
WP["WebProperties<br/>配置类"]
YWAC["YudaoWebAutoConfiguration<br/>自动装配"]
GEH["GlobalExceptionHandler<br/>全局异常处理器"]
WFU["WebFrameworkUtils<br/>Web工具"]
XSS["XSS防护<br/>jsoup"]
DES["脱敏<br/>DesensitizeBy/DesensitizationHandler"]
DOC["文档<br/>Knife4j/SpringDoc"]
BNR["横幅<br/>BannerApplicationRunner"]
LOG["API日志<br/>ApiAccessLogFilter/Interceptor/Advice"]
end
WP --> YWAC
YWAC --> GEH
GEH --> WFU
YWAC --> LOG
YWAC --> DOC
YWAC --> BNR
YWAC --> XSS
YWAC --> DES

图表来源

章节来源

pom.xml

核心组件

全局异常处理器：统一翻译各类异常为 CommonResult 响应，内置错误码映射与异常日志上报
Web配置：通过 WebProperties 定义 API 前缀与 UI 地址，YudaoWebAutoConfiguration 实现路径匹配与拦截器注册
安全与防护：XSS 清洗、脱敏注解与处理器、权限不足兜底
文档与横幅：Knife4j/SpringDoc OpenAPI 集成、Banner 启动横幅
API日志：多维度日志采集（过滤器/拦截器/AOP Advice）

章节来源

架构总览

Web组件在启动时通过自动装配注册异常处理器、API日志、文档与横幅等能力；对外提供统一的异常响应与安全防护。

Mermaid Diagram Code:

sequenceDiagram
participant C as "客户端"
participant F as "过滤器/拦截器"
participant M as "Spring MVC"
participant H as "GlobalExceptionHandler"
participant L as "异常日志服务"
C->>F : "HTTP请求"
F->>M : "进入控制器"
M-->>C : "正常响应"
M-->>H : "发生异常"
H->>L : "异步记录异常日志"
H-->>C : "统一错误响应(CommonResult)"

图表来源

组件详解

全局异常处理器（GlobalExceptionHandler）

职责：统一捕获并翻译异常为 CommonResult，同时记录异常日志，支持模块化表不存在场景的友好提示
异常覆盖：
- 参数缺失、类型不匹配、参数校验失败（含组合校验）、消息体解析异常
- 资源不存在（NoHandlerFound/NoResourceFound）、HTTP 方法不支持
- 业务异常 ServiceException（含错误码与消息）
- 权限不足 AccessDeniedException（结合登录上下文）
- 默认兜底异常（记录日志并返回通用错误码）
错误码策略：优先使用 ServiceException 中的业务错误码；其余场景映射至全局错误码（如 BAD_REQUEST、NOT_FOUND、METHOD_NOT_ALLOWED、FORBIDDEN、INTERNAL_SERVER_ERROR）
异常日志：收集请求上下文、用户信息、堆栈信息、TraceId 等，异步落库

Mermaid Diagram Code:

flowchart TD
Start(["进入异常处理"]) --> Type{"异常类型"}
Type --> |参数缺失/类型不匹配/校验失败| ParamErr["返回统一错误码+提示"]
Type --> |资源不存在/方法不支持| HttpErr["返回对应错误码"]
Type --> |业务异常| BizErr["返回业务错误码+消息"]
Type --> |权限不足| Deny["返回禁止访问错误码"]
Type --> |其他异常| Default["记录异常日志并返回服务器错误码"]
ParamErr --> End(["结束"])
HttpErr --> End
BizErr --> End
Deny --> End
Default --> End

图表来源

GlobalExceptionHandler.java

章节来源

GlobalExceptionHandler.java

Web配置（WebProperties 与 YudaoWebAutoConfiguration）

WebProperties
- 定义 API 前缀与 Controller 包匹配规则，用于对不同模块（如 APP/Admin）设置独立前缀与扫描范围
- 定义 Admin UI 访问地址
YudaoWebAutoConfiguration
- 注册拦截器、过滤器、跨域配置等
- 通过 PathMatchConfigurer 将 API 前缀与 Controller 包规则绑定，确保路径匹配一致性
- 集成 API 日志、文档、横幅、XSS、脱敏等能力

Mermaid Diagram Code:

classDiagram
class WebProperties {
+Api appApi
+Api adminApi
+Ui adminUi
}
class Api {
+String prefix
+String controller
}
class Ui {
+String url
}
class YudaoWebAutoConfiguration {
+configurePathMatch()
+registerInterceptors()
+registerFilters()
}
WebProperties --> Api
WebProperties --> Ui
YudaoWebAutoConfiguration --> WebProperties

图表来源

章节来源

安全与防护

XSS 防护：引入 jsoup 依赖，用于清洗富文本或输入内容中的潜在危险标签
SQL 注入防护：通过参数校验、类型转换、白名单式路径匹配与权限控制降低风险
敏感信息脱敏：提供 @DesensitizeBy 注解与 DesensitizationHandler 处理器，统一脱敏策略

Mermaid Diagram Code:

graph LR
IN["输入/请求参数"] --> XSS["XSS清洗"]
IN --> VALID["参数校验/类型转换"]
IN --> AUTH["权限校验"]
DATA["敏感数据"] --> DES["脱敏处理器"]
XSS --> OUT["安全输出"]
VALID --> OUT
AUTH --> OUT
DES --> OUT

图表来源

章节来源

Swagger/OpenAPI 文档集成

依赖 Knife4j 与 SpringDoc OpenAPI，提供更友好的接口文档体验
与 WebProperties 的 API 前缀配合，避免文档泄露至 Nginx 外部

章节来源

pom.xml

通过 BannerApplicationRunner 在应用启动后输出横幅信息，提升可观测性与品牌展示

章节来源

API 日志

三种采集方式：
- ApiAccessLogFilter：基于 Servlet 过滤器的请求级日志
- ApiAccessLogInterceptor：基于 Spring MVC Interceptor 的控制器级日志
- ApiAdvice：基于 @RestControllerAdvice 的统一切面日志
三者协同，覆盖请求生命周期各阶段

章节来源

依赖关系分析

Web容器：默认 Undertow（高性能），保留对 Tomcat 的排除与替换能力
安全：Spring Security 作为 provided 依赖，仅在全局异常处理中使用
文档：Knife4j 与 SpringDoc OpenAPI 并存，满足不同团队偏好
日志：依赖 yudao-module-infra-api 进行异常日志异步写入
脱敏与 XSS：独立依赖，便于按需启用

Mermaid Diagram Code:

graph TB
POM["pom.xml 依赖声明"]
WEB["spring-boot-starter-web"]
UND["spring-boot-starter-undertow"]
SEC["spring-security-core(provided)"]
DOC1["knife4j-openapi3-jakarta"]
DOC2["springdoc-openapi-starter-webmvc-api"]
INF["yudao-module-infra-api"]
SYS["yudao-module-system-api"]
XSS["jsoup"]
TEST["spring-boot-starter-test"]
POM --> WEB
POM --> UND
POM --> SEC
POM --> DOC1
POM --> DOC2
POM --> INF
POM --> SYS
POM --> XSS
POM --> TEST

图表来源

pom.xml

章节来源

pom.xml

性能与安全特性

性能
- Undertow 容器替代 Tomcat，提升并发与低延迟表现
- 异步记录异常日志，避免阻塞请求链路
安全
- 统一异常响应，隐藏内部异常细节
- 参数校验与类型转换，降低非法输入风险
- XSS 清洗与脱敏策略，保护敏感信息
- 权限不足统一返回 403，避免越权信息泄露

[本节为通用建议，无需具体文件分析]

故障排查指南

异常日志定位
- 关注 GlobalExceptionHandler 中的异常日志构建与异步写入逻辑，核对 TraceId、请求参数、用户信息
常见问题
- 资源不存在：确认 NoHandlerFound/NoResourceFound 的 URL 是否符合预期
- 权限不足：检查 AccessDeniedException 的触发点与登录上下文
- 参数校验失败：查看 MethodArgumentNotValidException/BindException/ConstraintViolationException 的字段与消息
排查步骤
- 打开调试日志，观察 defaultExceptionHandler 的日志输出
- 核对 WebProperties 的 API 前缀与 Controller 包匹配是否正确
- 检查 API 日志是否正常入库

章节来源

结论

yudao-spring-boot-starter-web 以“统一异常 + 安全防护 + 文档与横幅 + API日志”为核心，提供高可用、易扩展的 Web 基础设施。通过 WebProperties 与 YudaoWebAutoConfiguration，开发者可以快速定制 API 前缀、拦截器与过滤器；通过全局异常处理器与 API 日志，保障线上问题可追踪、可诊断。

[本节为总结，无需具体文件分析]

附录：扩展与自定义示例

如何添加自定义拦截器

在 YudaoWebAutoConfiguration 中注册拦截器，或在业务模块中实现 WebMvcConfigurer 并重写 addInterceptors 方法
示例路径参考：
- YudaoWebAutoConfiguration.java

如何添加自定义过滤器

在 YudaoWebAutoConfiguration 中注册过滤器，或通过 @WebFilter + @Order 定义
示例路径参考：
- YudaoWebAutoConfiguration.java

如何添加自定义异常处理器

方案一：在业务模块新增 @RestControllerAdvice，优先级高于全局异常处理器
方案二：扩展 GlobalExceptionHandler（不推荐），或通过继承/组合方式复用其日志与错误码策略
示例路径参考：
- GlobalExceptionHandler.java

如何启用/配置脱敏

在实体字段上使用 @DesensitizeBy 注解，结合 DesensitizationHandler 生效
示例路径参考：
- DesensitizeBy.java
- DesensitizationHandler.java

如何启用/配置 API 日志

通过 YudaoApiLogAutoConfiguration 自动装配，或在业务模块中自定义 ApiAccessLogFilter/Interceptor/Advice
示例路径参考：

目录​

简介​

项目结构​

核心组件​

架构总览​

组件详解​

全局异常处理器（GlobalExceptionHandler）​

Web配置（WebProperties 与 YudaoWebAutoConfiguration）​

安全与防护​

Swagger/OpenAPI 文档集成​

Banner 启动横幅​

API 日志​

依赖关系分析​

性能与安全特性​

故障排查指南​

结论​

附录：扩展与自定义示例​

如何添加自定义拦截器​

如何添加自定义过滤器​

如何添加自定义异常处理器​

如何启用/配置脱敏​

如何启用/配置 API 日志​

目录

简介

项目结构

核心组件

架构总览

组件详解

全局异常处理器（GlobalExceptionHandler）

Web配置（WebProperties 与 YudaoWebAutoConfiguration）

安全与防护

Swagger/OpenAPI 文档集成

Banner 启动横幅

API 日志

依赖关系分析

性能与安全特性

故障排查指南

结论

附录：扩展与自定义示例

如何添加自定义拦截器

如何添加自定义过滤器

如何添加自定义异常处理器

如何启用/配置脱敏

如何启用/配置 API 日志