初始化
This commit is contained in:
606
rdms-framework/rdms-spring-boot-starter-web/README.md
Normal file
606
rdms-framework/rdms-spring-boot-starter-web/README.md
Normal file
@@ -0,0 +1,606 @@
|
||||
# rdms-spring-boot-starter-web
|
||||
|
||||
## 1. 模块定位
|
||||
|
||||
`rdms-spring-boot-starter-web` 是 Web 层基础设施模块，用来统一处理 HTTP 接口开发中的通用问题，而不是承载具体业务逻辑。
|
||||
|
||||
模块当前聚合了以下能力：
|
||||
|
||||
- Web 基础自动配置
|
||||
- 全局异常处理
|
||||
- 接口返回结果暂存
|
||||
- 管理端 / 应用端接口前缀约定
|
||||
- Swagger / Knife4j 文档
|
||||
- API 访问日志
|
||||
- XSS 防护
|
||||
- API 加解密
|
||||
- 返回字段脱敏
|
||||
- Jackson JSON 定制
|
||||
- Banner 输出
|
||||
|
||||
## 2. 设计思路
|
||||
|
||||
这个模块的设计重点，是把 Web 层横切能力收敛到 starter 中，业务模块只关注 Controller、参数对象和业务逻辑本身。
|
||||
|
||||
核心思路如下：
|
||||
|
||||
- 通过自动装配统一注册 `Filter`、`ControllerAdvice`、`RestTemplate`、Swagger 等基础组件。
|
||||
- 通过包路径约定，自动给 Controller 增加统一前缀，减少每个模块重复写公共路径。
|
||||
- 通过全局异常处理，把常见异常统一翻译成 `CommonResult`。
|
||||
- 通过过滤器和拦截器处理访问日志、XSS、防重复读取请求体、演示环境保护等横切逻辑。
|
||||
- 通过注解方式扩展局部能力，例如 API 访问日志增强、接口加解密、字段脱敏。
|
||||
|
||||
自动装配入口如下：
|
||||
|
||||
- `com.njcn.rdms.framework.apilog.config.RdmsApiLogAutoConfiguration`
|
||||
- `com.njcn.rdms.framework.jackson.config.RdmsJacksonAutoConfiguration`
|
||||
- `com.njcn.rdms.framework.swagger.config.RdmsSwaggerAutoConfiguration`
|
||||
- `com.njcn.rdms.framework.web.config.RdmsWebAutoConfiguration`
|
||||
- `com.njcn.rdms.framework.apilog.config.RdmsApiLogRpcAutoConfiguration`
|
||||
- `com.njcn.rdms.framework.xss.config.RdmsXssAutoConfiguration`
|
||||
- `com.njcn.rdms.framework.banner.config.RdmsBannerAutoConfiguration`
|
||||
- `com.njcn.rdms.framework.encrypt.config.RdmsApiEncryptAutoConfiguration`
|
||||
|
||||
## 3. 功能模块
|
||||
|
||||
### 3.1 Web 基础自动配置
|
||||
|
||||
`RdmsWebAutoConfiguration` 是本模块的核心入口，主要提供以下能力：
|
||||
|
||||
- 注册全局异常处理器 `GlobalExceptionHandler`
|
||||
- 注册返回结果处理器 `GlobalResponseBodyHandler`
|
||||
- 注册 `WebFrameworkUtils`
|
||||
- 注册跨域过滤器 `CorsFilter`
|
||||
- 注册请求体缓存过滤器 `CacheRequestBodyFilter`
|
||||
- 提供普通 `RestTemplate`
|
||||
- 提供带 `@LoadBalanced` 的 `RestTemplate`
|
||||
|
||||
其中有两个基础能力需要重点关注：
|
||||
|
||||
#### 3.1.1 按包路径自动增加接口前缀
|
||||
|
||||
模块会根据 Controller 所在包路径，自动追加统一前缀：
|
||||
|
||||
- `**.controller.admin.**` 默认追加 `/admin-api`
|
||||
- `**.controller.app.**` 默认追加 `/app-api`
|
||||
|
||||
默认配置来自 `rdms.web`：
|
||||
|
||||
```yaml
|
||||
rdms:
|
||||
web:
|
||||
admin-api:
|
||||
prefix: /admin-api
|
||||
controller: "**.controller.admin.**"
|
||||
app-api:
|
||||
prefix: /app-api
|
||||
controller: "**.controller.app.**"
|
||||
admin-ui:
|
||||
url: http://127.0.0.1:80
|
||||
|
||||
# 说明：
|
||||
# - admin-api/app-api 已有默认值（如上所示），不改可省略
|
||||
# - admin-ui.url 无默认值，需要显式配置
|
||||
```
|
||||
|
||||
例如：
|
||||
|
||||
```java
|
||||
package com.njcn.rdms.module.system.controller.admin.user;
|
||||
|
||||
@RestController
|
||||
@RequestMapping("/user")
|
||||
public class UserController {
|
||||
|
||||
@GetMapping("/get")
|
||||
public CommonResult<String> get() {
|
||||
return CommonResult.success("ok");
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
实际访问路径是：
|
||||
|
||||
```text
|
||||
/admin-api/user/get
|
||||
```
|
||||
|
||||
如果 Controller 放在：
|
||||
|
||||
```text
|
||||
com.xxx.xxx.controller.app.xxx
|
||||
```
|
||||
|
||||
则会自动挂到 `/app-api` 下。
|
||||
|
||||
#### 3.1.2 `CommonResult` 不是自动包装
|
||||
|
||||
这个模块不会把任意 Controller 返回值自动包成 `CommonResult`。
|
||||
|
||||
`GlobalResponseBodyHandler` 的作用，是在返回前记录已经构造好的 `CommonResult`，供访问日志等能力读取，而不是替开发者自动改写返回结构。
|
||||
|
||||
因此 Controller 仍然需要显式返回：
|
||||
|
||||
```java
|
||||
return CommonResult.success(data);
|
||||
```
|
||||
|
||||
而不是依赖框架自动包装。
|
||||
|
||||
### 3.2 全局异常处理
|
||||
|
||||
`GlobalExceptionHandler` 会把常见异常统一转换成 `CommonResult`，包括：
|
||||
|
||||
- 参数缺失
|
||||
- 参数类型错误
|
||||
- `@Validated` / `@Valid` 校验失败
|
||||
- 请求方式不匹配
|
||||
- Content-Type 不匹配
|
||||
- 无权限访问
|
||||
- 业务异常 `ServiceException`
|
||||
- 系统异常
|
||||
|
||||
对于系统异常，除了统一返回错误结果外，还会通过 `ApiErrorLogCommonApi` 异步记录异常日志。
|
||||
|
||||
这意味着业务代码中通常只需要：
|
||||
|
||||
- 正常场景返回 `CommonResult.success(...)`
|
||||
- 业务错误抛出 `ServiceException`
|
||||
|
||||
其余异常由框架统一兜底。
|
||||
|
||||
### 3.3 接口返回结果暂存
|
||||
|
||||
这里的“接口返回结果记录”，更准确地说是“接口返回结果暂存”。
|
||||
|
||||
对应实现是 `GlobalResponseBodyHandler`，它只会在 Controller 返回值为 `CommonResult` 时，把该结果放到当前请求上下文中，供后续组件读取。
|
||||
|
||||
它本身不负责：
|
||||
|
||||
- 打印日志
|
||||
- 持久化日志
|
||||
- 改写返回结构
|
||||
|
||||
它主要服务于访问日志能力。因为 `ApiAccessLogFilter` 执行时，需要拿到本次请求最终返回的 `CommonResult`，才能把返回码、返回消息、响应体等内容写入访问日志。
|
||||
|
||||
可以这样理解两者关系：
|
||||
|
||||
- 接口返回结果暂存：把本次返回结果放到 request 上，供后续读取
|
||||
- API 访问日志：读取请求信息和返回结果，组装后异步上报日志
|
||||
|
||||
因此，这两个能力不是并列重复关系，而是前者为后者提供支撑。
|
||||
|
||||
### 3.4 请求体缓存
|
||||
|
||||
`CacheRequestBodyFilter` 会把请求体包装成可重复读取的形式。
|
||||
|
||||
这个能力主要解决以下问题：
|
||||
|
||||
- 过滤器里读过一次请求体后，后续代码还能继续读取
|
||||
- 访问日志、XSS、防护类过滤器可以提前读取请求内容
|
||||
- 异常日志记录时可以再次拿到请求参数
|
||||
|
||||
这类能力对 `application/json` 请求尤其重要。
|
||||
|
||||
### 3.5 跨域处理
|
||||
|
||||
模块默认注册了全局 `CorsFilter`，允许：
|
||||
|
||||
- 任意来源
|
||||
- 任意请求头
|
||||
- 任意请求方法
|
||||
- 携带凭证
|
||||
|
||||
适合前后端分离场景的统一跨域处理。
|
||||
|
||||
如果项目已经有更严格的网关级跨域策略，需要注意是否与这里的配置重复。
|
||||
|
||||
### 3.6 RestTemplate 支持
|
||||
|
||||
模块提供两个 `RestTemplate` Bean：
|
||||
|
||||
- 普通 `RestTemplate`
|
||||
- 支持服务名负载均衡的 `loadBalancedRestTemplate`
|
||||
|
||||
使用示例：
|
||||
|
||||
```java
|
||||
@Resource
|
||||
private RestTemplate restTemplate;
|
||||
|
||||
@Resource(name = "loadBalancedRestTemplate")
|
||||
private RestTemplate loadBalancedRestTemplate;
|
||||
```
|
||||
|
||||
适用场景：
|
||||
|
||||
- `restTemplate`：直接调用固定地址
|
||||
- `loadBalancedRestTemplate`：通过服务名访问注册中心中的其他服务
|
||||
|
||||
### 3.7 Swagger / Knife4j 文档
|
||||
|
||||
模块会自动装配 OpenAPI，并按管理端、应用端拆分分组：
|
||||
|
||||
- `/admin-api/**`
|
||||
- `/app-api/**`
|
||||
|
||||
同时会在文档中预置常见请求头，例如认证头、租户头，便于在 Swagger 页面直接调试接口。
|
||||
|
||||
Swagger 配置示例：
|
||||
|
||||
```yaml
|
||||
rdms:
|
||||
swagger:
|
||||
title: RDMS API # 文档标题
|
||||
description: RDMS 接口文档 # 文档描述
|
||||
author: RDMS # 作者/团队
|
||||
version: 1.0.0 # 版本号
|
||||
url: https://example.com # 项目或团队主页
|
||||
email: dev@example.com # 联系邮箱
|
||||
license: Apache 2.0 # 协议名称
|
||||
license-url: https://www.apache.org/licenses/LICENSE-2.0.html # 协议地址
|
||||
```
|
||||
|
||||
开发时通常只需要：
|
||||
|
||||
- 引入本模块
|
||||
- 补齐 `rdms.swagger` 配置
|
||||
- 在 Controller 上使用 `@Tag`
|
||||
- 在接口上使用 `@Operation`
|
||||
|
||||
这样访问日志模块还能直接复用这些注解信息，自动推断操作模块、操作名称。
|
||||
|
||||
### 3.8 API 访问日志
|
||||
|
||||
模块通过 `ApiAccessLogFilter + ApiAccessLogInterceptor` 组合处理接口访问日志。
|
||||
|
||||
这里的访问日志，才是真正意义上的“日志记录能力”。
|
||||
|
||||
处理逻辑分成两层：
|
||||
|
||||
- 拦截器层：把 `HandlerMethod` 放到 request 中，供过滤器层读取
|
||||
- 过滤器层：在请求结束后读取请求信息、异常信息、返回结果，并异步上报访问日志
|
||||
|
||||
访问日志内容包括：
|
||||
|
||||
- 用户信息
|
||||
- 请求路径、方法、IP、User-Agent
|
||||
- 请求参数
|
||||
- 返回码、返回信息
|
||||
- 执行耗时
|
||||
- 操作模块、操作名称、操作类型
|
||||
|
||||
其中“返回码、返回信息、响应体”这部分数据，正是从前面的 `GlobalResponseBodyHandler` 暂存结果中读取出来的。
|
||||
|
||||
默认会记录访问日志；如需关闭，可配置：
|
||||
|
||||
```yaml
|
||||
rdms:
|
||||
access-log:
|
||||
enable: false
|
||||
```
|
||||
|
||||
如果需要对某个接口单独调整日志行为，可使用 `@ApiAccessLog`。
|
||||
|
||||
常见用法示例：
|
||||
|
||||
```java
|
||||
@Tag(name = "用户管理")
|
||||
@RestController
|
||||
@RequestMapping("/user")
|
||||
public class UserController {
|
||||
|
||||
@GetMapping("/page")
|
||||
@Operation(summary = "查询用户分页")
|
||||
@ApiAccessLog(responseEnable = true, sanitizeKeys = {"mobile"})
|
||||
public CommonResult<PageResult<UserRespVO>> page(UserPageReqVO reqVO) {
|
||||
return CommonResult.success(userService.page(reqVO));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `responseEnable = true`：额外记录响应体
|
||||
- `sanitizeKeys`：从日志中移除敏感字段
|
||||
- 如果没有显式指定操作名称，默认优先从 `@Operation` 中获取
|
||||
|
||||
访问日志的异步落库依赖 `ApiAccessLogCommonApi`，因此它本质上是“记录请求轨迹”，不是直接把日志写在本模块内部。
|
||||
|
||||
### 3.9 XSS 防护
|
||||
|
||||
模块内提供了 XSS 过滤能力，核心组成包括：
|
||||
|
||||
- `XssFilter`
|
||||
- `XssRequestWrapper`
|
||||
- `XssStringJsonDeserializer`
|
||||
- `JsoupXssCleaner`
|
||||
|
||||
设计方式是：
|
||||
|
||||
- 对进入系统的请求内容做统一清洗
|
||||
- 对 JSON 中的字符串字段做清洗
|
||||
- 底层使用 `jsoup` 处理潜在的恶意脚本片段
|
||||
|
||||
适用场景：
|
||||
|
||||
- 富文本之外的大多数普通文本输入
|
||||
- 表单提交
|
||||
- JSON 请求体中的字符串字段
|
||||
|
||||
如果某些接口需要保留原始 HTML 内容，通常需要结合该模块的 XSS 配置做排除，而不是在业务层手工规避。
|
||||
|
||||
URL 白名单说明：
|
||||
|
||||
- 支持通过 `rdms.xss.exclude-urls` 配置 URL 白名单，命中的 URL 会跳过 XSS 过滤（包括 Filter 与 JSON 字符串反序列化）。
|
||||
- 适合富文本、HTML 片段等需要保留原始内容的接口。
|
||||
|
||||
示例：
|
||||
|
||||
```yaml
|
||||
rdms:
|
||||
xss:
|
||||
enable: true
|
||||
exclude-urls:
|
||||
- /admin-api/rich-text/**
|
||||
- /app-api/article/save
|
||||
```
|
||||
|
||||
### 3.10 API 加解密
|
||||
|
||||
模块提供了接口级加解密能力，核心组成包括：
|
||||
|
||||
- `@ApiEncrypt`
|
||||
- `ApiEncryptFilter`
|
||||
- `ApiDecryptRequestWrapper`
|
||||
- `ApiEncryptResponseWrapper`
|
||||
|
||||
适合理解为：
|
||||
|
||||
- 请求进入时先解密
|
||||
- Controller / Service 内部仍然处理明文
|
||||
- 响应返回前再加密
|
||||
|
||||
开发使用上，一般是在需要加解密的接口上增加 `@ApiEncrypt`，其余请求不受影响。
|
||||
|
||||
示例：
|
||||
|
||||
```java
|
||||
@RestController
|
||||
@RequestMapping("/secure/demo")
|
||||
public class SecureDemoController {
|
||||
|
||||
@PostMapping("/submit")
|
||||
@ApiEncrypt
|
||||
public CommonResult<String> submit(@RequestBody DemoReqVO reqVO) {
|
||||
return CommonResult.success(reqVO.getContent());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
这类能力适合：
|
||||
|
||||
- 对外开放接口
|
||||
- 对传输内容有额外保护要求的场景
|
||||
|
||||
不适合把它当成通用权限控制手段。它解决的是“传输内容保护”，不是“访问授权”。
|
||||
|
||||
### 3.11 返回字段脱敏
|
||||
|
||||
模块内置了一组字段脱敏注解和序列化器，常见注解包括：
|
||||
|
||||
- `@MobileDesensitize`
|
||||
- `@EmailDesensitize`
|
||||
- `@IdCardDesensitize`
|
||||
- `@BankCardDesensitize`
|
||||
- `@ChineseNameDesensitize`
|
||||
- `@PasswordDesensitize`
|
||||
|
||||
适用方式是：在返回对象字段上直接加注解，序列化为 JSON 时自动脱敏。
|
||||
|
||||
示例：
|
||||
|
||||
```java
|
||||
@Data
|
||||
public class UserRespVO {
|
||||
|
||||
private Long id;
|
||||
|
||||
@MobileDesensitize
|
||||
private String mobile;
|
||||
|
||||
@EmailDesensitize
|
||||
private String email;
|
||||
|
||||
@ChineseNameDesensitize
|
||||
private String nickname;
|
||||
}
|
||||
```
|
||||
|
||||
这样接口内部仍可使用原始值，真正对外输出时才变成脱敏后的内容。
|
||||
|
||||
### 3.12 Jackson JSON 定制
|
||||
|
||||
模块包含 `RdmsJacksonAutoConfiguration`，用于统一注册 JSON 序列化 / 反序列化相关定制能力。
|
||||
|
||||
从模块结构上看，它主要承担两类职责：
|
||||
|
||||
- 承接本模块的 XSS、脱敏等 JSON 处理能力
|
||||
- 把 JSON 相关行为统一收口到 starter 中，避免各业务模块重复配置 `ObjectMapper`
|
||||
|
||||
因此业务模块通常不需要自己再手动声明一套新的全局 Jackson 配置，除非有明确的覆盖需求。
|
||||
|
||||
### 3.13 Banner
|
||||
|
||||
模块还包含 `RdmsBannerAutoConfiguration` 和 `BannerApplicationRunner`，用于在应用启动时输出框架 Banner 信息。
|
||||
|
||||
这部分属于展示型能力，不影响具体业务逻辑。
|
||||
|
||||
## 4. 开发人员上手
|
||||
|
||||
### 4.1 引入依赖
|
||||
|
||||
```xml
|
||||
<dependency>
|
||||
<groupId>com.njcn</groupId>
|
||||
<artifactId>rdms-spring-boot-starter-web</artifactId>
|
||||
</dependency>
|
||||
```
|
||||
|
||||
本模块已经聚合：
|
||||
|
||||
- `spring-boot-starter-web`
|
||||
- `spring-boot-starter-validation`
|
||||
- `knife4j-openapi3-jakarta-spring-boot-starter`
|
||||
- `springdoc-openapi-starter-webmvc-ui`
|
||||
|
||||
如果项目已经单独引入了这些依赖，需要留意是否存在重复配置。
|
||||
|
||||
### 4.2 准备基础配置
|
||||
|
||||
建议至少配置以下内容：
|
||||
|
||||
```yaml
|
||||
spring:
|
||||
application:
|
||||
name: rdms-system-server
|
||||
|
||||
rdms:
|
||||
web:
|
||||
admin-api:
|
||||
prefix: /admin-api
|
||||
controller: "**.controller.admin.**"
|
||||
app-api:
|
||||
prefix: /app-api
|
||||
controller: "**.controller.app.**"
|
||||
admin-ui:
|
||||
url: http://127.0.0.1:80
|
||||
|
||||
swagger:
|
||||
title: RDMS API # 文档标题
|
||||
description: RDMS 接口文档 # 文档描述
|
||||
author: RDMS # 作者/团队
|
||||
version: 1.0.0 # 版本号
|
||||
url: https://example.com # 项目或团队主页
|
||||
email: dev@example.com # 联系邮箱
|
||||
license: Apache 2.0 # 协议名称
|
||||
license-url: https://www.apache.org/licenses/LICENSE-2.0.html # 协议地址
|
||||
|
||||
access-log:
|
||||
enable: true
|
||||
```
|
||||
|
||||
### 4.3 按约定放置 Controller
|
||||
|
||||
如果希望自动带上前缀，需要把 Controller 放到约定包下：
|
||||
|
||||
- 管理端：`xx.controller.admin.xx`
|
||||
- 应用端：`xx.controller.app.xx`
|
||||
|
||||
不符合这个包路径规则的 Controller，不会自动追加 `/admin-api` 或 `/app-api`。
|
||||
|
||||
### 4.4 统一返回 `CommonResult`
|
||||
|
||||
Controller 写法建议保持统一：
|
||||
|
||||
```java
|
||||
@Tag(name = "部门管理")
|
||||
@RestController
|
||||
@RequestMapping("/dept")
|
||||
public class DeptController {
|
||||
|
||||
@GetMapping("/get")
|
||||
@Operation(summary = "获得部门详情")
|
||||
public CommonResult<DeptRespVO> get(@RequestParam("id") Long id) {
|
||||
return CommonResult.success(deptService.get(id));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
建议遵循：
|
||||
|
||||
- 成功场景返回 `CommonResult.success(...)`
|
||||
- 业务异常抛出 `ServiceException`
|
||||
- 参数对象使用 `@Validated` / `@Valid`
|
||||
|
||||
### 4.5 使用访问日志
|
||||
|
||||
多数情况下，不需要额外写代码，访问日志会自动生效。
|
||||
|
||||
如果需要补充操作名、操作类型、响应体记录等信息，可以加：
|
||||
|
||||
```java
|
||||
@ApiAccessLog(responseEnable = true)
|
||||
```
|
||||
|
||||
建议同时补齐：
|
||||
|
||||
- `@Tag`
|
||||
- `@Operation`
|
||||
|
||||
这样日志中的操作模块和操作名称会更完整；建议将 `@Tag` / `@Operation` 作为接口开发的必填规范。
|
||||
|
||||
### 4.6 使用加解密
|
||||
|
||||
只在需要的接口上加：
|
||||
|
||||
```java
|
||||
@ApiEncrypt
|
||||
```
|
||||
|
||||
然后让调用方按约定传输密文即可。接口内部仍按明文对象开发，不需要在 Controller 内手工做解密逻辑。
|
||||
|
||||
### 4.7 使用字段脱敏
|
||||
|
||||
在返回对象字段上直接加注解即可：
|
||||
|
||||
```java
|
||||
@MobileDesensitize
|
||||
private String mobile;
|
||||
```
|
||||
|
||||
适合用户信息、联系方式、证件信息等对外展示场景。
|
||||
|
||||
### 4.8 使用 RestTemplate
|
||||
|
||||
固定地址调用：
|
||||
|
||||
```java
|
||||
@Resource
|
||||
private RestTemplate restTemplate;
|
||||
```
|
||||
|
||||
服务名调用：
|
||||
|
||||
```java
|
||||
@Resource(name = "loadBalancedRestTemplate")
|
||||
private RestTemplate loadBalancedRestTemplate;
|
||||
```
|
||||
|
||||
### 4.9 开发时需要注意的几个点
|
||||
|
||||
- 这个模块不会自动把任意返回值包装成 `CommonResult`，需要显式返回。
|
||||
- 接口前缀是按包路径匹配出来的，不是看 Controller 名称。
|
||||
- 访问日志默认开启，但是否真正异步落库，还取决于日志相关 RPC 接口是否可用。
|
||||
- XSS、防脱敏、加解密都属于横切能力，原则上应该通过统一配置或注解使用，不建议在业务代码里重复造轮子。
|
||||
- 如果项目已经在网关层处理跨域、日志、安全头等逻辑，需要评估是否与本模块职责重叠。
|
||||
|
||||
## 5. 适合承载什么，不适合承载什么
|
||||
|
||||
适合放在这个模块里的能力：
|
||||
|
||||
- Web 层公共配置
|
||||
- HTTP 请求/响应横切处理
|
||||
- 接口文档
|
||||
- 访问日志
|
||||
- 安全性输入输出处理
|
||||
- Web 基础工具注册
|
||||
|
||||
不适合放在这个模块里的能力：
|
||||
|
||||
- 具体业务规则
|
||||
- 菜单、权限、数据权限等业务权限判断
|
||||
- 某个业务模块专属的 Controller 逻辑
|
||||
- 与单一业务强耦合的转换规则
|
||||
|
||||
从职责上看，这个模块更接近“Web 基础设施层”，而不是“业务功能层”。
|
||||
92
rdms-framework/rdms-spring-boot-starter-web/pom.xml
Normal file
92
rdms-framework/rdms-spring-boot-starter-web/pom.xml
Normal file
@@ -0,0 +1,92 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
<parent>
|
||||
<groupId>com.njcn</groupId>
|
||||
<artifactId>rdms-framework</artifactId>
|
||||
<version>${revision}</version>
|
||||
</parent>
|
||||
|
||||
<artifactId>rdms-spring-boot-starter-web</artifactId>
|
||||
<packaging>jar</packaging>
|
||||
|
||||
<name>${project.artifactId}</name>
|
||||
<description>Web 框架，全局异常、API 日志、脱敏、错误码等</description>
|
||||
<properties>
|
||||
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
|
||||
</properties>
|
||||
|
||||
<dependencies>
|
||||
<dependency>
|
||||
<groupId>com.njcn</groupId>
|
||||
<artifactId>rdms-common</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Spring Boot 配置所需依赖 -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-configuration-processor</artifactId>
|
||||
<optional>true</optional>
|
||||
</dependency>
|
||||
|
||||
<!-- Web 相关 -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-web</artifactId>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-validation</artifactId>
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.springframework.security</groupId>
|
||||
<artifactId>spring-security-core</artifactId>
|
||||
<scope>provided</scope> <!-- 设置为 provided，主要是 GlobalExceptionHandler 使用 -->
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>com.github.xiaoymin</groupId>
|
||||
<artifactId>knife4j-openapi3-jakarta-spring-boot-starter</artifactId>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.springdoc</groupId>
|
||||
<artifactId>springdoc-openapi-starter-webmvc-ui</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- RPC 远程调用相关 -->
|
||||
<dependency>
|
||||
<groupId>com.njcn</groupId>
|
||||
<artifactId>rdms-spring-boot-starter-rpc</artifactId>
|
||||
<optional>true</optional>
|
||||
</dependency>
|
||||
|
||||
<!-- 工具类相关 -->
|
||||
<dependency>
|
||||
<groupId>com.google.guava</groupId>
|
||||
<artifactId>guava</artifactId>
|
||||
<scope>provided</scope> <!-- 设置为 provided，只有工具类需要使用到 -->
|
||||
</dependency>
|
||||
|
||||
<dependency>
|
||||
<groupId>org.jsoup</groupId>
|
||||
<artifactId>jsoup</artifactId>
|
||||
</dependency>
|
||||
|
||||
<!-- Test 测试相关 -->
|
||||
<dependency>
|
||||
<groupId>org.springframework.boot</groupId>
|
||||
<artifactId>spring-boot-starter-test</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
<dependency>
|
||||
<groupId>org.mockito</groupId>
|
||||
<artifactId>mockito-inline</artifactId>
|
||||
<scope>test</scope>
|
||||
</dependency>
|
||||
</dependencies>
|
||||
|
||||
</project>
|
||||
@@ -0,0 +1,44 @@
|
||||
package com.njcn.rdms.framework.apilog.config;
|
||||
|
||||
import com.njcn.rdms.framework.apilog.core.filter.ApiAccessLogFilter;
|
||||
import com.njcn.rdms.framework.apilog.core.interceptor.ApiAccessLogInterceptor;
|
||||
import com.njcn.rdms.framework.common.biz.infra.logger.ApiAccessLogCommonApi;
|
||||
import com.njcn.rdms.framework.common.enums.WebFilterOrderEnum;
|
||||
import com.njcn.rdms.framework.web.config.RdmsWebAutoConfiguration;
|
||||
import com.njcn.rdms.framework.web.config.WebProperties;
|
||||
import jakarta.servlet.Filter;
|
||||
import org.springframework.beans.factory.annotation.Value;
|
||||
import org.springframework.boot.autoconfigure.AutoConfiguration;
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
|
||||
import org.springframework.boot.web.servlet.FilterRegistrationBean;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
|
||||
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
|
||||
|
||||
@AutoConfiguration(after = RdmsWebAutoConfiguration.class)
|
||||
public class RdmsApiLogAutoConfiguration implements WebMvcConfigurer {
|
||||
|
||||
/**
|
||||
* 创建 ApiAccessLogFilter Bean，记录 API 请求日志
|
||||
*/
|
||||
@Bean
|
||||
@ConditionalOnProperty(prefix = "rdms.access-log", value = "enable", matchIfMissing = true) // 允许使用 rdms.access-log.enable=false 禁用访问日志
|
||||
public FilterRegistrationBean<ApiAccessLogFilter> apiAccessLogFilter(WebProperties webProperties,
|
||||
@Value("${spring.application.name}") String applicationName,
|
||||
ApiAccessLogCommonApi apiAccessLogApi) {
|
||||
ApiAccessLogFilter filter = new ApiAccessLogFilter(webProperties, applicationName, apiAccessLogApi);
|
||||
return createFilterBean(filter, WebFilterOrderEnum.API_ACCESS_LOG_FILTER);
|
||||
}
|
||||
|
||||
private static <T extends Filter> FilterRegistrationBean<T> createFilterBean(T filter, Integer order) {
|
||||
FilterRegistrationBean<T> bean = new FilterRegistrationBean<>(filter);
|
||||
bean.setOrder(order);
|
||||
return bean;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void addInterceptors(InterceptorRegistry registry) {
|
||||
registry.addInterceptor(new ApiAccessLogInterceptor());
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,16 @@
|
||||
package com.njcn.rdms.framework.apilog.config;
|
||||
|
||||
import com.njcn.rdms.framework.common.biz.infra.logger.ApiAccessLogCommonApi;
|
||||
import com.njcn.rdms.framework.common.biz.infra.logger.ApiErrorLogCommonApi;
|
||||
import org.springframework.boot.autoconfigure.AutoConfiguration;
|
||||
import org.springframework.cloud.openfeign.EnableFeignClients;
|
||||
|
||||
/**
|
||||
* API 日志使用到 Feign 的配置项
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@AutoConfiguration
|
||||
@EnableFeignClients(clients = {ApiAccessLogCommonApi.class, ApiErrorLogCommonApi.class}) // 主要是引入相关的 API 服务
|
||||
public class RdmsApiLogRpcAutoConfiguration {
|
||||
}
|
||||
@@ -0,0 +1,65 @@
|
||||
package com.njcn.rdms.framework.apilog.core.annotation;
|
||||
|
||||
import com.njcn.rdms.framework.apilog.core.enums.OperateTypeEnum;
|
||||
|
||||
import java.lang.annotation.ElementType;
|
||||
import java.lang.annotation.Retention;
|
||||
import java.lang.annotation.RetentionPolicy;
|
||||
import java.lang.annotation.Target;
|
||||
|
||||
/**
|
||||
* 访问日志注解
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@Target({ElementType.METHOD})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface ApiAccessLog {
|
||||
|
||||
// ========== 开关字段 ==========
|
||||
|
||||
/**
|
||||
* 是否记录访问日志
|
||||
*/
|
||||
boolean enable() default true;
|
||||
/**
|
||||
* 是否记录请求参数
|
||||
*
|
||||
* 默认记录，主要考虑请求数据一般不大。可手动设置为 false 进行关闭
|
||||
*/
|
||||
boolean requestEnable() default true;
|
||||
/**
|
||||
* 是否记录响应结果
|
||||
*
|
||||
* 默认不记录，主要考虑响应数据可能比较大。可手动设置为 true 进行打开
|
||||
*/
|
||||
boolean responseEnable() default false;
|
||||
/**
|
||||
* 敏感参数数组
|
||||
*
|
||||
* 添加后，请求参数、响应结果不会记录该参数
|
||||
*/
|
||||
String[] sanitizeKeys() default {};
|
||||
|
||||
// ========== 模块字段 ==========
|
||||
|
||||
/**
|
||||
* 操作模块
|
||||
*
|
||||
* 为空时，会尝试读取 {@link io.swagger.v3.oas.annotations.tags.Tag#name()} 属性
|
||||
*/
|
||||
String operateModule() default "";
|
||||
/**
|
||||
* 操作名
|
||||
*
|
||||
* 为空时，会尝试读取 {@link io.swagger.v3.oas.annotations.Operation#summary()} 属性
|
||||
*/
|
||||
String operateName() default "";
|
||||
/**
|
||||
* 操作分类
|
||||
*
|
||||
* 实际并不是数组，因为枚举不能设置 null 作为默认值
|
||||
*/
|
||||
OperateTypeEnum[] operateType() default {};
|
||||
|
||||
}
|
||||
@@ -0,0 +1,51 @@
|
||||
package com.njcn.rdms.framework.apilog.core.enums;
|
||||
|
||||
import lombok.AllArgsConstructor;
|
||||
import lombok.Getter;
|
||||
|
||||
/**
|
||||
* 操作日志的操作类型
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@Getter
|
||||
@AllArgsConstructor
|
||||
public enum OperateTypeEnum {
|
||||
|
||||
/**
|
||||
* 查询
|
||||
*/
|
||||
GET(1),
|
||||
/**
|
||||
* 新增
|
||||
*/
|
||||
CREATE(2),
|
||||
/**
|
||||
* 修改
|
||||
*/
|
||||
UPDATE(3),
|
||||
/**
|
||||
* 删除
|
||||
*/
|
||||
DELETE(4),
|
||||
/**
|
||||
* 导出
|
||||
*/
|
||||
EXPORT(5),
|
||||
/**
|
||||
* 导入
|
||||
*/
|
||||
IMPORT(6),
|
||||
/**
|
||||
* 其它
|
||||
*
|
||||
* 在无法归类时，可以选择使用其它。因为还有操作名可以进一步标识
|
||||
*/
|
||||
OTHER(0);
|
||||
|
||||
/**
|
||||
* 类型
|
||||
*/
|
||||
private final Integer type;
|
||||
|
||||
}
|
||||
@@ -0,0 +1,252 @@
|
||||
package com.njcn.rdms.framework.apilog.core.filter;
|
||||
|
||||
import cn.hutool.core.collection.CollUtil;
|
||||
import cn.hutool.core.date.LocalDateTimeUtil;
|
||||
import cn.hutool.core.exceptions.ExceptionUtil;
|
||||
import cn.hutool.core.map.MapUtil;
|
||||
import cn.hutool.core.util.ArrayUtil;
|
||||
import cn.hutool.core.util.BooleanUtil;
|
||||
import cn.hutool.core.util.StrUtil;
|
||||
import com.fasterxml.jackson.databind.JsonNode;
|
||||
import com.njcn.rdms.framework.apilog.core.annotation.ApiAccessLog;
|
||||
import com.njcn.rdms.framework.apilog.core.enums.OperateTypeEnum;
|
||||
import com.njcn.rdms.framework.common.biz.infra.logger.ApiAccessLogCommonApi;
|
||||
import com.njcn.rdms.framework.common.biz.infra.logger.dto.ApiAccessLogCreateReqDTO;
|
||||
import com.njcn.rdms.framework.common.exception.enums.GlobalErrorCodeConstants;
|
||||
import com.njcn.rdms.framework.common.pojo.CommonResult;
|
||||
import com.njcn.rdms.framework.common.util.json.JsonUtils;
|
||||
import com.njcn.rdms.framework.common.util.monitor.TracerUtils;
|
||||
import com.njcn.rdms.framework.common.util.servlet.ServletUtils;
|
||||
import com.njcn.rdms.framework.web.config.WebProperties;
|
||||
import com.njcn.rdms.framework.web.core.filter.ApiRequestFilter;
|
||||
import com.njcn.rdms.framework.web.core.util.WebFrameworkUtils;
|
||||
import io.swagger.v3.oas.annotations.Operation;
|
||||
import io.swagger.v3.oas.annotations.tags.Tag;
|
||||
import jakarta.servlet.FilterChain;
|
||||
import jakarta.servlet.ServletException;
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import jakarta.servlet.http.HttpServletResponse;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.springframework.web.bind.annotation.RequestMethod;
|
||||
import org.springframework.web.method.HandlerMethod;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.time.LocalDateTime;
|
||||
import java.time.temporal.ChronoUnit;
|
||||
import java.util.Iterator;
|
||||
import java.util.Map;
|
||||
|
||||
import static com.njcn.rdms.framework.apilog.core.interceptor.ApiAccessLogInterceptor.ATTRIBUTE_HANDLER_METHOD;
|
||||
import static com.njcn.rdms.framework.common.util.json.JsonUtils.toJsonString;
|
||||
|
||||
/**
|
||||
* API 访问日志 Filter
|
||||
*
|
||||
* 目的：记录 API 访问日志到数据库中
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@Slf4j
|
||||
public class ApiAccessLogFilter extends ApiRequestFilter {
|
||||
|
||||
private static final String[] SANITIZE_KEYS = new String[]{"password", "token", "accessToken", "refreshToken"};
|
||||
|
||||
private final String applicationName;
|
||||
|
||||
private final ApiAccessLogCommonApi apiAccessLogApi;
|
||||
|
||||
public ApiAccessLogFilter(WebProperties webProperties, String applicationName, ApiAccessLogCommonApi apiAccessLogApi) {
|
||||
super(webProperties);
|
||||
this.applicationName = applicationName;
|
||||
this.apiAccessLogApi = apiAccessLogApi;
|
||||
}
|
||||
|
||||
@Override
|
||||
@SuppressWarnings("NullableProblems")
|
||||
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
|
||||
throws ServletException, IOException {
|
||||
// 获得开始时间
|
||||
LocalDateTime beginTime = LocalDateTime.now();
|
||||
// 提前获得参数，避免 XssFilter 过滤处理
|
||||
Map<String, String> queryString = ServletUtils.getParamMap(request);
|
||||
String requestBody = ServletUtils.isJsonRequest(request) ? ServletUtils.getBody(request) : null;
|
||||
|
||||
try {
|
||||
// 继续过滤器
|
||||
filterChain.doFilter(request, response);
|
||||
// 正常执行，记录日志
|
||||
createApiAccessLog(request, beginTime, queryString, requestBody, null);
|
||||
} catch (Exception ex) {
|
||||
// 异常执行，记录日志
|
||||
createApiAccessLog(request, beginTime, queryString, requestBody, ex);
|
||||
throw ex;
|
||||
}
|
||||
}
|
||||
|
||||
private void createApiAccessLog(HttpServletRequest request, LocalDateTime beginTime,
|
||||
Map<String, String> queryString, String requestBody, Exception ex) {
|
||||
ApiAccessLogCreateReqDTO accessLog = new ApiAccessLogCreateReqDTO();
|
||||
try {
|
||||
boolean enable = buildApiAccessLog(accessLog, request, beginTime, queryString, requestBody, ex);
|
||||
if (!enable) {
|
||||
return;
|
||||
}
|
||||
apiAccessLogApi.createApiAccessLogAsync(accessLog);
|
||||
} catch (Throwable th) {
|
||||
log.error("[createApiAccessLog][url({}) log({}) 发生异常]", request.getRequestURI(), toJsonString(accessLog), th);
|
||||
}
|
||||
}
|
||||
|
||||
private boolean buildApiAccessLog(ApiAccessLogCreateReqDTO accessLog, HttpServletRequest request, LocalDateTime beginTime,
|
||||
Map<String, String> queryString, String requestBody, Exception ex) {
|
||||
// 判断：是否要记录操作日志
|
||||
HandlerMethod handlerMethod = (HandlerMethod) request.getAttribute(ATTRIBUTE_HANDLER_METHOD);
|
||||
ApiAccessLog accessLogAnnotation = null;
|
||||
if (handlerMethod != null) {
|
||||
accessLogAnnotation = handlerMethod.getMethodAnnotation(ApiAccessLog.class);
|
||||
if (accessLogAnnotation != null && BooleanUtil.isFalse(accessLogAnnotation.enable())) {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
// 处理用户信息
|
||||
accessLog.setUserId(WebFrameworkUtils.getLoginUserId(request))
|
||||
.setUserType(WebFrameworkUtils.getLoginUserType(request));
|
||||
// 设置访问结果
|
||||
CommonResult<?> result = WebFrameworkUtils.getCommonResult(request);
|
||||
if (result != null) {
|
||||
accessLog.setResultCode(result.getCode()).setResultMsg(result.getMsg());
|
||||
} else if (ex != null) {
|
||||
accessLog.setResultCode(GlobalErrorCodeConstants.INTERNAL_SERVER_ERROR.getCode())
|
||||
.setResultMsg(ExceptionUtil.getRootCauseMessage(ex));
|
||||
} else {
|
||||
accessLog.setResultCode(GlobalErrorCodeConstants.SUCCESS.getCode()).setResultMsg("");
|
||||
}
|
||||
// 设置请求字段
|
||||
accessLog.setTraceId(TracerUtils.getTraceId()).setApplicationName(applicationName)
|
||||
.setRequestUrl(request.getRequestURI()).setRequestMethod(request.getMethod())
|
||||
.setUserAgent(ServletUtils.getUserAgent(request)).setUserIp(ServletUtils.getClientIP(request));
|
||||
String[] sanitizeKeys = accessLogAnnotation != null ? accessLogAnnotation.sanitizeKeys() : null;
|
||||
Boolean requestEnable = accessLogAnnotation != null ? accessLogAnnotation.requestEnable() : Boolean.TRUE;
|
||||
if (!BooleanUtil.isFalse(requestEnable)) { // 默认记录，所以判断 !false
|
||||
Map<String, Object> requestParams = MapUtil.<String, Object>builder()
|
||||
.put("query", sanitizeMap(queryString, sanitizeKeys))
|
||||
.put("body", sanitizeJson(requestBody, sanitizeKeys)).build();
|
||||
accessLog.setRequestParams(toJsonString(requestParams));
|
||||
}
|
||||
Boolean responseEnable = accessLogAnnotation != null ? accessLogAnnotation.responseEnable() : Boolean.FALSE;
|
||||
if (BooleanUtil.isTrue(responseEnable)) { // 默认不记录，默认强制要求 true
|
||||
accessLog.setResponseBody(sanitizeJson(result, sanitizeKeys));
|
||||
}
|
||||
// 持续时间
|
||||
accessLog.setBeginTime(beginTime).setEndTime(LocalDateTime.now())
|
||||
.setDuration((int) LocalDateTimeUtil.between(accessLog.getBeginTime(), accessLog.getEndTime(), ChronoUnit.MILLIS));
|
||||
|
||||
// 操作模块
|
||||
if (handlerMethod != null) {
|
||||
Tag tagAnnotation = handlerMethod.getBeanType().getAnnotation(Tag.class);
|
||||
Operation operationAnnotation = handlerMethod.getMethodAnnotation(Operation.class);
|
||||
String operateModule = accessLogAnnotation != null && StrUtil.isNotBlank(accessLogAnnotation.operateModule()) ?
|
||||
accessLogAnnotation.operateModule() :
|
||||
tagAnnotation != null ? StrUtil.nullToDefault(tagAnnotation.name(), tagAnnotation.description()) : null;
|
||||
String operateName = accessLogAnnotation != null && StrUtil.isNotBlank(accessLogAnnotation.operateName()) ?
|
||||
accessLogAnnotation.operateName() :
|
||||
operationAnnotation != null ? operationAnnotation.summary() : null;
|
||||
OperateTypeEnum operateType = accessLogAnnotation != null && accessLogAnnotation.operateType().length > 0 ?
|
||||
accessLogAnnotation.operateType()[0] : parseOperateLogType(request);
|
||||
accessLog.setOperateModule(operateModule).setOperateName(operateName).setOperateType(operateType.getType());
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
// ========== 解析 @ApiAccessLog、@Swagger 注解 ==========
|
||||
|
||||
private static OperateTypeEnum parseOperateLogType(HttpServletRequest request) {
|
||||
RequestMethod requestMethod = RequestMethod.resolve(request.getMethod());
|
||||
if (requestMethod == null) {
|
||||
return OperateTypeEnum.OTHER;
|
||||
}
|
||||
switch (requestMethod) {
|
||||
case GET:
|
||||
return OperateTypeEnum.GET;
|
||||
case POST:
|
||||
return OperateTypeEnum.CREATE;
|
||||
case PUT:
|
||||
return OperateTypeEnum.UPDATE;
|
||||
case DELETE:
|
||||
return OperateTypeEnum.DELETE;
|
||||
default:
|
||||
return OperateTypeEnum.OTHER;
|
||||
}
|
||||
}
|
||||
|
||||
// ========== 请求和响应的脱敏逻辑，移除类似 password、token 等敏感字段 ==========
|
||||
|
||||
private static String sanitizeMap(Map<String, ?> map, String[] sanitizeKeys) {
|
||||
if (CollUtil.isEmpty(map)) {
|
||||
return null;
|
||||
}
|
||||
if (sanitizeKeys != null) {
|
||||
MapUtil.removeAny(map, sanitizeKeys);
|
||||
}
|
||||
MapUtil.removeAny(map, SANITIZE_KEYS);
|
||||
return JsonUtils.toJsonString(map);
|
||||
}
|
||||
|
||||
private static String sanitizeJson(String jsonString, String[] sanitizeKeys) {
|
||||
if (StrUtil.isEmpty(jsonString)) {
|
||||
return null;
|
||||
}
|
||||
try {
|
||||
JsonNode rootNode = JsonUtils.parseTree(jsonString);
|
||||
sanitizeJson(rootNode, sanitizeKeys);
|
||||
return JsonUtils.toJsonString(rootNode);
|
||||
} catch (Exception e) {
|
||||
// 脱敏失败的情况下，直接忽略异常，避免影响用户请求
|
||||
log.error("[sanitizeJson][脱敏({}) 发生异常]", jsonString, e);
|
||||
return jsonString;
|
||||
}
|
||||
}
|
||||
|
||||
private static String sanitizeJson(CommonResult<?> commonResult, String[] sanitizeKeys) {
|
||||
if (commonResult == null) {
|
||||
return null;
|
||||
}
|
||||
String jsonString = toJsonString(commonResult);
|
||||
try {
|
||||
JsonNode rootNode = JsonUtils.parseTree(jsonString);
|
||||
sanitizeJson(rootNode.get("data"), sanitizeKeys); // 只处理 data 字段，不处理 code、msg 字段，避免错误被脱敏掉
|
||||
return JsonUtils.toJsonString(rootNode);
|
||||
} catch (Exception e) {
|
||||
// 脱敏失败的情况下，直接忽略异常，避免影响用户请求
|
||||
log.error("[sanitizeJson][脱敏({}) 发生异常]", jsonString, e);
|
||||
return jsonString;
|
||||
}
|
||||
}
|
||||
|
||||
private static void sanitizeJson(JsonNode node, String[] sanitizeKeys) {
|
||||
// 情况一：数组，遍历处理
|
||||
if (node.isArray()) {
|
||||
for (JsonNode childNode : node) {
|
||||
sanitizeJson(childNode, sanitizeKeys);
|
||||
}
|
||||
return;
|
||||
}
|
||||
// 情况二：非 Object，只是某个值，直接返回
|
||||
if (!node.isObject()) {
|
||||
return;
|
||||
}
|
||||
// 情况三：Object，遍历处理
|
||||
Iterator<Map.Entry<String, JsonNode>> iterator = node.properties().iterator();
|
||||
while (iterator.hasNext()) {
|
||||
Map.Entry<String, JsonNode> entry = iterator.next();
|
||||
if (ArrayUtil.contains(sanitizeKeys, entry.getKey())
|
||||
|| ArrayUtil.contains(SANITIZE_KEYS, entry.getKey())) {
|
||||
iterator.remove();
|
||||
continue;
|
||||
}
|
||||
sanitizeJson(entry.getValue(), sanitizeKeys);
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,33 @@
|
||||
package com.njcn.rdms.framework.apilog.core.interceptor;
|
||||
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import jakarta.servlet.http.HttpServletResponse;
|
||||
import org.springframework.web.method.HandlerMethod;
|
||||
import org.springframework.web.servlet.HandlerInterceptor;
|
||||
|
||||
/**
|
||||
* API 访问日志 Interceptor
|
||||
*
|
||||
* 目的：记录 HandlerMethod，提供给 ApiAccessLogFilter 使用
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
public class ApiAccessLogInterceptor implements HandlerInterceptor {
|
||||
|
||||
public static final String ATTRIBUTE_HANDLER_METHOD = "HANDLER_METHOD";
|
||||
|
||||
@Override
|
||||
public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) {
|
||||
// 记录 HandlerMethod，提供给 ApiAccessLogFilter 使用
|
||||
HandlerMethod handlerMethod = handler instanceof HandlerMethod ? (HandlerMethod) handler : null;
|
||||
if (handlerMethod != null) {
|
||||
request.setAttribute(ATTRIBUTE_HANDLER_METHOD, handlerMethod);
|
||||
}
|
||||
return true;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void afterCompletion(HttpServletRequest request, HttpServletResponse response, Object handler, Exception ex) {
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,8 @@
|
||||
/**
|
||||
* API 日志：包含两类
|
||||
* 1. API 访问日志：记录用户访问 API 的访问日志，定期归档历史日志。
|
||||
* 2. 异常日志：记录用户访问 API 的系统异常，方便日常排查问题与告警。
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
package com.njcn.rdms.framework.apilog;
|
||||
@@ -0,0 +1,20 @@
|
||||
package com.njcn.rdms.framework.banner.config;
|
||||
|
||||
import com.njcn.rdms.framework.banner.core.BannerApplicationRunner;
|
||||
import org.springframework.boot.autoconfigure.AutoConfiguration;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
|
||||
/**
|
||||
* Banner 的自动配置类
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@AutoConfiguration
|
||||
public class RdmsBannerAutoConfiguration {
|
||||
|
||||
@Bean
|
||||
public BannerApplicationRunner bannerApplicationRunner() {
|
||||
return new BannerApplicationRunner();
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,25 @@
|
||||
package com.njcn.rdms.framework.banner.core;
|
||||
|
||||
import cn.hutool.core.thread.ThreadUtil;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.springframework.boot.ApplicationArguments;
|
||||
import org.springframework.boot.ApplicationRunner;
|
||||
|
||||
import java.util.concurrent.TimeUnit;
|
||||
|
||||
/**
|
||||
* 项目启动成功后，提供文档相关的地址
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@Slf4j
|
||||
public class BannerApplicationRunner implements ApplicationRunner {
|
||||
|
||||
@Override
|
||||
public void run(ApplicationArguments args) {
|
||||
ThreadUtil.execute(() -> {
|
||||
ThreadUtil.sleep(1, TimeUnit.SECONDS); // 延迟 1 秒，保证输出到结尾
|
||||
});
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,6 @@
|
||||
/**
|
||||
* Banner 用于在 console 控制台，打印开发文档、接口文档等
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
package com.njcn.rdms.framework.banner;
|
||||
@@ -0,0 +1,28 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.base.annotation;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JacksonAnnotationsInside;
|
||||
import com.fasterxml.jackson.databind.annotation.JsonSerialize;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.handler.DesensitizationHandler;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.serializer.StringDesensitizeSerializer;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
/**
|
||||
* 顶级脱敏注解，自定义注解需要使用此注解
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
@Documented
|
||||
@Target(ElementType.ANNOTATION_TYPE)
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@JacksonAnnotationsInside // 此注解是其他所有 jackson 注解的元注解，打上了此注解的注解表明是 jackson 注解的一部分
|
||||
@JsonSerialize(using = StringDesensitizeSerializer.class) // 指定序列化器
|
||||
public @interface DesensitizeBy {
|
||||
|
||||
/**
|
||||
* 脱敏处理器
|
||||
*/
|
||||
@SuppressWarnings("rawtypes")
|
||||
Class<? extends DesensitizationHandler> handler();
|
||||
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.base.handler;
|
||||
|
||||
import cn.hutool.core.util.ReflectUtil;
|
||||
|
||||
import java.lang.annotation.Annotation;
|
||||
|
||||
/**
|
||||
* 脱敏处理器接口
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public interface DesensitizationHandler<T extends Annotation> {
|
||||
|
||||
/**
|
||||
* 脱敏
|
||||
*
|
||||
* @param origin 原始字符串
|
||||
* @param annotation 注解信息
|
||||
* @return 脱敏后的字符串
|
||||
*/
|
||||
String desensitize(String origin, T annotation);
|
||||
|
||||
/**
|
||||
* 是否禁用脱敏的 Spring EL 表达式
|
||||
*
|
||||
* 如果返回 true 则跳过脱敏
|
||||
*
|
||||
* @param annotation 注解信息
|
||||
* @return 是否禁用脱敏的 Spring EL 表达式
|
||||
*/
|
||||
default String getDisable(T annotation) {
|
||||
// 约定：默认就是 enable() 属性。如果不符合，子类重写
|
||||
try {
|
||||
return (String) ReflectUtil.invoke(annotation, "disable");
|
||||
} catch (Exception ex) {
|
||||
return "";
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,92 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.base.serializer;
|
||||
|
||||
import cn.hutool.core.annotation.AnnotationUtil;
|
||||
import cn.hutool.core.lang.Singleton;
|
||||
import cn.hutool.core.util.ArrayUtil;
|
||||
import cn.hutool.core.util.ReflectUtil;
|
||||
import cn.hutool.core.util.StrUtil;
|
||||
import com.fasterxml.jackson.core.JsonGenerator;
|
||||
import com.fasterxml.jackson.databind.BeanProperty;
|
||||
import com.fasterxml.jackson.databind.JsonSerializer;
|
||||
import com.fasterxml.jackson.databind.SerializerProvider;
|
||||
import com.fasterxml.jackson.databind.ser.ContextualSerializer;
|
||||
import com.fasterxml.jackson.databind.ser.std.StdSerializer;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.annotation.DesensitizeBy;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.handler.DesensitizationHandler;
|
||||
import lombok.Getter;
|
||||
import lombok.Setter;
|
||||
|
||||
import java.io.IOException;
|
||||
import java.lang.annotation.Annotation;
|
||||
import java.lang.reflect.Field;
|
||||
|
||||
/**
|
||||
* 脱敏序列化器
|
||||
*
|
||||
* 实现 JSON 返回数据时，使用 {@link DesensitizationHandler} 对声明脱敏注解的字段，进行脱敏处理。
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
@SuppressWarnings("rawtypes")
|
||||
public class StringDesensitizeSerializer extends StdSerializer<String> implements ContextualSerializer {
|
||||
|
||||
@Getter
|
||||
@Setter
|
||||
private DesensitizationHandler desensitizationHandler;
|
||||
|
||||
protected StringDesensitizeSerializer() {
|
||||
super(String.class);
|
||||
}
|
||||
|
||||
@Override
|
||||
public JsonSerializer<?> createContextual(SerializerProvider serializerProvider, BeanProperty beanProperty) {
|
||||
DesensitizeBy annotation = beanProperty.getAnnotation(DesensitizeBy.class);
|
||||
if (annotation == null) {
|
||||
return this;
|
||||
}
|
||||
// 创建一个 StringDesensitizeSerializer 对象，使用 DesensitizeBy 对应的处理器
|
||||
StringDesensitizeSerializer serializer = new StringDesensitizeSerializer();
|
||||
serializer.setDesensitizationHandler(Singleton.get(annotation.handler()));
|
||||
return serializer;
|
||||
}
|
||||
|
||||
@Override
|
||||
@SuppressWarnings("unchecked")
|
||||
public void serialize(String value, JsonGenerator gen, SerializerProvider serializerProvider) throws IOException {
|
||||
if (StrUtil.isBlank(value)) {
|
||||
gen.writeNull();
|
||||
return;
|
||||
}
|
||||
// 获取序列化字段
|
||||
Field field = getField(gen);
|
||||
|
||||
// 自定义处理器
|
||||
DesensitizeBy[] annotations = AnnotationUtil.getCombinationAnnotations(field, DesensitizeBy.class);
|
||||
if (ArrayUtil.isEmpty(annotations)) {
|
||||
gen.writeString(value);
|
||||
return;
|
||||
}
|
||||
for (Annotation annotation : field.getAnnotations()) {
|
||||
if (AnnotationUtil.hasAnnotation(annotation.annotationType(), DesensitizeBy.class)) {
|
||||
value = this.desensitizationHandler.desensitize(value, annotation);
|
||||
gen.writeString(value);
|
||||
return;
|
||||
}
|
||||
}
|
||||
gen.writeString(value);
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取字段
|
||||
*
|
||||
* @param generator JsonGenerator
|
||||
* @return 字段
|
||||
*/
|
||||
private Field getField(JsonGenerator generator) {
|
||||
String currentName = generator.getOutputContext().getCurrentName();
|
||||
Object currentValue = generator.currentValue();
|
||||
Class<?> currentValueClass = currentValue.getClass();
|
||||
return ReflectUtil.getField(currentValueClass, currentName);
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,40 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.regex.annotation;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JacksonAnnotationsInside;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.annotation.DesensitizeBy;
|
||||
import com.njcn.rdms.framework.desensitize.core.regex.handler.EmailDesensitizationHandler;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
/**
|
||||
* 邮箱脱敏注解
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
@Documented
|
||||
@Target({ElementType.FIELD})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@JacksonAnnotationsInside
|
||||
@DesensitizeBy(handler = EmailDesensitizationHandler.class)
|
||||
public @interface EmailDesensitize {
|
||||
|
||||
/**
|
||||
* 匹配的正则表达式
|
||||
*/
|
||||
String regex() default "(^.)[^@]*(@.*$)";
|
||||
|
||||
/**
|
||||
* 替换规则，邮箱;
|
||||
*
|
||||
* 比如：example@gmail.com 脱敏之后为 e****@gmail.com
|
||||
*/
|
||||
String replacer() default "$1****$2";
|
||||
|
||||
/**
|
||||
* 是否禁用脱敏
|
||||
*
|
||||
* 支持 Spring EL 表达式，如果返回 true 则跳过脱敏
|
||||
*/
|
||||
String disable() default "";
|
||||
|
||||
}
|
||||
@@ -0,0 +1,42 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.regex.annotation;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JacksonAnnotationsInside;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.annotation.DesensitizeBy;
|
||||
import com.njcn.rdms.framework.desensitize.core.regex.handler.DefaultRegexDesensitizationHandler;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
/**
|
||||
* 正则脱敏注解
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
@Documented
|
||||
@Target({ElementType.FIELD, ElementType.ANNOTATION_TYPE})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@JacksonAnnotationsInside
|
||||
@DesensitizeBy(handler = DefaultRegexDesensitizationHandler.class)
|
||||
public @interface RegexDesensitize {
|
||||
|
||||
/**
|
||||
* 匹配的正则表达式（默认匹配所有）
|
||||
*/
|
||||
String regex() default "^[\\s\\S]*$";
|
||||
|
||||
/**
|
||||
* 替换规则，会将匹配到的字符串全部替换成 replacer
|
||||
*
|
||||
* 例如：regex=123; replacer=******
|
||||
* 原始字符串 123456789
|
||||
* 脱敏后字符串 ******456789
|
||||
*/
|
||||
String replacer() default "******";
|
||||
|
||||
/**
|
||||
* 是否禁用脱敏
|
||||
*
|
||||
* 支持 Spring EL 表达式，如果返回 true 则跳过脱敏
|
||||
*/
|
||||
String disable() default "";
|
||||
|
||||
}
|
||||
@@ -0,0 +1,46 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.regex.handler;
|
||||
|
||||
import com.njcn.rdms.framework.common.util.spring.SpringExpressionUtils;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.handler.DesensitizationHandler;
|
||||
|
||||
import java.lang.annotation.Annotation;
|
||||
|
||||
/**
|
||||
* 正则表达式脱敏处理器抽象类，已实现通用的方法
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public abstract class AbstractRegexDesensitizationHandler<T extends Annotation>
|
||||
implements DesensitizationHandler<T> {
|
||||
|
||||
@Override
|
||||
public String desensitize(String origin, T annotation) {
|
||||
// 1. 判断是否禁用脱敏
|
||||
Object disable = SpringExpressionUtils.parseExpression(getDisable(annotation));
|
||||
if (Boolean.TRUE.equals(disable)) {
|
||||
return origin;
|
||||
}
|
||||
|
||||
// 2. 执行脱敏
|
||||
String regex = getRegex(annotation);
|
||||
String replacer = getReplacer(annotation);
|
||||
return origin.replaceAll(regex, replacer);
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取注解上的 regex 参数
|
||||
*
|
||||
* @param annotation 注解信息
|
||||
* @return 正则表达式
|
||||
*/
|
||||
abstract String getRegex(T annotation);
|
||||
|
||||
/**
|
||||
* 获取注解上的 replacer 参数
|
||||
*
|
||||
* @param annotation 注解信息
|
||||
* @return 待替换的字符串
|
||||
*/
|
||||
abstract String getReplacer(T annotation);
|
||||
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.regex.handler;
|
||||
|
||||
import com.njcn.rdms.framework.desensitize.core.regex.annotation.RegexDesensitize;
|
||||
|
||||
/**
|
||||
* {@link RegexDesensitize} 的正则脱敏处理器
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public class DefaultRegexDesensitizationHandler extends AbstractRegexDesensitizationHandler<RegexDesensitize> {
|
||||
|
||||
@Override
|
||||
String getRegex(RegexDesensitize annotation) {
|
||||
return annotation.regex();
|
||||
}
|
||||
|
||||
@Override
|
||||
String getReplacer(RegexDesensitize annotation) {
|
||||
return annotation.replacer();
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getDisable(RegexDesensitize annotation) {
|
||||
return annotation.disable();
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,22 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.regex.handler;
|
||||
|
||||
import com.njcn.rdms.framework.desensitize.core.regex.annotation.EmailDesensitize;
|
||||
|
||||
/**
|
||||
* {@link EmailDesensitize} 的脱敏处理器
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public class EmailDesensitizationHandler extends AbstractRegexDesensitizationHandler<EmailDesensitize> {
|
||||
|
||||
@Override
|
||||
String getRegex(EmailDesensitize annotation) {
|
||||
return annotation.regex();
|
||||
}
|
||||
|
||||
@Override
|
||||
String getReplacer(EmailDesensitize annotation) {
|
||||
return annotation.replacer();
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.annotation;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JacksonAnnotationsInside;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.annotation.DesensitizeBy;
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.handler.BankCardDesensitization;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
/**
|
||||
* 银行卡号
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
@Documented
|
||||
@Target({ElementType.FIELD})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@JacksonAnnotationsInside
|
||||
@DesensitizeBy(handler = BankCardDesensitization.class)
|
||||
public @interface BankCardDesensitize {
|
||||
|
||||
/**
|
||||
* 前缀保留长度
|
||||
*/
|
||||
int prefixKeep() default 6;
|
||||
|
||||
/**
|
||||
* 后缀保留长度
|
||||
*/
|
||||
int suffixKeep() default 2;
|
||||
|
||||
/**
|
||||
* 替换规则，银行卡号; 比如：9988002866797031 脱敏之后为 998800********31
|
||||
*/
|
||||
String replacer() default "*";
|
||||
|
||||
/**
|
||||
* 是否禁用脱敏
|
||||
*
|
||||
* 支持 Spring EL 表达式，如果返回 true 则跳过脱敏
|
||||
*/
|
||||
String disable() default "";
|
||||
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.annotation;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JacksonAnnotationsInside;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.annotation.DesensitizeBy;
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.handler.CarLicenseDesensitization;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
/**
|
||||
* 车牌号
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
@Documented
|
||||
@Target({ElementType.FIELD})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@JacksonAnnotationsInside
|
||||
@DesensitizeBy(handler = CarLicenseDesensitization.class)
|
||||
public @interface CarLicenseDesensitize {
|
||||
|
||||
/**
|
||||
* 前缀保留长度
|
||||
*/
|
||||
int prefixKeep() default 3;
|
||||
|
||||
/**
|
||||
* 后缀保留长度
|
||||
*/
|
||||
int suffixKeep() default 1;
|
||||
|
||||
/**
|
||||
* 替换规则，车牌号;比如：粤A66666 脱敏之后为粤A6***6
|
||||
*/
|
||||
String replacer() default "*";
|
||||
|
||||
/**
|
||||
* 是否禁用脱敏
|
||||
*
|
||||
* 支持 Spring EL 表达式，如果返回 true 则跳过脱敏
|
||||
*/
|
||||
String disable() default "";
|
||||
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.annotation;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JacksonAnnotationsInside;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.annotation.DesensitizeBy;
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.handler.ChineseNameDesensitization;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
/**
|
||||
* 中文名
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
@Documented
|
||||
@Target({ElementType.FIELD})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@JacksonAnnotationsInside
|
||||
@DesensitizeBy(handler = ChineseNameDesensitization.class)
|
||||
public @interface ChineseNameDesensitize {
|
||||
|
||||
/**
|
||||
* 前缀保留长度
|
||||
*/
|
||||
int prefixKeep() default 1;
|
||||
|
||||
/**
|
||||
* 后缀保留长度
|
||||
*/
|
||||
int suffixKeep() default 0;
|
||||
|
||||
/**
|
||||
* 替换规则，中文名;比如：刘子豪脱敏之后为刘**
|
||||
*/
|
||||
String replacer() default "*";
|
||||
|
||||
/**
|
||||
* 是否禁用脱敏
|
||||
*
|
||||
* 支持 Spring EL 表达式，如果返回 true 则跳过脱敏
|
||||
*/
|
||||
String disable() default "";
|
||||
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.annotation;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JacksonAnnotationsInside;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.annotation.DesensitizeBy;
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.handler.FixedPhoneDesensitization;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
/**
|
||||
* 固定电话
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
@Documented
|
||||
@Target({ElementType.FIELD})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@JacksonAnnotationsInside
|
||||
@DesensitizeBy(handler = FixedPhoneDesensitization.class)
|
||||
public @interface FixedPhoneDesensitize {
|
||||
|
||||
/**
|
||||
* 前缀保留长度
|
||||
*/
|
||||
int prefixKeep() default 4;
|
||||
|
||||
/**
|
||||
* 后缀保留长度
|
||||
*/
|
||||
int suffixKeep() default 2;
|
||||
|
||||
/**
|
||||
* 替换规则，固定电话;比如：01086551122 脱敏之后为 0108*****22
|
||||
*/
|
||||
String replacer() default "*";
|
||||
|
||||
/**
|
||||
* 是否禁用脱敏
|
||||
*
|
||||
* 支持 Spring EL 表达式，如果返回 true 则跳过脱敏
|
||||
*/
|
||||
String disable() default "";
|
||||
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.annotation;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JacksonAnnotationsInside;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.annotation.DesensitizeBy;
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.handler.IdCardDesensitization;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
/**
|
||||
* 身份证
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
@Documented
|
||||
@Target({ElementType.FIELD})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@JacksonAnnotationsInside
|
||||
@DesensitizeBy(handler = IdCardDesensitization.class)
|
||||
public @interface IdCardDesensitize {
|
||||
|
||||
/**
|
||||
* 前缀保留长度
|
||||
*/
|
||||
int prefixKeep() default 6;
|
||||
|
||||
/**
|
||||
* 后缀保留长度
|
||||
*/
|
||||
int suffixKeep() default 2;
|
||||
|
||||
/**
|
||||
* 替换规则，身份证号码;比如：530321199204074611 脱敏之后为 530321**********11
|
||||
*/
|
||||
String replacer() default "*";
|
||||
|
||||
/**
|
||||
* 是否禁用脱敏
|
||||
*
|
||||
* 支持 Spring EL 表达式，如果返回 true 则跳过脱敏
|
||||
*/
|
||||
String disable() default "";
|
||||
|
||||
}
|
||||
@@ -0,0 +1,43 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.annotation;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JacksonAnnotationsInside;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.annotation.DesensitizeBy;
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.handler.MobileDesensitization;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
/**
|
||||
* 手机号
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
@Documented
|
||||
@Target({ElementType.FIELD})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@JacksonAnnotationsInside
|
||||
@DesensitizeBy(handler = MobileDesensitization.class)
|
||||
public @interface MobileDesensitize {
|
||||
|
||||
/**
|
||||
* 前缀保留长度
|
||||
*/
|
||||
int prefixKeep() default 3;
|
||||
|
||||
/**
|
||||
* 后缀保留长度
|
||||
*/
|
||||
int suffixKeep() default 4;
|
||||
|
||||
/**
|
||||
* 替换规则，手机号;比如：13248765917 脱敏之后为 132****5917
|
||||
*/
|
||||
String replacer() default "*";
|
||||
|
||||
/**
|
||||
* 是否禁用脱敏
|
||||
*
|
||||
* 支持 Spring EL 表达式，如果返回 true 则跳过脱敏
|
||||
*/
|
||||
String disable() default "";
|
||||
|
||||
}
|
||||
@@ -0,0 +1,45 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.annotation;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JacksonAnnotationsInside;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.annotation.DesensitizeBy;
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.handler.PasswordDesensitization;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
/**
|
||||
* 密码
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
@Documented
|
||||
@Target({ElementType.FIELD})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@JacksonAnnotationsInside
|
||||
@DesensitizeBy(handler = PasswordDesensitization.class)
|
||||
public @interface PasswordDesensitize {
|
||||
|
||||
/**
|
||||
* 前缀保留长度
|
||||
*/
|
||||
int prefixKeep() default 0;
|
||||
|
||||
/**
|
||||
* 后缀保留长度
|
||||
*/
|
||||
int suffixKeep() default 0;
|
||||
|
||||
/**
|
||||
* 替换规则，密码;
|
||||
*
|
||||
* 比如：123456 脱敏之后为 ******
|
||||
*/
|
||||
String replacer() default "*";
|
||||
|
||||
/**
|
||||
* 是否禁用脱敏
|
||||
*
|
||||
* 支持 Spring EL 表达式，如果返回 true 则跳过脱敏
|
||||
*/
|
||||
String disable() default "";
|
||||
|
||||
}
|
||||
@@ -0,0 +1,47 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.annotation;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JacksonAnnotationsInside;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.annotation.DesensitizeBy;
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.handler.DefaultDesensitizationHandler;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
/**
|
||||
* 滑动脱敏注解
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
@Documented
|
||||
@Target({ElementType.FIELD, ElementType.ANNOTATION_TYPE})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
@JacksonAnnotationsInside
|
||||
@DesensitizeBy(handler = DefaultDesensitizationHandler.class)
|
||||
public @interface SliderDesensitize {
|
||||
|
||||
/**
|
||||
* 后缀保留长度
|
||||
*/
|
||||
int suffixKeep() default 0;
|
||||
|
||||
/**
|
||||
* 替换规则，会将前缀后缀保留后，全部替换成 replacer
|
||||
*
|
||||
* 例如：prefixKeep = 1; suffixKeep = 2; replacer = "*";
|
||||
* 原始字符串 123456
|
||||
* 脱敏后 1***56
|
||||
*/
|
||||
String replacer() default "*";
|
||||
|
||||
/**
|
||||
* 前缀保留长度
|
||||
*/
|
||||
int prefixKeep() default 0;
|
||||
|
||||
/**
|
||||
* 是否禁用脱敏
|
||||
*
|
||||
* 支持 Spring EL 表达式，如果返回 true 则跳过脱敏
|
||||
*/
|
||||
String disable() default "";
|
||||
|
||||
}
|
||||
@@ -0,0 +1,77 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.handler;
|
||||
|
||||
import com.njcn.rdms.framework.common.util.spring.SpringExpressionUtils;
|
||||
import com.njcn.rdms.framework.desensitize.core.base.handler.DesensitizationHandler;
|
||||
|
||||
import java.lang.annotation.Annotation;
|
||||
|
||||
/**
|
||||
* 滑动脱敏处理器抽象类，已实现通用的方法
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public abstract class AbstractSliderDesensitizationHandler<T extends Annotation>
|
||||
implements DesensitizationHandler<T> {
|
||||
|
||||
@Override
|
||||
public String desensitize(String origin, T annotation) {
|
||||
// 1. 判断是否禁用脱敏
|
||||
Object disable = SpringExpressionUtils.parseExpression(getDisable(annotation));
|
||||
if (Boolean.TRUE.equals(disable)) {
|
||||
return origin;
|
||||
}
|
||||
|
||||
// 2. 执行脱敏
|
||||
int prefixKeep = getPrefixKeep(annotation);
|
||||
int suffixKeep = getSuffixKeep(annotation);
|
||||
String replacer = getReplacer(annotation);
|
||||
int length = origin.length();
|
||||
int interval = length - prefixKeep - suffixKeep;
|
||||
|
||||
// 情况一：原始字符串长度小于等于前后缀保留字符串长度，则原始字符串全部替换
|
||||
if (interval <= 0) {
|
||||
return buildReplacerByLength(replacer, length);
|
||||
}
|
||||
|
||||
// 情况二：原始字符串长度大于前后缀保留字符串长度，则替换中间字符串
|
||||
return origin.substring(0, prefixKeep) +
|
||||
buildReplacerByLength(replacer, interval) +
|
||||
origin.substring(prefixKeep + interval);
|
||||
}
|
||||
|
||||
/**
|
||||
* 根据长度循环构建替换符
|
||||
*
|
||||
* @param replacer 替换符
|
||||
* @param length 长度
|
||||
* @return 构建后的替换符
|
||||
*/
|
||||
private String buildReplacerByLength(String replacer, int length) {
|
||||
return replacer.repeat(length);
|
||||
}
|
||||
|
||||
/**
|
||||
* 前缀保留长度
|
||||
*
|
||||
* @param annotation 注解信息
|
||||
* @return 前缀保留长度
|
||||
*/
|
||||
abstract Integer getPrefixKeep(T annotation);
|
||||
|
||||
/**
|
||||
* 后缀保留长度
|
||||
*
|
||||
* @param annotation 注解信息
|
||||
* @return 后缀保留长度
|
||||
*/
|
||||
abstract Integer getSuffixKeep(T annotation);
|
||||
|
||||
/**
|
||||
* 替换符
|
||||
*
|
||||
* @param annotation 注解信息
|
||||
* @return 替换符
|
||||
*/
|
||||
abstract String getReplacer(T annotation);
|
||||
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.handler;
|
||||
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.annotation.BankCardDesensitize;
|
||||
|
||||
/**
|
||||
* {@link BankCardDesensitize} 的脱敏处理器
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public class BankCardDesensitization extends AbstractSliderDesensitizationHandler<BankCardDesensitize> {
|
||||
|
||||
@Override
|
||||
Integer getPrefixKeep(BankCardDesensitize annotation) {
|
||||
return annotation.prefixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
Integer getSuffixKeep(BankCardDesensitize annotation) {
|
||||
return annotation.suffixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
String getReplacer(BankCardDesensitize annotation) {
|
||||
return annotation.replacer();
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getDisable(BankCardDesensitize annotation) {
|
||||
return "";
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.handler;
|
||||
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.annotation.CarLicenseDesensitize;
|
||||
|
||||
/**
|
||||
* {@link CarLicenseDesensitize} 的脱敏处理器
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public class CarLicenseDesensitization extends AbstractSliderDesensitizationHandler<CarLicenseDesensitize> {
|
||||
|
||||
@Override
|
||||
Integer getPrefixKeep(CarLicenseDesensitize annotation) {
|
||||
return annotation.prefixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
Integer getSuffixKeep(CarLicenseDesensitize annotation) {
|
||||
return annotation.suffixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
String getReplacer(CarLicenseDesensitize annotation) {
|
||||
return annotation.replacer();
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getDisable(CarLicenseDesensitize annotation) {
|
||||
return annotation.disable();
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.handler;
|
||||
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.annotation.ChineseNameDesensitize;
|
||||
|
||||
/**
|
||||
* {@link ChineseNameDesensitize} 的脱敏处理器
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public class ChineseNameDesensitization extends AbstractSliderDesensitizationHandler<ChineseNameDesensitize> {
|
||||
|
||||
@Override
|
||||
Integer getPrefixKeep(ChineseNameDesensitize annotation) {
|
||||
return annotation.prefixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
Integer getSuffixKeep(ChineseNameDesensitize annotation) {
|
||||
return annotation.suffixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
String getReplacer(ChineseNameDesensitize annotation) {
|
||||
return annotation.replacer();
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.handler;
|
||||
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.annotation.SliderDesensitize;
|
||||
|
||||
/**
|
||||
* {@link SliderDesensitize} 的脱敏处理器
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public class DefaultDesensitizationHandler extends AbstractSliderDesensitizationHandler<SliderDesensitize> {
|
||||
|
||||
@Override
|
||||
Integer getPrefixKeep(SliderDesensitize annotation) {
|
||||
return annotation.prefixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
Integer getSuffixKeep(SliderDesensitize annotation) {
|
||||
return annotation.suffixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
String getReplacer(SliderDesensitize annotation) {
|
||||
return annotation.replacer();
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.handler;
|
||||
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.annotation.FixedPhoneDesensitize;
|
||||
|
||||
/**
|
||||
* {@link FixedPhoneDesensitize} 的脱敏处理器
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public class FixedPhoneDesensitization extends AbstractSliderDesensitizationHandler<FixedPhoneDesensitize> {
|
||||
|
||||
@Override
|
||||
Integer getPrefixKeep(FixedPhoneDesensitize annotation) {
|
||||
return annotation.prefixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
Integer getSuffixKeep(FixedPhoneDesensitize annotation) {
|
||||
return annotation.suffixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
String getReplacer(FixedPhoneDesensitize annotation) {
|
||||
return annotation.replacer();
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.handler;
|
||||
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.annotation.IdCardDesensitize;
|
||||
|
||||
/**
|
||||
* {@link IdCardDesensitize} 的脱敏处理器
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public class IdCardDesensitization extends AbstractSliderDesensitizationHandler<IdCardDesensitize> {
|
||||
@Override
|
||||
Integer getPrefixKeep(IdCardDesensitize annotation) {
|
||||
return annotation.prefixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
Integer getSuffixKeep(IdCardDesensitize annotation) {
|
||||
return annotation.suffixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
String getReplacer(IdCardDesensitize annotation) {
|
||||
return annotation.replacer();
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,27 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.handler;
|
||||
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.annotation.MobileDesensitize;
|
||||
|
||||
/**
|
||||
* {@link MobileDesensitize} 的脱敏处理器
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public class MobileDesensitization extends AbstractSliderDesensitizationHandler<MobileDesensitize> {
|
||||
|
||||
@Override
|
||||
Integer getPrefixKeep(MobileDesensitize annotation) {
|
||||
return annotation.prefixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
Integer getSuffixKeep(MobileDesensitize annotation) {
|
||||
return annotation.suffixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
String getReplacer(MobileDesensitize annotation) {
|
||||
return annotation.replacer();
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
package com.njcn.rdms.framework.desensitize.core.slider.handler;
|
||||
|
||||
import com.njcn.rdms.framework.desensitize.core.slider.annotation.PasswordDesensitize;
|
||||
|
||||
/**
|
||||
* {@link PasswordDesensitize} 的码脱敏处理器
|
||||
*
|
||||
* @author gaibu
|
||||
*/
|
||||
public class PasswordDesensitization extends AbstractSliderDesensitizationHandler<PasswordDesensitize> {
|
||||
@Override
|
||||
Integer getPrefixKeep(PasswordDesensitize annotation) {
|
||||
return annotation.prefixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
Integer getSuffixKeep(PasswordDesensitize annotation) {
|
||||
return annotation.suffixKeep();
|
||||
}
|
||||
|
||||
@Override
|
||||
String getReplacer(PasswordDesensitize annotation) {
|
||||
return annotation.replacer();
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
/**
|
||||
* 脱敏组件：支持 JSON 返回数据时，将邮箱、手机等字段进行脱敏
|
||||
*/
|
||||
package com.njcn.rdms.framework.desensitize;
|
||||
@@ -0,0 +1,70 @@
|
||||
package com.njcn.rdms.framework.encrypt.config;
|
||||
|
||||
import jakarta.validation.constraints.NotEmpty;
|
||||
import jakarta.validation.constraints.NotNull;
|
||||
import lombok.Data;
|
||||
import org.springframework.boot.context.properties.ConfigurationProperties;
|
||||
import org.springframework.validation.annotation.Validated;
|
||||
|
||||
/**
|
||||
* HTTP API 加解密配置
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@ConfigurationProperties(prefix = "rdms.api-encrypt")
|
||||
@Validated
|
||||
@Data
|
||||
public class ApiEncryptProperties {
|
||||
|
||||
/**
|
||||
* 是否开启
|
||||
*/
|
||||
@NotNull(message = "是否开启不能为空")
|
||||
private Boolean enable;
|
||||
|
||||
/**
|
||||
* 请求头（响应头）名称
|
||||
*
|
||||
* 1. 如果该请求头非空，则表示请求参数已被「前端」加密，「后端」需要解密
|
||||
* 2. 如果该响应头非空，则表示响应结果已被「后端」加密，「前端」需要解密
|
||||
*/
|
||||
@NotEmpty(message = "请求头（响应头）名称不能为空")
|
||||
private String header = "X-Api-Encrypt";
|
||||
|
||||
/**
|
||||
* 对称加密算法，用于请求/响应的加解密
|
||||
*
|
||||
* 目前支持
|
||||
* 【对称加密】：
|
||||
* 1. {@link cn.hutool.crypto.symmetric.SymmetricAlgorithm#AES}
|
||||
* 2. {@link cn.hutool.crypto.symmetric.SM4#ALGORITHM_NAME} （需要自己二次开发，成本低）
|
||||
* 【非对称加密】
|
||||
* 1. {@link cn.hutool.crypto.asymmetric.AsymmetricAlgorithm#RSA}
|
||||
* 2. {@link cn.hutool.crypto.asymmetric.SM2} （需要自己二次开发，成本低）
|
||||
*
|
||||
* @see <a href="https://help.aliyun.com/zh/ssl-certificate/what-are-a-public-key-and-a-private-key">什么是公钥和私钥？</a>
|
||||
*/
|
||||
@NotEmpty(message = "对称加密算法不能为空")
|
||||
private String algorithm;
|
||||
|
||||
/**
|
||||
* 请求的解密密钥
|
||||
*
|
||||
* 注意：
|
||||
* 1. 如果是【对称加密】时，它「后端」对应的是“密钥”。对应的，「前端」也对应的也是“密钥”。
|
||||
* 2. 如果是【非对称加密】时，它「后端」对应的是“私钥”。对应的，「前端」对应的是“公钥”。（重要！！！）
|
||||
*/
|
||||
@NotEmpty(message = "请求的解密密钥不能为空")
|
||||
private String requestKey;
|
||||
|
||||
/**
|
||||
* 响应的加密密钥
|
||||
*
|
||||
* 注意：
|
||||
* 1. 如果是【对称加密】时，它「后端」对应的是“密钥”。对应的，「前端」也对应的也是“密钥”。
|
||||
* 2. 如果是【非对称加密】时，它「后端」对应的是“公钥”。对应的，「前端」对应的是“私钥”。（重要！！！）
|
||||
*/
|
||||
@NotEmpty(message = "响应的加密密钥不能为空")
|
||||
private String responseKey;
|
||||
|
||||
}
|
||||
@@ -0,0 +1,34 @@
|
||||
package com.njcn.rdms.framework.encrypt.config;
|
||||
|
||||
import com.njcn.rdms.framework.common.enums.WebFilterOrderEnum;
|
||||
import com.njcn.rdms.framework.encrypt.core.filter.ApiEncryptFilter;
|
||||
import com.njcn.rdms.framework.web.config.WebProperties;
|
||||
import com.njcn.rdms.framework.web.core.handler.GlobalExceptionHandler;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.springframework.boot.autoconfigure.AutoConfiguration;
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
|
||||
import org.springframework.boot.context.properties.EnableConfigurationProperties;
|
||||
import org.springframework.boot.web.servlet.FilterRegistrationBean;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
|
||||
|
||||
import static com.njcn.rdms.framework.web.config.RdmsWebAutoConfiguration.createFilterBean;
|
||||
|
||||
@AutoConfiguration
|
||||
@Slf4j
|
||||
@EnableConfigurationProperties(ApiEncryptProperties.class)
|
||||
@ConditionalOnProperty(prefix = "rdms.api-encrypt", name = "enable", havingValue = "true")
|
||||
public class RdmsApiEncryptAutoConfiguration {
|
||||
|
||||
@Bean
|
||||
public FilterRegistrationBean<ApiEncryptFilter> apiEncryptFilter(WebProperties webProperties,
|
||||
ApiEncryptProperties apiEncryptProperties,
|
||||
RequestMappingHandlerMapping requestMappingHandlerMapping,
|
||||
GlobalExceptionHandler globalExceptionHandler) {
|
||||
ApiEncryptFilter filter = new ApiEncryptFilter(webProperties, apiEncryptProperties,
|
||||
requestMappingHandlerMapping, globalExceptionHandler);
|
||||
return createFilterBean(filter, WebFilterOrderEnum.API_ENCRYPT_FILTER);
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,23 @@
|
||||
package com.njcn.rdms.framework.encrypt.core.annotation;
|
||||
|
||||
import java.lang.annotation.*;
|
||||
|
||||
/**
|
||||
* HTTP API 加解密注解
|
||||
*/
|
||||
@Documented
|
||||
@Target({ElementType.TYPE, ElementType.METHOD})
|
||||
@Retention(RetentionPolicy.RUNTIME)
|
||||
public @interface ApiEncrypt {
|
||||
|
||||
/**
|
||||
* 是否对请求参数进行解密，默认 true
|
||||
*/
|
||||
boolean request() default true;
|
||||
|
||||
/**
|
||||
* 是否对响应结果进行加密，默认 true
|
||||
*/
|
||||
boolean response() default true;
|
||||
|
||||
}
|
||||
@@ -0,0 +1,86 @@
|
||||
package com.njcn.rdms.framework.encrypt.core.filter;
|
||||
|
||||
import cn.hutool.core.io.IoUtil;
|
||||
import cn.hutool.core.util.StrUtil;
|
||||
import cn.hutool.crypto.asymmetric.AsymmetricDecryptor;
|
||||
import cn.hutool.crypto.asymmetric.KeyType;
|
||||
import cn.hutool.crypto.symmetric.SymmetricDecryptor;
|
||||
import jakarta.servlet.ReadListener;
|
||||
import jakarta.servlet.ServletInputStream;
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import jakarta.servlet.http.HttpServletRequestWrapper;
|
||||
|
||||
import java.io.BufferedReader;
|
||||
import java.io.ByteArrayInputStream;
|
||||
import java.io.IOException;
|
||||
import java.io.InputStreamReader;
|
||||
|
||||
/**
|
||||
* 解密请求 {@link HttpServletRequestWrapper} 实现类
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
public class ApiDecryptRequestWrapper extends HttpServletRequestWrapper {
|
||||
|
||||
private final byte[] body;
|
||||
|
||||
public ApiDecryptRequestWrapper(HttpServletRequest request,
|
||||
SymmetricDecryptor symmetricDecryptor,
|
||||
AsymmetricDecryptor asymmetricDecryptor) throws IOException {
|
||||
super(request);
|
||||
// 读取 body，允许 HEX、BASE64 传输
|
||||
String requestBody = StrUtil.utf8Str(
|
||||
IoUtil.readBytes(request.getInputStream(), false));
|
||||
|
||||
// 解密 body
|
||||
body = symmetricDecryptor != null ? symmetricDecryptor.decrypt(requestBody)
|
||||
: asymmetricDecryptor.decrypt(requestBody, KeyType.PrivateKey);
|
||||
}
|
||||
|
||||
@Override
|
||||
public BufferedReader getReader() {
|
||||
return new BufferedReader(new InputStreamReader(this.getInputStream()));
|
||||
}
|
||||
|
||||
@Override
|
||||
public int getContentLength() {
|
||||
return body.length;
|
||||
}
|
||||
|
||||
@Override
|
||||
public long getContentLengthLong() {
|
||||
return body.length;
|
||||
}
|
||||
|
||||
@Override
|
||||
public ServletInputStream getInputStream() {
|
||||
ByteArrayInputStream stream = new ByteArrayInputStream(body);
|
||||
return new ServletInputStream() {
|
||||
|
||||
@Override
|
||||
public int read() {
|
||||
return stream.read();
|
||||
}
|
||||
|
||||
@Override
|
||||
public int available() {
|
||||
return body.length;
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean isFinished() {
|
||||
return false;
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean isReady() {
|
||||
return false;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void setReadListener(ReadListener readListener) {
|
||||
}
|
||||
|
||||
};
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,161 @@
|
||||
package com.njcn.rdms.framework.encrypt.core.filter;
|
||||
|
||||
import cn.hutool.core.util.StrUtil;
|
||||
import cn.hutool.crypto.SecureUtil;
|
||||
import cn.hutool.crypto.asymmetric.AsymmetricDecryptor;
|
||||
import cn.hutool.crypto.asymmetric.AsymmetricEncryptor;
|
||||
import cn.hutool.crypto.symmetric.SymmetricDecryptor;
|
||||
import cn.hutool.crypto.symmetric.SymmetricEncryptor;
|
||||
import com.njcn.rdms.framework.common.pojo.CommonResult;
|
||||
import com.njcn.rdms.framework.common.util.object.ObjectUtils;
|
||||
import com.njcn.rdms.framework.common.util.servlet.ServletUtils;
|
||||
import com.njcn.rdms.framework.encrypt.config.ApiEncryptProperties;
|
||||
import com.njcn.rdms.framework.encrypt.core.annotation.ApiEncrypt;
|
||||
import com.njcn.rdms.framework.web.config.WebProperties;
|
||||
import com.njcn.rdms.framework.web.core.filter.ApiRequestFilter;
|
||||
import com.njcn.rdms.framework.web.core.handler.GlobalExceptionHandler;
|
||||
import jakarta.servlet.FilterChain;
|
||||
import jakarta.servlet.ServletException;
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import jakarta.servlet.http.HttpServletResponse;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.springframework.http.HttpMethod;
|
||||
import org.springframework.web.method.HandlerMethod;
|
||||
import org.springframework.web.servlet.HandlerExecutionChain;
|
||||
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
|
||||
import org.springframework.web.util.ServletRequestPathUtils;
|
||||
|
||||
import java.io.IOException;
|
||||
|
||||
import static com.njcn.rdms.framework.common.exception.util.ServiceExceptionUtil.invalidParamException;
|
||||
|
||||
/**
|
||||
* API 加密过滤器，处理 {@link ApiEncrypt} 注解。
|
||||
*
|
||||
* 1. 解密请求参数
|
||||
* 2. 加密响应结果
|
||||
*
|
||||
* 疑问：为什么不使用 SpringMVC 的 RequestBodyAdvice 或 ResponseBodyAdvice 机制呢？
|
||||
* 回答：考虑到项目中会记录访问日志、异常日志，以及 HTTP API 签名等场景，最好是全局级、且提前做解析！！！
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@Slf4j
|
||||
public class ApiEncryptFilter extends ApiRequestFilter {
|
||||
|
||||
private final ApiEncryptProperties apiEncryptProperties;
|
||||
|
||||
private final RequestMappingHandlerMapping requestMappingHandlerMapping;
|
||||
|
||||
private final GlobalExceptionHandler globalExceptionHandler;
|
||||
|
||||
private final SymmetricDecryptor requestSymmetricDecryptor;
|
||||
private final AsymmetricDecryptor requestAsymmetricDecryptor;
|
||||
|
||||
private final SymmetricEncryptor responseSymmetricEncryptor;
|
||||
private final AsymmetricEncryptor responseAsymmetricEncryptor;
|
||||
|
||||
public ApiEncryptFilter(WebProperties webProperties,
|
||||
ApiEncryptProperties apiEncryptProperties,
|
||||
RequestMappingHandlerMapping requestMappingHandlerMapping,
|
||||
GlobalExceptionHandler globalExceptionHandler) {
|
||||
super(webProperties);
|
||||
this.apiEncryptProperties = apiEncryptProperties;
|
||||
this.requestMappingHandlerMapping = requestMappingHandlerMapping;
|
||||
this.globalExceptionHandler = globalExceptionHandler;
|
||||
if (StrUtil.equalsIgnoreCase(apiEncryptProperties.getAlgorithm(), "AES")) {
|
||||
this.requestSymmetricDecryptor = SecureUtil.aes(StrUtil.utf8Bytes(apiEncryptProperties.getRequestKey()));
|
||||
this.requestAsymmetricDecryptor = null;
|
||||
this.responseSymmetricEncryptor = SecureUtil.aes(StrUtil.utf8Bytes(apiEncryptProperties.getResponseKey()));
|
||||
this.responseAsymmetricEncryptor = null;
|
||||
} else if (StrUtil.equalsIgnoreCase(apiEncryptProperties.getAlgorithm(), "RSA")) {
|
||||
this.requestSymmetricDecryptor = null;
|
||||
this.requestAsymmetricDecryptor = SecureUtil.rsa(apiEncryptProperties.getRequestKey(), null);
|
||||
this.responseSymmetricEncryptor = null;
|
||||
this.responseAsymmetricEncryptor = SecureUtil.rsa(null, apiEncryptProperties.getResponseKey());
|
||||
} else {
|
||||
// 补充说明：如果要支持 SM2、SM4 等算法，可在此处增加对应实例的创建，并添加相应的 Maven 依赖即可。
|
||||
throw new IllegalArgumentException("不支持的加密算法：" + apiEncryptProperties.getAlgorithm());
|
||||
}
|
||||
}
|
||||
|
||||
@Override
|
||||
@SuppressWarnings("NullableProblems")
|
||||
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain chain)
|
||||
throws ServletException, IOException {
|
||||
// 获取 @ApiEncrypt 注解
|
||||
ApiEncrypt apiEncrypt = getApiEncrypt(request);
|
||||
boolean requestEnable = apiEncrypt != null && apiEncrypt.request();
|
||||
boolean responseEnable = apiEncrypt != null && apiEncrypt.response();
|
||||
String encryptHeader = request.getHeader(apiEncryptProperties.getHeader());
|
||||
if (!requestEnable && !responseEnable && StrUtil.isBlank(encryptHeader)) {
|
||||
chain.doFilter(request, response);
|
||||
return;
|
||||
}
|
||||
|
||||
// 1. 解密请求
|
||||
if (ObjectUtils.equalsAny(HttpMethod.valueOf(request.getMethod()),
|
||||
HttpMethod.POST, HttpMethod.PUT, HttpMethod.DELETE)) {
|
||||
try {
|
||||
if (StrUtil.isNotBlank(encryptHeader)) {
|
||||
request = new ApiDecryptRequestWrapper(request,
|
||||
requestSymmetricDecryptor, requestAsymmetricDecryptor);
|
||||
} else if (requestEnable) {
|
||||
throw invalidParamException("请求未包含加密标头，请检查是否正确配置了加密标头");
|
||||
}
|
||||
} catch (Exception ex) {
|
||||
CommonResult<?> result = globalExceptionHandler.allExceptionHandler(request, ex);
|
||||
ServletUtils.writeJSON(response, result);
|
||||
return;
|
||||
}
|
||||
}
|
||||
|
||||
// 2. 执行过滤器链
|
||||
if (responseEnable) {
|
||||
// 特殊：仅包装，最后执行。目的：Response 内容可以被重复读取！！！
|
||||
response = new ApiEncryptResponseWrapper(response);
|
||||
}
|
||||
chain.doFilter(request, response);
|
||||
|
||||
// 3. 加密响应（真正执行）
|
||||
if (responseEnable) {
|
||||
((ApiEncryptResponseWrapper) response).encrypt(apiEncryptProperties,
|
||||
responseSymmetricEncryptor, responseAsymmetricEncryptor);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取 @ApiEncrypt 注解
|
||||
*
|
||||
* @param request 请求
|
||||
*/
|
||||
@SuppressWarnings("PatternVariableCanBeUsed")
|
||||
private ApiEncrypt getApiEncrypt(HttpServletRequest request) {
|
||||
try {
|
||||
// 特殊：兼容 SpringBoot 2.X 版本会报错的问题 https://t.zsxq.com/kqyiB
|
||||
if (!ServletRequestPathUtils.hasParsedRequestPath(request)) {
|
||||
ServletRequestPathUtils.parseAndCache(request);
|
||||
}
|
||||
|
||||
// 解析 @ApiEncrypt 注解
|
||||
HandlerExecutionChain mappingHandler = requestMappingHandlerMapping.getHandler(request);
|
||||
if (mappingHandler == null) {
|
||||
return null;
|
||||
}
|
||||
Object handler = mappingHandler.getHandler();
|
||||
if (handler instanceof HandlerMethod) {
|
||||
HandlerMethod handlerMethod = (HandlerMethod) handler;
|
||||
ApiEncrypt annotation = handlerMethod.getMethodAnnotation(ApiEncrypt.class);
|
||||
if (annotation == null) {
|
||||
annotation = handlerMethod.getBeanType().getAnnotation(ApiEncrypt.class);
|
||||
}
|
||||
return annotation;
|
||||
}
|
||||
} catch (Exception e) {
|
||||
log.error("[getApiEncrypt][url({}/{}) 获取 @ApiEncrypt 注解失败]",
|
||||
request.getRequestURI(), request.getMethod(), e);
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,110 @@
|
||||
package com.njcn.rdms.framework.encrypt.core.filter;
|
||||
|
||||
import cn.hutool.crypto.asymmetric.AsymmetricEncryptor;
|
||||
import cn.hutool.crypto.asymmetric.KeyType;
|
||||
import cn.hutool.crypto.symmetric.SymmetricEncryptor;
|
||||
import com.njcn.rdms.framework.encrypt.config.ApiEncryptProperties;
|
||||
import jakarta.servlet.ServletOutputStream;
|
||||
import jakarta.servlet.WriteListener;
|
||||
import jakarta.servlet.http.HttpServletResponse;
|
||||
import jakarta.servlet.http.HttpServletResponseWrapper;
|
||||
|
||||
import java.io.ByteArrayOutputStream;
|
||||
import java.io.IOException;
|
||||
import java.io.OutputStreamWriter;
|
||||
import java.io.PrintWriter;
|
||||
|
||||
/**
|
||||
* 加密响应 {@link HttpServletResponseWrapper} 实现类
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
public class ApiEncryptResponseWrapper extends HttpServletResponseWrapper {
|
||||
|
||||
private final ByteArrayOutputStream byteArrayOutputStream;
|
||||
private final ServletOutputStream servletOutputStream;
|
||||
private final PrintWriter printWriter;
|
||||
|
||||
public ApiEncryptResponseWrapper(HttpServletResponse response) {
|
||||
super(response);
|
||||
this.byteArrayOutputStream = new ByteArrayOutputStream();
|
||||
this.servletOutputStream = this.getOutputStream();
|
||||
this.printWriter = new PrintWriter(new OutputStreamWriter(byteArrayOutputStream));
|
||||
}
|
||||
|
||||
public void encrypt(ApiEncryptProperties properties,
|
||||
SymmetricEncryptor symmetricEncryptor,
|
||||
AsymmetricEncryptor asymmetricEncryptor) throws IOException {
|
||||
// 1.1 清空 body
|
||||
HttpServletResponse response = (HttpServletResponse) this.getResponse();
|
||||
response.resetBuffer();
|
||||
// 1.2 获取 body
|
||||
this.flushBuffer();
|
||||
byte[] body = byteArrayOutputStream.toByteArray();
|
||||
|
||||
// 2. 添加加密 header 标识
|
||||
this.addHeader(properties.getHeader(), "true");
|
||||
// 特殊：特殊：https://juejin.cn/post/6867327674675625992
|
||||
this.addHeader("Access-Control-Expose-Headers", properties.getHeader());
|
||||
|
||||
// 3.1 加密 body
|
||||
String encryptedBody = symmetricEncryptor != null ? symmetricEncryptor.encryptBase64(body)
|
||||
: asymmetricEncryptor.encryptBase64(body, KeyType.PublicKey);
|
||||
// 3.2 输出加密后的 body：（设置 header 要放在 response 的 write 之前）
|
||||
response.getWriter().write(encryptedBody);
|
||||
}
|
||||
|
||||
@Override
|
||||
public PrintWriter getWriter() {
|
||||
return printWriter;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void flushBuffer() throws IOException {
|
||||
if (servletOutputStream != null) {
|
||||
servletOutputStream.flush();
|
||||
}
|
||||
if (printWriter != null) {
|
||||
printWriter.flush();
|
||||
}
|
||||
}
|
||||
|
||||
@Override
|
||||
public void reset() {
|
||||
byteArrayOutputStream.reset();
|
||||
}
|
||||
|
||||
@Override
|
||||
public ServletOutputStream getOutputStream() {
|
||||
return new ServletOutputStream() {
|
||||
|
||||
@Override
|
||||
public boolean isReady() {
|
||||
return false;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void setWriteListener(WriteListener writeListener) {
|
||||
}
|
||||
|
||||
@Override
|
||||
public void write(int b) {
|
||||
byteArrayOutputStream.write(b);
|
||||
}
|
||||
|
||||
@Override
|
||||
@SuppressWarnings("NullableProblems")
|
||||
public void write(byte[] b) throws IOException {
|
||||
byteArrayOutputStream.write(b);
|
||||
}
|
||||
|
||||
@Override
|
||||
@SuppressWarnings("NullableProblems")
|
||||
public void write(byte[] b, int off, int len) {
|
||||
byteArrayOutputStream.write(b, off, len);
|
||||
}
|
||||
|
||||
};
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
/**
|
||||
* HTTP API 加密组件：支持 Request 和 Response 的加密、解密
|
||||
*/
|
||||
package com.njcn.rdms.framework.encrypt;
|
||||
@@ -0,0 +1,78 @@
|
||||
package com.njcn.rdms.framework.jackson.config;
|
||||
|
||||
import com.fasterxml.jackson.databind.Module;
|
||||
import com.fasterxml.jackson.databind.ObjectMapper;
|
||||
import com.fasterxml.jackson.databind.module.SimpleModule;
|
||||
import com.fasterxml.jackson.datatype.jsr310.deser.LocalDateDeserializer;
|
||||
import com.fasterxml.jackson.datatype.jsr310.deser.LocalTimeDeserializer;
|
||||
import com.fasterxml.jackson.datatype.jsr310.ser.LocalDateSerializer;
|
||||
import com.fasterxml.jackson.datatype.jsr310.ser.LocalTimeSerializer;
|
||||
import com.njcn.rdms.framework.common.util.json.JsonUtils;
|
||||
import com.njcn.rdms.framework.common.util.json.databind.NumberSerializer;
|
||||
import com.njcn.rdms.framework.common.util.json.databind.TimestampLocalDateTimeDeserializer;
|
||||
import com.njcn.rdms.framework.common.util.json.databind.TimestampLocalDateTimeSerializer;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.springframework.boot.autoconfigure.AutoConfiguration;
|
||||
import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;
|
||||
import org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
|
||||
import java.time.LocalDate;
|
||||
import java.time.LocalDateTime;
|
||||
import java.time.LocalTime;
|
||||
|
||||
@AutoConfiguration(after = JacksonAutoConfiguration.class)
|
||||
@Slf4j
|
||||
public class RdmsJacksonAutoConfiguration {
|
||||
|
||||
/**
|
||||
* 从 Builder 源头定制（关键：使用 *ByType，避免 handledType 要求）
|
||||
*/
|
||||
@Bean
|
||||
public Jackson2ObjectMapperBuilderCustomizer ldtEpochMillisCustomizer() {
|
||||
return builder -> builder
|
||||
// Long -> Number
|
||||
.serializerByType(Long.class, NumberSerializer.INSTANCE)
|
||||
.serializerByType(Long.TYPE, NumberSerializer.INSTANCE)
|
||||
// LocalDate / LocalTime
|
||||
.serializerByType(LocalDate.class, LocalDateSerializer.INSTANCE)
|
||||
.deserializerByType(LocalDate.class, LocalDateDeserializer.INSTANCE)
|
||||
.serializerByType(LocalTime.class, LocalTimeSerializer.INSTANCE)
|
||||
.deserializerByType(LocalTime.class, LocalTimeDeserializer.INSTANCE)
|
||||
// LocalDateTime < - > EpochMillis
|
||||
.serializerByType(LocalDateTime.class, TimestampLocalDateTimeSerializer.INSTANCE)
|
||||
.deserializerByType(LocalDateTime.class, TimestampLocalDateTimeDeserializer.INSTANCE);
|
||||
}
|
||||
|
||||
/**
|
||||
* 以 Bean 形式暴露 Module（Boot 会自动注册到所有 ObjectMapper）
|
||||
*/
|
||||
@Bean
|
||||
public Module timestampSupportModuleBean() {
|
||||
SimpleModule m = new SimpleModule("TimestampSupportModule");
|
||||
// Long -> Number，避免前端精度丢失
|
||||
m.addSerializer(Long.class, NumberSerializer.INSTANCE);
|
||||
m.addSerializer(Long.TYPE, NumberSerializer.INSTANCE);
|
||||
// LocalDate / LocalTime
|
||||
m.addSerializer(LocalDate.class, LocalDateSerializer.INSTANCE);
|
||||
m.addDeserializer(LocalDate.class, LocalDateDeserializer.INSTANCE);
|
||||
m.addSerializer(LocalTime.class, LocalTimeSerializer.INSTANCE);
|
||||
m.addDeserializer(LocalTime.class, LocalTimeDeserializer.INSTANCE);
|
||||
// LocalDateTime < - > EpochMillis
|
||||
m.addSerializer(LocalDateTime.class, TimestampLocalDateTimeSerializer.INSTANCE);
|
||||
m.addDeserializer(LocalDateTime.class, TimestampLocalDateTimeDeserializer.INSTANCE);
|
||||
return m;
|
||||
}
|
||||
|
||||
/**
|
||||
* 初始化全局 JsonUtils，直接使用主 ObjectMapper
|
||||
*/
|
||||
@Bean
|
||||
@SuppressWarnings("InstantiationOfUtilityClass")
|
||||
public JsonUtils jsonUtils(ObjectMapper objectMapper) {
|
||||
JsonUtils.init(objectMapper);
|
||||
log.debug("[init][初始化 JsonUtils 成功]");
|
||||
return new JsonUtils();
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1 @@
|
||||
package com.njcn.rdms.framework.jackson.core;
|
||||
@@ -0,0 +1,146 @@
|
||||
package com.njcn.rdms.framework.swagger.config;
|
||||
|
||||
import com.github.xiaoymin.knife4j.annotations.ApiSupport;
|
||||
import com.github.xiaoymin.knife4j.core.conf.ExtensionsConstants;
|
||||
import com.github.xiaoymin.knife4j.core.conf.GlobalConstants;
|
||||
import com.github.xiaoymin.knife4j.spring.configuration.Knife4jProperties;
|
||||
import com.github.xiaoymin.knife4j.spring.configuration.Knife4jSetting;
|
||||
import com.github.xiaoymin.knife4j.spring.extension.OpenApiExtensionResolver;
|
||||
import io.swagger.v3.oas.annotations.tags.Tag;
|
||||
import io.swagger.v3.oas.models.OpenAPI;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.apache.commons.lang3.ArrayUtils;
|
||||
import org.springdoc.core.customizers.GlobalOpenApiCustomizer;
|
||||
import org.springdoc.core.properties.SpringDocConfigProperties;
|
||||
import org.springframework.beans.factory.config.BeanDefinition;
|
||||
import org.springframework.context.annotation.ClassPathScanningCandidateComponentProvider;
|
||||
import org.springframework.context.annotation.Configuration;
|
||||
import org.springframework.context.annotation.Primary;
|
||||
import org.springframework.core.type.filter.AnnotationTypeFilter;
|
||||
import org.springframework.util.CollectionUtils;
|
||||
import org.springframework.web.bind.annotation.RestController;
|
||||
|
||||
import java.lang.annotation.Annotation;
|
||||
import java.util.*;
|
||||
import java.util.stream.Collectors;
|
||||
|
||||
/**
|
||||
* 增强扩展属性支持
|
||||
*
|
||||
* 参考 <a href="https://github.com/xiaoymin/knife4j/issues/913">Spring Boot 3.4 以上版本 /v3/api-docs 解决接口报错，依赖修复</a>
|
||||
*
|
||||
* @since 4.1.0
|
||||
* @author <a href="xiaoymin@foxmail.com">xiaoymin@foxmail.com</a>
|
||||
* 2022/12/11 22:40
|
||||
*/
|
||||
@Primary
|
||||
@Configuration
|
||||
@Slf4j
|
||||
public class Knife4jOpenApiCustomizer extends com.github.xiaoymin.knife4j.spring.extension.Knife4jOpenApiCustomizer
|
||||
implements GlobalOpenApiCustomizer {
|
||||
|
||||
final Knife4jProperties knife4jProperties;
|
||||
final SpringDocConfigProperties properties;
|
||||
|
||||
public Knife4jOpenApiCustomizer(Knife4jProperties knife4jProperties, SpringDocConfigProperties properties) {
|
||||
super(knife4jProperties,properties);
|
||||
this.knife4jProperties = knife4jProperties;
|
||||
this.properties = properties;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void customise(OpenAPI openApi) {
|
||||
if (knife4jProperties.isEnable()) {
|
||||
Knife4jSetting setting = knife4jProperties.getSetting();
|
||||
OpenApiExtensionResolver openApiExtensionResolver = new OpenApiExtensionResolver(setting, knife4jProperties.getDocuments());
|
||||
// 解析初始化
|
||||
openApiExtensionResolver.start();
|
||||
Map<String, Object> objectMap = new HashMap<>();
|
||||
objectMap.put(GlobalConstants.EXTENSION_OPEN_SETTING_NAME, setting);
|
||||
objectMap.put(GlobalConstants.EXTENSION_OPEN_MARKDOWN_NAME, openApiExtensionResolver.getMarkdownFiles());
|
||||
openApi.addExtension(GlobalConstants.EXTENSION_OPEN_API_NAME, objectMap);
|
||||
addOrderExtension(openApi);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 往 OpenAPI 内 tags 字段添加 x-order 属性
|
||||
*
|
||||
* @param openApi openApi
|
||||
*/
|
||||
private void addOrderExtension(OpenAPI openApi) {
|
||||
if (CollectionUtils.isEmpty(properties.getGroupConfigs())) {
|
||||
return;
|
||||
}
|
||||
// 获取包扫描路径
|
||||
Set<String> packagesToScan =
|
||||
properties.getGroupConfigs().stream()
|
||||
.map(SpringDocConfigProperties.GroupConfig::getPackagesToScan)
|
||||
.filter(toScan -> !CollectionUtils.isEmpty(toScan))
|
||||
.flatMap(List::stream)
|
||||
.collect(Collectors.toSet());
|
||||
if (CollectionUtils.isEmpty(packagesToScan)) {
|
||||
return;
|
||||
}
|
||||
// 扫描包下被 ApiSupport 注解的 RestController Class
|
||||
Set<Class<?>> classes = packagesToScan.stream()
|
||||
.map(packageToScan -> scanPackageByAnnotation(packageToScan, RestController.class))
|
||||
.flatMap(Set::stream)
|
||||
.filter(clazz -> clazz.isAnnotationPresent(ApiSupport.class))
|
||||
.collect(Collectors.toSet());
|
||||
if (!CollectionUtils.isEmpty(classes)) {
|
||||
// ApiSupport oder 值存入 tagSortMap<Tag.name,ApiSupport.order>
|
||||
Map<String, Integer> tagOrderMap = new HashMap<>();
|
||||
classes.forEach(clazz -> {
|
||||
Tag tag = getTag(clazz);
|
||||
if (Objects.nonNull(tag)) {
|
||||
ApiSupport apiSupport = clazz.getAnnotation(ApiSupport.class);
|
||||
tagOrderMap.putIfAbsent(tag.name(), apiSupport.order());
|
||||
}
|
||||
});
|
||||
// 往 openApi tags 字段添加 x-order 增强属性
|
||||
if (openApi.getTags() != null) {
|
||||
openApi.getTags().forEach(tag -> {
|
||||
if (tagOrderMap.containsKey(tag.getName())) {
|
||||
tag.addExtension(ExtensionsConstants.EXTENSION_ORDER, tagOrderMap.get(tag.getName()));
|
||||
}
|
||||
});
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
private Tag getTag(Class<?> clazz) {
|
||||
// 从类上获取
|
||||
Tag tag = clazz.getAnnotation(Tag.class);
|
||||
if (Objects.isNull(tag)) {
|
||||
// 从接口上获取
|
||||
Class<?>[] interfaces = clazz.getInterfaces();
|
||||
if (ArrayUtils.isNotEmpty(interfaces)) {
|
||||
for (Class<?> interfaceClazz : interfaces) {
|
||||
Tag anno = interfaceClazz.getAnnotation(Tag.class);
|
||||
if (Objects.nonNull(anno)) {
|
||||
tag = anno;
|
||||
break;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
return tag;
|
||||
}
|
||||
|
||||
private Set<Class<?>> scanPackageByAnnotation(String packageName, final Class<? extends Annotation> annotationClass) {
|
||||
ClassPathScanningCandidateComponentProvider scanner =
|
||||
new ClassPathScanningCandidateComponentProvider(false);
|
||||
scanner.addIncludeFilter(new AnnotationTypeFilter(annotationClass));
|
||||
Set<Class<?>> classes = new HashSet<>();
|
||||
for (BeanDefinition beanDefinition : scanner.findCandidateComponents(packageName)) {
|
||||
try {
|
||||
Class<?> clazz = Class.forName(beanDefinition.getBeanClassName());
|
||||
classes.add(clazz);
|
||||
} catch (ClassNotFoundException ignore) {
|
||||
}
|
||||
}
|
||||
return classes;
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,186 @@
|
||||
package com.njcn.rdms.framework.swagger.config;
|
||||
|
||||
import com.github.xiaoymin.knife4j.spring.configuration.Knife4jAutoConfiguration;
|
||||
import io.swagger.v3.oas.models.Components;
|
||||
import io.swagger.v3.oas.models.OpenAPI;
|
||||
import io.swagger.v3.oas.models.info.Contact;
|
||||
import io.swagger.v3.oas.models.info.Info;
|
||||
import io.swagger.v3.oas.models.info.License;
|
||||
import io.swagger.v3.oas.models.media.IntegerSchema;
|
||||
import io.swagger.v3.oas.models.media.StringSchema;
|
||||
import io.swagger.v3.oas.models.parameters.Parameter;
|
||||
import io.swagger.v3.oas.models.security.SecurityRequirement;
|
||||
import io.swagger.v3.oas.models.security.SecurityScheme;
|
||||
import org.springdoc.core.customizers.OpenApiBuilderCustomizer;
|
||||
import org.springdoc.core.customizers.OperationCustomizer;
|
||||
import org.springdoc.core.customizers.ServerBaseUrlCustomizer;
|
||||
import org.springdoc.core.models.GroupedOpenApi;
|
||||
import org.springdoc.core.properties.SpringDocConfigProperties;
|
||||
import org.springdoc.core.providers.JavadocProvider;
|
||||
import org.springdoc.core.service.OpenAPIService;
|
||||
import org.springdoc.core.service.SecurityService;
|
||||
import org.springdoc.core.utils.PropertyResolverUtils;
|
||||
import org.springframework.boot.autoconfigure.AutoConfiguration;
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
|
||||
import org.springframework.boot.context.properties.EnableConfigurationProperties;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
import org.springframework.context.annotation.Import;
|
||||
import org.springframework.context.annotation.Primary;
|
||||
import org.springframework.http.HttpHeaders;
|
||||
|
||||
import java.util.HashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Optional;
|
||||
|
||||
import static com.njcn.rdms.framework.web.core.util.WebFrameworkUtils.HEADER_TENANT_ID;
|
||||
|
||||
/**
|
||||
* Swagger 自动配置类，基于 OpenAPI + Springdoc 实现。
|
||||
*
|
||||
* 友情提示：
|
||||
* 1. Springdoc 文档地址：<a href="https://github.com/springdoc/springdoc-openapi">仓库</a>
|
||||
* 2. Swagger 规范，于 2015 更名为 OpenAPI 规范，本质是一个东西
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@AutoConfiguration(before = Knife4jAutoConfiguration.class) // before 原因，保证覆写的 Knife4jOpenApiCustomizer 先生效！相关 https://github.com/YunaiV/ruoyi-vue-pro/issues/954 讨论
|
||||
@ConditionalOnClass({OpenAPI.class})
|
||||
@EnableConfigurationProperties(SwaggerProperties.class)
|
||||
@ConditionalOnProperty(prefix = "springdoc.api-docs", name = "enabled", havingValue = "true", matchIfMissing = true) // 设置为 false 时，禁用
|
||||
@Import(Knife4jOpenApiCustomizer.class)
|
||||
public class RdmsSwaggerAutoConfiguration {
|
||||
|
||||
// ========== 全局 OpenAPI 配置 ==========
|
||||
|
||||
@Bean
|
||||
public OpenAPI createApi(SwaggerProperties properties) {
|
||||
Map<String, SecurityScheme> securitySchemas = buildSecuritySchemes();
|
||||
OpenAPI openAPI = new OpenAPI()
|
||||
// 接口信息
|
||||
.info(buildInfo(properties))
|
||||
// 接口安全配置
|
||||
.components(new Components().securitySchemes(securitySchemas))
|
||||
.addSecurityItem(new SecurityRequirement().addList(HttpHeaders.AUTHORIZATION));
|
||||
securitySchemas.keySet().forEach(key -> openAPI.addSecurityItem(new SecurityRequirement().addList(key)));
|
||||
return openAPI;
|
||||
}
|
||||
|
||||
/**
|
||||
* API 摘要信息
|
||||
*/
|
||||
private Info buildInfo(SwaggerProperties properties) {
|
||||
return new Info()
|
||||
.title(properties.getTitle())
|
||||
.description(properties.getDescription())
|
||||
.version(properties.getVersion())
|
||||
.contact(new Contact().name(properties.getAuthor()).url(properties.getUrl()).email(properties.getEmail()))
|
||||
.license(new License().name(properties.getLicense()).url(properties.getLicenseUrl()));
|
||||
}
|
||||
|
||||
/**
|
||||
* 安全模式，这里配置通过请求头 Authorization 传递 token 参数
|
||||
*/
|
||||
private Map<String, SecurityScheme> buildSecuritySchemes() {
|
||||
Map<String, SecurityScheme> securitySchemes = new HashMap<>();
|
||||
SecurityScheme securityScheme = new SecurityScheme()
|
||||
.type(SecurityScheme.Type.APIKEY) // 类型
|
||||
.name(HttpHeaders.AUTHORIZATION) // 请求头的 name
|
||||
.in(SecurityScheme.In.HEADER); // token 所在位置
|
||||
securitySchemes.put(HttpHeaders.AUTHORIZATION, securityScheme);
|
||||
return securitySchemes;
|
||||
}
|
||||
|
||||
/**
|
||||
* 自定义 OpenAPI 处理器
|
||||
*/
|
||||
@Bean
|
||||
@Primary // 目的：以我们创建的 OpenAPIService Bean 为主，避免一键改包后，启动报错！
|
||||
public OpenAPIService openApiBuilder(Optional<OpenAPI> openAPI,
|
||||
SecurityService securityParser,
|
||||
SpringDocConfigProperties springDocConfigProperties,
|
||||
PropertyResolverUtils propertyResolverUtils,
|
||||
Optional<List<OpenApiBuilderCustomizer>> openApiBuilderCustomizers,
|
||||
Optional<List<ServerBaseUrlCustomizer>> serverBaseUrlCustomizers,
|
||||
Optional<JavadocProvider> javadocProvider) {
|
||||
return new OpenAPIService(openAPI, securityParser, springDocConfigProperties,
|
||||
propertyResolverUtils, openApiBuilderCustomizers, serverBaseUrlCustomizers, javadocProvider);
|
||||
}
|
||||
|
||||
// ========== 分组 OpenAPI 配置 ==========
|
||||
|
||||
/**
|
||||
* 所有模块的 API 分组
|
||||
*/
|
||||
@Bean
|
||||
public GroupedOpenApi allGroupedOpenApi() {
|
||||
return buildGroupedOpenApi("all", "");
|
||||
}
|
||||
|
||||
public static GroupedOpenApi buildGroupedOpenApi(String group) {
|
||||
return buildGroupedOpenApi(group, group);
|
||||
}
|
||||
|
||||
public static GroupedOpenApi buildGroupedOpenApi(String group, String path) {
|
||||
return GroupedOpenApi.builder()
|
||||
.group(group)
|
||||
.pathsToMatch("/admin-api/" + path + "/**", "/app-api/" + path + "/**")
|
||||
.addOperationCustomizer((operation, handlerMethod) -> operation
|
||||
.addParametersItem(buildTenantHeaderParameter())
|
||||
.addParametersItem(buildSecurityHeaderParameter()))
|
||||
.addOperationCustomizer(buildOperationIdCustomizer())
|
||||
.build();
|
||||
}
|
||||
|
||||
/**
|
||||
* 构建 Tenant 租户编号请求头参数
|
||||
*
|
||||
* @return 多租户参数
|
||||
*/
|
||||
private static Parameter buildTenantHeaderParameter() {
|
||||
return new Parameter()
|
||||
.name(HEADER_TENANT_ID) // header 名
|
||||
.description("租户编号") // 描述
|
||||
.in(String.valueOf(SecurityScheme.In.HEADER)) // 请求 header
|
||||
.schema(new IntegerSchema()._default(1L).name(HEADER_TENANT_ID).description("租户编号")); // 默认：使用租户编号为 1
|
||||
}
|
||||
|
||||
/**
|
||||
* 构建 Authorization 认证请求头参数
|
||||
*
|
||||
* 解决 Knife4j <a href="https://gitee.com/xiaoym/knife4j/issues/I69QBU">Authorize 未生效，请求header里未包含参数</a>
|
||||
*
|
||||
* @return 认证参数
|
||||
*/
|
||||
private static Parameter buildSecurityHeaderParameter() {
|
||||
return new Parameter()
|
||||
.name(HttpHeaders.AUTHORIZATION) // header 名
|
||||
.description("认证 Token") // 描述
|
||||
.in(String.valueOf(SecurityScheme.In.HEADER)) // 请求 header
|
||||
.schema(new StringSchema()._default("Bearer test1").name(HEADER_TENANT_ID).description("认证 Token")); // 默认：使用用户编号为 1
|
||||
}
|
||||
|
||||
/**
|
||||
* 核心：自定义OperationId生成规则，组合「类名前缀 + 方法名」
|
||||
*
|
||||
* @see <a href="https://github.com/YunaiV/ruoyi-vue-pro/issues/957">app-api 前缀不生效，都是使用 admin-api</a>
|
||||
*/
|
||||
private static OperationCustomizer buildOperationIdCustomizer() {
|
||||
return (operation, handlerMethod) -> {
|
||||
// 1. 获取控制器类名（如 UserController）
|
||||
String className = handlerMethod.getBeanType().getSimpleName();
|
||||
// 2. 提取类名前缀（去除 Controller 后缀，如 UserController -> User）
|
||||
String classPrefix = className.replaceAll("Controller$", "");
|
||||
// 3. 获取方法名（如 list）
|
||||
String methodName = handlerMethod.getMethod().getName();
|
||||
// 4. 组合生成 operationId（如 User_list）
|
||||
String operationId = classPrefix + "_" + methodName;
|
||||
// 5. 设置自定义 operationId
|
||||
operation.setOperationId(operationId);
|
||||
return operation;
|
||||
};
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
package com.njcn.rdms.framework.swagger.config;
|
||||
|
||||
import jakarta.validation.constraints.NotEmpty;
|
||||
import lombok.Data;
|
||||
import org.springframework.boot.context.properties.ConfigurationProperties;
|
||||
|
||||
/**
|
||||
* Swagger 配置属性
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@ConfigurationProperties("rdms.swagger")
|
||||
@Data
|
||||
public class SwaggerProperties {
|
||||
|
||||
/**
|
||||
* 标题
|
||||
*/
|
||||
@NotEmpty(message = "标题不能为空")
|
||||
private String title;
|
||||
/**
|
||||
* 描述
|
||||
*/
|
||||
@NotEmpty(message = "描述不能为空")
|
||||
private String description;
|
||||
/**
|
||||
* 作者
|
||||
*/
|
||||
@NotEmpty(message = "作者不能为空")
|
||||
private String author;
|
||||
/**
|
||||
* 版本
|
||||
*/
|
||||
@NotEmpty(message = "版本不能为空")
|
||||
private String version;
|
||||
/**
|
||||
* url
|
||||
*/
|
||||
@NotEmpty(message = "扫描的 package 不能为空")
|
||||
private String url;
|
||||
/**
|
||||
* email
|
||||
*/
|
||||
@NotEmpty(message = "扫描的 email 不能为空")
|
||||
private String email;
|
||||
|
||||
/**
|
||||
* license
|
||||
*/
|
||||
@NotEmpty(message = "扫描的 license 不能为空")
|
||||
private String license;
|
||||
|
||||
/**
|
||||
* license-url
|
||||
*/
|
||||
@NotEmpty(message = "扫描的 license-url 不能为空")
|
||||
private String licenseUrl;
|
||||
|
||||
}
|
||||
@@ -0,0 +1,6 @@
|
||||
/**
|
||||
* 基于 Swagger + Knife4j 实现 API 接口文档
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
package com.njcn.rdms.framework.swagger;
|
||||
@@ -0,0 +1,163 @@
|
||||
package com.njcn.rdms.framework.web.config;
|
||||
|
||||
import cn.hutool.core.util.StrUtil;
|
||||
import com.google.common.collect.Maps;
|
||||
import com.njcn.rdms.framework.common.biz.infra.logger.ApiErrorLogCommonApi;
|
||||
import com.njcn.rdms.framework.common.enums.WebFilterOrderEnum;
|
||||
import com.njcn.rdms.framework.web.core.filter.CacheRequestBodyFilter;
|
||||
import com.njcn.rdms.framework.web.core.handler.GlobalExceptionHandler;
|
||||
import com.njcn.rdms.framework.web.core.handler.GlobalResponseBodyHandler;
|
||||
import com.njcn.rdms.framework.web.core.util.WebFrameworkUtils;
|
||||
import jakarta.servlet.Filter;
|
||||
import org.springframework.beans.factory.annotation.Value;
|
||||
import org.springframework.boot.autoconfigure.AutoConfiguration;
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
|
||||
import org.springframework.boot.autoconfigure.web.client.RestTemplateAutoConfiguration;
|
||||
import org.springframework.boot.autoconfigure.web.servlet.WebMvcRegistrations;
|
||||
import org.springframework.boot.context.properties.EnableConfigurationProperties;
|
||||
import org.springframework.boot.web.client.RestTemplateBuilder;
|
||||
import org.springframework.boot.web.servlet.FilterRegistrationBean;
|
||||
import org.springframework.cloud.client.loadbalancer.LoadBalanced;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
import org.springframework.context.annotation.Primary;
|
||||
import org.springframework.core.annotation.Order;
|
||||
import org.springframework.util.AntPathMatcher;
|
||||
import org.springframework.web.bind.annotation.RestController;
|
||||
import org.springframework.web.client.RestTemplate;
|
||||
import org.springframework.web.cors.CorsConfiguration;
|
||||
import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
|
||||
import org.springframework.web.filter.CorsFilter;
|
||||
import org.springframework.web.servlet.mvc.method.annotation.RequestMappingHandlerMapping;
|
||||
|
||||
import java.util.Map;
|
||||
import java.util.function.Predicate;
|
||||
|
||||
@AutoConfiguration(beforeName = {
|
||||
"com.fhs.trans.config.TransServiceConfig" // cloud 独有：避免一键改包后，RestTemplate 初始化的冲突。可见 https://t.zsxq.com/T4yj7 帖子
|
||||
})
|
||||
@EnableConfigurationProperties(WebProperties.class)
|
||||
public class RdmsWebAutoConfiguration {
|
||||
|
||||
/**
|
||||
* 应用名
|
||||
*/
|
||||
@Value("${spring.application.name}")
|
||||
private String applicationName;
|
||||
|
||||
@Bean
|
||||
public WebMvcRegistrations webMvcRegistrations(WebProperties webProperties) {
|
||||
return new WebMvcRegistrations() {
|
||||
|
||||
@Override
|
||||
public RequestMappingHandlerMapping getRequestMappingHandlerMapping() {
|
||||
RequestMappingHandlerMapping mapping = new RequestMappingHandlerMapping();
|
||||
// 实例化时就带上前缀
|
||||
mapping.setPathPrefixes(buildPathPrefixes(webProperties));
|
||||
return mapping;
|
||||
}
|
||||
|
||||
/**
|
||||
* 构建 prefix → 匹配条件的映射
|
||||
*/
|
||||
private Map<String, Predicate<Class<?>>> buildPathPrefixes(WebProperties webProperties) {
|
||||
AntPathMatcher antPathMatcher = new AntPathMatcher(".");
|
||||
Map<String, Predicate<Class<?>>> pathPrefixes = Maps.newLinkedHashMapWithExpectedSize(2);
|
||||
putPathPrefix(pathPrefixes, webProperties.getAdminApi(), antPathMatcher);
|
||||
putPathPrefix(pathPrefixes, webProperties.getAppApi(), antPathMatcher);
|
||||
return pathPrefixes;
|
||||
}
|
||||
|
||||
/**
|
||||
* 设置 API 前缀，仅仅匹配 controller 包下的
|
||||
*/
|
||||
private void putPathPrefix(Map<String, Predicate<Class<?>>> pathPrefixes, WebProperties.Api api, AntPathMatcher matcher) {
|
||||
if (api == null || StrUtil.isEmpty(api.getPrefix())) {
|
||||
return;
|
||||
}
|
||||
pathPrefixes.put(api.getPrefix(), // api 前缀
|
||||
clazz -> clazz.isAnnotationPresent(RestController.class)
|
||||
&& matcher.match(api.getController(), clazz.getPackage().getName()));
|
||||
}
|
||||
|
||||
};
|
||||
}
|
||||
|
||||
@Bean
|
||||
@SuppressWarnings("SpringJavaInjectionPointsAutowiringInspection")
|
||||
public GlobalExceptionHandler globalExceptionHandler(ApiErrorLogCommonApi apiErrorLogApi) {
|
||||
return new GlobalExceptionHandler(applicationName, apiErrorLogApi);
|
||||
}
|
||||
|
||||
@Bean
|
||||
public GlobalResponseBodyHandler globalResponseBodyHandler() {
|
||||
return new GlobalResponseBodyHandler();
|
||||
}
|
||||
|
||||
@Bean
|
||||
@SuppressWarnings("InstantiationOfUtilityClass")
|
||||
public WebFrameworkUtils webFrameworkUtils(WebProperties webProperties) {
|
||||
// 由于 WebFrameworkUtils 需要使用到 webProperties 属性，所以注册为一个 Bean
|
||||
return new WebFrameworkUtils(webProperties);
|
||||
}
|
||||
|
||||
// ========== Filter 相关 ==========
|
||||
|
||||
/**
|
||||
* 创建 CorsFilter Bean，解决跨域问题
|
||||
*/
|
||||
@Bean
|
||||
@Order(value = WebFilterOrderEnum.CORS_FILTER) // 特殊：修复因执行顺序影响到跨域配置不生效问题
|
||||
public FilterRegistrationBean<CorsFilter> corsFilterBean() {
|
||||
// 创建 CorsConfiguration 对象
|
||||
CorsConfiguration config = new CorsConfiguration();
|
||||
config.setAllowCredentials(true);
|
||||
config.addAllowedOriginPattern("*"); // 设置访问源地址
|
||||
config.addAllowedHeader("*"); // 设置访问源请求头
|
||||
config.addAllowedMethod("*"); // 设置访问源请求方法
|
||||
// 创建 UrlBasedCorsConfigurationSource 对象
|
||||
UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
|
||||
source.registerCorsConfiguration("/**", config); // 对接口配置跨域设置
|
||||
return createFilterBean(new CorsFilter(source), WebFilterOrderEnum.CORS_FILTER);
|
||||
}
|
||||
|
||||
/**
|
||||
* 创建 RequestBodyCacheFilter Bean，可重复读取请求内容
|
||||
*/
|
||||
@Bean
|
||||
public FilterRegistrationBean<CacheRequestBodyFilter> requestBodyCacheFilter() {
|
||||
return createFilterBean(new CacheRequestBodyFilter(), WebFilterOrderEnum.REQUEST_BODY_CACHE_FILTER);
|
||||
}
|
||||
|
||||
/**
|
||||
* 创建 DemoFilter Bean，演示模式
|
||||
*/
|
||||
public static <T extends Filter> FilterRegistrationBean<T> createFilterBean(T filter, Integer order) {
|
||||
FilterRegistrationBean<T> bean = new FilterRegistrationBean<>(filter);
|
||||
bean.setOrder(order);
|
||||
return bean;
|
||||
}
|
||||
|
||||
/**
|
||||
* 创建 RestTemplate 实例
|
||||
*
|
||||
* @param restTemplateBuilder {@link RestTemplateAutoConfiguration#restTemplateBuilder}
|
||||
*/
|
||||
@Bean
|
||||
@ConditionalOnMissingBean
|
||||
@Primary
|
||||
public RestTemplate restTemplate(RestTemplateBuilder restTemplateBuilder) {
|
||||
return restTemplateBuilder.build();
|
||||
}
|
||||
|
||||
/**
|
||||
* 创建 RestTemplate 实例（支持负载均衡）
|
||||
*
|
||||
* @param restTemplateBuilder {@link RestTemplateAutoConfiguration#restTemplateBuilder}
|
||||
*/
|
||||
@Bean
|
||||
@LoadBalanced
|
||||
public RestTemplate loadBalancedRestTemplate(RestTemplateBuilder restTemplateBuilder) {
|
||||
return restTemplateBuilder.build();
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,65 @@
|
||||
package com.njcn.rdms.framework.web.config;
|
||||
|
||||
import jakarta.validation.Valid;
|
||||
import jakarta.validation.constraints.NotEmpty;
|
||||
import jakarta.validation.constraints.NotNull;
|
||||
import lombok.AllArgsConstructor;
|
||||
import lombok.Data;
|
||||
import lombok.NoArgsConstructor;
|
||||
import org.springframework.boot.context.properties.ConfigurationProperties;
|
||||
import org.springframework.validation.annotation.Validated;
|
||||
import org.springframework.web.servlet.config.annotation.PathMatchConfigurer;
|
||||
|
||||
@ConfigurationProperties(prefix = "rdms.web")
|
||||
@Validated
|
||||
@Data
|
||||
public class WebProperties {
|
||||
|
||||
@NotNull(message = "APP API 不能为空")
|
||||
private Api appApi = new Api("/app-api", "**.controller.app.**");
|
||||
@NotNull(message = "Admin API 不能为空")
|
||||
private Api adminApi = new Api("/admin-api", "**.controller.admin.**");
|
||||
|
||||
@NotNull(message = "Admin UI 不能为空")
|
||||
private Ui adminUi;
|
||||
|
||||
@Data
|
||||
@AllArgsConstructor
|
||||
@NoArgsConstructor
|
||||
@Valid
|
||||
public static class Api {
|
||||
|
||||
/**
|
||||
* API 前缀，实现所有 Controller 提供的 RESTFul API 的统一前缀
|
||||
*
|
||||
*
|
||||
* 意义：通过该前缀，避免 Swagger、Actuator 意外通过 Nginx 暴露出来给外部，带来安全性问题
|
||||
* 这样，Nginx 只需要配置转发到 /api/* 的所有接口即可。
|
||||
*
|
||||
* @see RdmsWebAutoConfiguration#configurePathMatch(PathMatchConfigurer)
|
||||
*/
|
||||
@NotEmpty(message = "API 前缀不能为空")
|
||||
private String prefix;
|
||||
|
||||
/**
|
||||
* Controller 所在包的 Ant 路径规则
|
||||
*
|
||||
* 主要目的是，给该 Controller 设置指定的 {@link #prefix}
|
||||
*/
|
||||
@NotEmpty(message = "Controller 所在包不能为空")
|
||||
private String controller;
|
||||
|
||||
}
|
||||
|
||||
@Data
|
||||
@Valid
|
||||
public static class Ui {
|
||||
|
||||
/**
|
||||
* 访问地址
|
||||
*/
|
||||
private String url;
|
||||
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
package com.njcn.rdms.framework.web.core.filter;
|
||||
|
||||
import cn.hutool.core.util.StrUtil;
|
||||
import com.njcn.rdms.framework.web.config.WebProperties;
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import lombok.RequiredArgsConstructor;
|
||||
import org.springframework.web.filter.OncePerRequestFilter;
|
||||
|
||||
/**
|
||||
* 过滤 /admin-api、/app-api 等 API 请求的过滤器
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@RequiredArgsConstructor
|
||||
public abstract class ApiRequestFilter extends OncePerRequestFilter {
|
||||
|
||||
protected final WebProperties webProperties;
|
||||
|
||||
@Override
|
||||
protected boolean shouldNotFilter(HttpServletRequest request) {
|
||||
// 只过滤 API 请求的地址
|
||||
String apiUri = request.getRequestURI().substring(request.getContextPath().length());
|
||||
return !StrUtil.startWithAny(apiUri, webProperties.getAdminApi().getPrefix(), webProperties.getAppApi().getPrefix());
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,46 @@
|
||||
package com.njcn.rdms.framework.web.core.filter;
|
||||
|
||||
import cn.hutool.core.util.StrUtil;
|
||||
import com.njcn.rdms.framework.common.util.servlet.ServletUtils;
|
||||
import jakarta.servlet.FilterChain;
|
||||
import jakarta.servlet.ServletException;
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import jakarta.servlet.http.HttpServletResponse;
|
||||
import org.springframework.web.filter.OncePerRequestFilter;
|
||||
|
||||
import java.io.IOException;
|
||||
|
||||
/**
|
||||
* Request Body 缓存 Filter，实现它的可重复读取
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
public class CacheRequestBodyFilter extends OncePerRequestFilter {
|
||||
|
||||
/**
|
||||
* 需要排除的 URI
|
||||
*
|
||||
* 1. 排除 Spring Boot Admin 相关请求，避免客户端连接中断导致的异常。
|
||||
* 例如说：<a href="https://github.com/YunaiV/ruoyi-vue-pro/issues/795">795 ISSUE</a>
|
||||
*/
|
||||
private static final String[] IGNORE_URIS = {"/admin/", "/actuator/"};
|
||||
|
||||
@Override
|
||||
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
|
||||
throws IOException, ServletException {
|
||||
filterChain.doFilter(new CacheRequestBodyWrapper(request), response);
|
||||
}
|
||||
|
||||
@Override
|
||||
protected boolean shouldNotFilter(HttpServletRequest request) {
|
||||
// 1. 校验是否为排除的 URL
|
||||
String requestURI = request.getRequestURI();
|
||||
if (StrUtil.startWithAny(requestURI, IGNORE_URIS)) {
|
||||
return true;
|
||||
}
|
||||
|
||||
// 2. 只处理 json 请求内容
|
||||
return !ServletUtils.isJsonRequest(request);
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,77 @@
|
||||
package com.njcn.rdms.framework.web.core.filter;
|
||||
|
||||
import com.njcn.rdms.framework.common.util.servlet.ServletUtils;
|
||||
import jakarta.servlet.ReadListener;
|
||||
import jakarta.servlet.ServletInputStream;
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import jakarta.servlet.http.HttpServletRequestWrapper;
|
||||
|
||||
import java.io.BufferedReader;
|
||||
import java.io.ByteArrayInputStream;
|
||||
import java.io.InputStreamReader;
|
||||
|
||||
/**
|
||||
* Request Body 缓存 Wrapper
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
public class CacheRequestBodyWrapper extends HttpServletRequestWrapper {
|
||||
|
||||
/**
|
||||
* 缓存的内容
|
||||
*/
|
||||
private final byte[] body;
|
||||
|
||||
public CacheRequestBodyWrapper(HttpServletRequest request) {
|
||||
super(request);
|
||||
body = ServletUtils.getBodyBytes(request);
|
||||
}
|
||||
|
||||
@Override
|
||||
public BufferedReader getReader() {
|
||||
return new BufferedReader(new InputStreamReader(this.getInputStream()));
|
||||
}
|
||||
|
||||
@Override
|
||||
public int getContentLength() {
|
||||
return body.length;
|
||||
}
|
||||
|
||||
@Override
|
||||
public long getContentLengthLong() {
|
||||
return body.length;
|
||||
}
|
||||
|
||||
@Override
|
||||
public ServletInputStream getInputStream() {
|
||||
final ByteArrayInputStream inputStream = new ByteArrayInputStream(body);
|
||||
// 返回 ServletInputStream
|
||||
return new ServletInputStream() {
|
||||
|
||||
@Override
|
||||
public int read() {
|
||||
return inputStream.read();
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean isFinished() {
|
||||
return false;
|
||||
}
|
||||
|
||||
@Override
|
||||
public boolean isReady() {
|
||||
return false;
|
||||
}
|
||||
|
||||
@Override
|
||||
public void setReadListener(ReadListener readListener) {}
|
||||
|
||||
@Override
|
||||
public int available() {
|
||||
return body.length;
|
||||
}
|
||||
|
||||
};
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,399 @@
|
||||
package com.njcn.rdms.framework.web.core.handler;
|
||||
|
||||
import cn.hutool.core.collection.CollUtil;
|
||||
import cn.hutool.core.exceptions.ExceptionUtil;
|
||||
import cn.hutool.core.map.MapUtil;
|
||||
import cn.hutool.core.util.ObjUtil;
|
||||
import cn.hutool.core.util.StrUtil;
|
||||
import com.fasterxml.jackson.databind.exc.InvalidFormatException;
|
||||
import com.google.common.util.concurrent.UncheckedExecutionException;
|
||||
import com.njcn.rdms.framework.common.biz.infra.logger.ApiErrorLogCommonApi;
|
||||
import com.njcn.rdms.framework.common.biz.infra.logger.dto.ApiErrorLogCreateReqDTO;
|
||||
import com.njcn.rdms.framework.common.exception.ServiceException;
|
||||
import com.njcn.rdms.framework.common.exception.util.ServiceExceptionUtil;
|
||||
import com.njcn.rdms.framework.common.pojo.CommonResult;
|
||||
import com.njcn.rdms.framework.common.util.collection.SetUtils;
|
||||
import com.njcn.rdms.framework.common.util.json.JsonUtils;
|
||||
import com.njcn.rdms.framework.common.util.monitor.TracerUtils;
|
||||
import com.njcn.rdms.framework.common.util.servlet.ServletUtils;
|
||||
import com.njcn.rdms.framework.web.core.util.WebFrameworkUtils;
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import jakarta.validation.ConstraintViolation;
|
||||
import jakarta.validation.ConstraintViolationException;
|
||||
import jakarta.validation.ValidationException;
|
||||
import lombok.AllArgsConstructor;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.springframework.http.converter.HttpMessageNotReadableException;
|
||||
import org.springframework.security.access.AccessDeniedException;
|
||||
import org.springframework.util.Assert;
|
||||
import org.springframework.validation.BindException;
|
||||
import org.springframework.validation.FieldError;
|
||||
import org.springframework.validation.ObjectError;
|
||||
import org.springframework.web.HttpMediaTypeNotSupportedException;
|
||||
import org.springframework.web.HttpRequestMethodNotSupportedException;
|
||||
import org.springframework.web.bind.MethodArgumentNotValidException;
|
||||
import org.springframework.web.bind.MissingServletRequestParameterException;
|
||||
import org.springframework.web.bind.annotation.ExceptionHandler;
|
||||
import org.springframework.web.bind.annotation.RestControllerAdvice;
|
||||
import org.springframework.web.method.annotation.MethodArgumentTypeMismatchException;
|
||||
import org.springframework.web.multipart.MaxUploadSizeExceededException;
|
||||
import org.springframework.web.servlet.NoHandlerFoundException;
|
||||
import org.springframework.web.servlet.resource.NoResourceFoundException;
|
||||
|
||||
import java.time.LocalDateTime;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import java.util.Set;
|
||||
|
||||
import static com.njcn.rdms.framework.common.exception.enums.GlobalErrorCodeConstants.*;
|
||||
|
||||
/**
|
||||
* 全局异常处理器，将 Exception 翻译成 CommonResult + 对应的异常编号
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@RestControllerAdvice
|
||||
@AllArgsConstructor
|
||||
@Slf4j
|
||||
public class GlobalExceptionHandler {
|
||||
|
||||
/**
|
||||
* 忽略的 ServiceException 错误提示，避免打印过多 logger
|
||||
*/
|
||||
public static final Set<String> IGNORE_ERROR_MESSAGES = SetUtils.asSet("无效的刷新令牌");
|
||||
|
||||
@SuppressWarnings("SpringJavaInjectionPointsAutowiringInspection")
|
||||
private final String applicationName;
|
||||
|
||||
private final ApiErrorLogCommonApi apiErrorLogApi;
|
||||
|
||||
/**
|
||||
* 处理所有异常，主要是提供给 Filter 使用
|
||||
* 因为 Filter 不走 SpringMVC 的流程，但是我们又需要兜底处理异常，所以这里提供一个全量的异常处理过程，保持逻辑统一。
|
||||
*
|
||||
* @param request 请求
|
||||
* @param ex 异常
|
||||
* @return 通用返回
|
||||
*/
|
||||
public CommonResult<?> allExceptionHandler(HttpServletRequest request, Throwable ex) {
|
||||
if (ex instanceof MissingServletRequestParameterException) {
|
||||
return missingServletRequestParameterExceptionHandler((MissingServletRequestParameterException) ex);
|
||||
}
|
||||
if (ex instanceof MethodArgumentTypeMismatchException) {
|
||||
return methodArgumentTypeMismatchExceptionHandler((MethodArgumentTypeMismatchException) ex);
|
||||
}
|
||||
if (ex instanceof MethodArgumentNotValidException) {
|
||||
return methodArgumentNotValidExceptionExceptionHandler((MethodArgumentNotValidException) ex);
|
||||
}
|
||||
if (ex instanceof BindException) {
|
||||
return bindExceptionHandler((BindException) ex);
|
||||
}
|
||||
if (ex instanceof ConstraintViolationException) {
|
||||
return constraintViolationExceptionHandler((ConstraintViolationException) ex);
|
||||
}
|
||||
if (ex instanceof ValidationException) {
|
||||
return validationException((ValidationException) ex);
|
||||
}
|
||||
if (ex instanceof MaxUploadSizeExceededException) {
|
||||
return maxUploadSizeExceededExceptionHandler((MaxUploadSizeExceededException) ex);
|
||||
}
|
||||
if (ex instanceof NoHandlerFoundException) {
|
||||
return noHandlerFoundExceptionHandler((NoHandlerFoundException) ex);
|
||||
}
|
||||
if (ex instanceof NoResourceFoundException) {
|
||||
return noResourceFoundExceptionHandler(request, (NoResourceFoundException) ex);
|
||||
}
|
||||
if (ex instanceof HttpRequestMethodNotSupportedException) {
|
||||
return httpRequestMethodNotSupportedExceptionHandler((HttpRequestMethodNotSupportedException) ex);
|
||||
}
|
||||
if (ex instanceof HttpMediaTypeNotSupportedException) {
|
||||
return httpMediaTypeNotSupportedExceptionHandler((HttpMediaTypeNotSupportedException) ex);
|
||||
}
|
||||
if (ex instanceof ServiceException) {
|
||||
return serviceExceptionHandler((ServiceException) ex);
|
||||
}
|
||||
if (ex instanceof AccessDeniedException) {
|
||||
return accessDeniedExceptionHandler(request, (AccessDeniedException) ex);
|
||||
}
|
||||
return defaultExceptionHandler(request, ex);
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 SpringMVC 请求参数缺失
|
||||
*
|
||||
* 例如说，接口上设置了 @RequestParam("xx") 参数，结果并未传递 xx 参数
|
||||
*/
|
||||
@ExceptionHandler(value = MissingServletRequestParameterException.class)
|
||||
public CommonResult<?> missingServletRequestParameterExceptionHandler(MissingServletRequestParameterException ex) {
|
||||
log.warn("[missingServletRequestParameterExceptionHandler]", ex);
|
||||
return CommonResult.error(BAD_REQUEST.getCode(), String.format("请求参数缺失:%s", ex.getParameterName()));
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 SpringMVC 请求参数类型错误
|
||||
*
|
||||
* 例如说，接口上设置了 @RequestParam("xx") 参数为 Integer，结果传递 xx 参数类型为 String
|
||||
*/
|
||||
@ExceptionHandler(MethodArgumentTypeMismatchException.class)
|
||||
public CommonResult<?> methodArgumentTypeMismatchExceptionHandler(MethodArgumentTypeMismatchException ex) {
|
||||
log.warn("[methodArgumentTypeMismatchExceptionHandler]", ex);
|
||||
return CommonResult.error(BAD_REQUEST.getCode(), String.format("请求参数类型错误:%s", ex.getMessage()));
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 SpringMVC 参数校验不正确
|
||||
*/
|
||||
@ExceptionHandler(MethodArgumentNotValidException.class)
|
||||
public CommonResult<?> methodArgumentNotValidExceptionExceptionHandler(MethodArgumentNotValidException ex) {
|
||||
log.warn("[methodArgumentNotValidExceptionExceptionHandler]", ex);
|
||||
// 获取 errorMessage
|
||||
String errorMessage = null;
|
||||
FieldError fieldError = ex.getBindingResult().getFieldError();
|
||||
if (fieldError == null) {
|
||||
// 组合校验，参考自 https://t.zsxq.com/3HVTx
|
||||
List<ObjectError> allErrors = ex.getBindingResult().getAllErrors();
|
||||
if (CollUtil.isNotEmpty(allErrors)) {
|
||||
errorMessage = allErrors.get(0).getDefaultMessage();
|
||||
}
|
||||
} else {
|
||||
errorMessage = fieldError.getDefaultMessage();
|
||||
}
|
||||
// 转换 CommonResult
|
||||
if (StrUtil.isEmpty(errorMessage)) {
|
||||
return CommonResult.error(BAD_REQUEST);
|
||||
}
|
||||
return CommonResult.error(BAD_REQUEST.getCode(), String.format("请求参数不正确:%s", errorMessage));
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 SpringMVC 参数绑定不正确，本质上也是通过 Validator 校验
|
||||
*/
|
||||
@ExceptionHandler(BindException.class)
|
||||
public CommonResult<?> bindExceptionHandler(BindException ex) {
|
||||
log.warn("[handleBindException]", ex);
|
||||
FieldError fieldError = ex.getFieldError();
|
||||
assert fieldError != null; // 断言，避免告警
|
||||
return CommonResult.error(BAD_REQUEST.getCode(), String.format("请求参数不正确:%s", fieldError.getDefaultMessage()));
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 SpringMVC 请求参数类型错误
|
||||
*
|
||||
* 例如说，接口上设置了 @RequestBody 实体中 xx 属性类型为 Integer，结果传递 xx 参数类型为 String
|
||||
*/
|
||||
@ExceptionHandler(HttpMessageNotReadableException.class)
|
||||
@SuppressWarnings("PatternVariableCanBeUsed")
|
||||
public CommonResult<?> methodArgumentTypeInvalidFormatExceptionHandler(HttpMessageNotReadableException ex) {
|
||||
log.warn("[methodArgumentTypeInvalidFormatExceptionHandler]", ex);
|
||||
if (ex.getCause() instanceof InvalidFormatException) {
|
||||
InvalidFormatException invalidFormatException = (InvalidFormatException) ex.getCause();
|
||||
return CommonResult.error(BAD_REQUEST.getCode(), String.format("请求参数类型错误:%s", invalidFormatException.getValue()));
|
||||
}
|
||||
if (StrUtil.startWith(ex.getMessage(), "Required request body is missing")) {
|
||||
return CommonResult.error(BAD_REQUEST.getCode(), "请求参数类型错误: request body 缺失");
|
||||
}
|
||||
return defaultExceptionHandler(ServletUtils.getRequest(), ex);
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 Validator 校验不通过产生的异常
|
||||
*/
|
||||
@ExceptionHandler(value = ConstraintViolationException.class)
|
||||
public CommonResult<?> constraintViolationExceptionHandler(ConstraintViolationException ex) {
|
||||
log.warn("[constraintViolationExceptionHandler]", ex);
|
||||
ConstraintViolation<?> constraintViolation = ex.getConstraintViolations().iterator().next();
|
||||
return CommonResult.error(BAD_REQUEST.getCode(), String.format("请求参数不正确:%s", constraintViolation.getMessage()));
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 Dubbo Consumer 本地参数校验时，抛出的 ValidationException 异常
|
||||
*/
|
||||
@ExceptionHandler(value = ValidationException.class)
|
||||
public CommonResult<?> validationException(ValidationException ex) {
|
||||
log.warn("[constraintViolationExceptionHandler]", ex);
|
||||
// 无法拼接明细的错误信息，因为 Dubbo Consumer 抛出 ValidationException 异常时，是直接的字符串信息，且人类不可读
|
||||
return CommonResult.error(BAD_REQUEST);
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理上传文件过大异常
|
||||
*/
|
||||
@ExceptionHandler(MaxUploadSizeExceededException.class)
|
||||
public CommonResult<?> maxUploadSizeExceededExceptionHandler(MaxUploadSizeExceededException ex) {
|
||||
return CommonResult.error(BAD_REQUEST.getCode(), "上传文件过大，请调整后重试");
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 SpringMVC 请求地址不存在
|
||||
*
|
||||
* 注意，它需要设置如下两个配置项：
|
||||
* 1. spring.mvc.throw-exception-if-no-handler-found 为 true
|
||||
* 2. spring.mvc.static-path-pattern 为 /statics/**
|
||||
*/
|
||||
@ExceptionHandler(NoHandlerFoundException.class)
|
||||
public CommonResult<?> noHandlerFoundExceptionHandler(NoHandlerFoundException ex) {
|
||||
log.warn("[noHandlerFoundExceptionHandler]", ex);
|
||||
return CommonResult.error(NOT_FOUND.getCode(), String.format("请求地址不存在:%s", ex.getRequestURL()));
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 SpringMVC 请求地址不存在
|
||||
*/
|
||||
@ExceptionHandler(NoResourceFoundException.class)
|
||||
private CommonResult<?> noResourceFoundExceptionHandler(HttpServletRequest req, NoResourceFoundException ex) {
|
||||
log.warn("[noResourceFoundExceptionHandler]", ex);
|
||||
return CommonResult.error(NOT_FOUND.getCode(), String.format("请求地址不存在:%s", ex.getResourcePath()));
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 SpringMVC 请求方法不正确
|
||||
*
|
||||
* 例如说，A 接口的方法为 GET 方式，结果请求方法为 POST 方式，导致不匹配
|
||||
*/
|
||||
@ExceptionHandler(HttpRequestMethodNotSupportedException.class)
|
||||
public CommonResult<?> httpRequestMethodNotSupportedExceptionHandler(HttpRequestMethodNotSupportedException ex) {
|
||||
log.warn("[httpRequestMethodNotSupportedExceptionHandler]", ex);
|
||||
return CommonResult.error(METHOD_NOT_ALLOWED.getCode(), String.format("请求方法不正确:%s", ex.getMessage()));
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 SpringMVC 请求的 Content-Type 不正确
|
||||
*
|
||||
* 例如说，A 接口的 Content-Type 为 application/json，结果请求的 Content-Type 为 application/octet-stream，导致不匹配
|
||||
*/
|
||||
@ExceptionHandler(HttpMediaTypeNotSupportedException.class)
|
||||
public CommonResult<?> httpMediaTypeNotSupportedExceptionHandler(HttpMediaTypeNotSupportedException ex) {
|
||||
log.warn("[httpMediaTypeNotSupportedExceptionHandler]", ex);
|
||||
return CommonResult.error(BAD_REQUEST.getCode(), String.format("请求类型不正确:%s", ex.getMessage()));
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 Spring Security 权限不足的异常
|
||||
*
|
||||
* 来源是，使用 @PreAuthorize 注解，AOP 进行权限拦截
|
||||
*/
|
||||
@ExceptionHandler(value = AccessDeniedException.class)
|
||||
public CommonResult<?> accessDeniedExceptionHandler(HttpServletRequest req, AccessDeniedException ex) {
|
||||
log.warn("[accessDeniedExceptionHandler][userId({}) 无法访问 url({})]", WebFrameworkUtils.getLoginUserId(req),
|
||||
req.getRequestURL(), ex);
|
||||
return CommonResult.error(FORBIDDEN);
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 Guava UncheckedExecutionException
|
||||
*
|
||||
* 例如说，缓存加载报错，可见 <a href="https://t.zsxq.com/UszdH">https://t.zsxq.com/UszdH</a>
|
||||
*/
|
||||
@ExceptionHandler(value = UncheckedExecutionException.class)
|
||||
public CommonResult<?> uncheckedExecutionExceptionHandler(HttpServletRequest req, UncheckedExecutionException ex) {
|
||||
return allExceptionHandler(req, ex.getCause());
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理业务异常 ServiceException
|
||||
*
|
||||
* 例如说，商品库存不足，用户手机号已存在。
|
||||
*/
|
||||
@ExceptionHandler(value = ServiceException.class)
|
||||
public CommonResult<?> serviceExceptionHandler(ServiceException ex) {
|
||||
// 不包含的时候，才进行打印，避免 ex 堆栈过多
|
||||
if (!IGNORE_ERROR_MESSAGES.contains(ex.getMessage())) {
|
||||
// 即使打印，也只打印第一层 StackTraceElement，并且使用 warn 在控制台输出，更容易看到
|
||||
try {
|
||||
StackTraceElement[] stackTraces = ex.getStackTrace();
|
||||
for (StackTraceElement stackTrace : stackTraces) {
|
||||
if (ObjUtil.notEqual(stackTrace.getClassName(), ServiceExceptionUtil.class.getName())) {
|
||||
log.warn("[serviceExceptionHandler]\n\t{}", stackTrace);
|
||||
break;
|
||||
}
|
||||
}
|
||||
} catch (Exception ignored) {
|
||||
// 忽略日志，避免影响主流程
|
||||
}
|
||||
}
|
||||
return CommonResult.error(ex.getCode(), ex.getMessage());
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理系统异常，兜底处理所有的一切
|
||||
*/
|
||||
@ExceptionHandler(value = Exception.class)
|
||||
public CommonResult<?> defaultExceptionHandler(HttpServletRequest req, Throwable ex) {
|
||||
// 特殊：如果是 ServiceException 的异常，则直接返回
|
||||
// 例如说：https://gitee.com/zhijiantianya/rdms-cloud/issues/ICSSRM、https://gitee.com/zhijiantianya/rdms-cloud/issues/ICT6FM
|
||||
if (ex.getCause() != null && ex.getCause() instanceof ServiceException) {
|
||||
return serviceExceptionHandler((ServiceException) ex.getCause());
|
||||
}
|
||||
|
||||
// 情况一：处理表不存在的异常
|
||||
CommonResult<?> tableNotExistsResult = handleTableNotExists(ex);
|
||||
if (tableNotExistsResult != null) {
|
||||
return tableNotExistsResult;
|
||||
}
|
||||
|
||||
// 情况二：处理异常
|
||||
log.error("[defaultExceptionHandler]", ex);
|
||||
// 插入异常日志
|
||||
createExceptionLog(req, ex);
|
||||
// 返回 ERROR CommonResult
|
||||
return CommonResult.error(INTERNAL_SERVER_ERROR.getCode(), INTERNAL_SERVER_ERROR.getMsg());
|
||||
}
|
||||
|
||||
private void createExceptionLog(HttpServletRequest req, Throwable e) {
|
||||
// 插入错误日志
|
||||
ApiErrorLogCreateReqDTO errorLog = new ApiErrorLogCreateReqDTO();
|
||||
try {
|
||||
// 初始化 errorLog
|
||||
buildExceptionLog(errorLog, req, e);
|
||||
// 执行插入 errorLog
|
||||
apiErrorLogApi.createApiErrorLogAsync(errorLog);
|
||||
} catch (Throwable th) {
|
||||
log.error("[createExceptionLog][url({}) log({}) 发生异常]", req.getRequestURI(), JsonUtils.toJsonString(errorLog), th);
|
||||
}
|
||||
}
|
||||
|
||||
private void buildExceptionLog(ApiErrorLogCreateReqDTO errorLog, HttpServletRequest request, Throwable e) {
|
||||
// 处理用户信息
|
||||
errorLog.setUserId(WebFrameworkUtils.getLoginUserId(request));
|
||||
errorLog.setUserType(WebFrameworkUtils.getLoginUserType(request));
|
||||
// 设置异常字段
|
||||
errorLog.setExceptionName(e.getClass().getName());
|
||||
errorLog.setExceptionMessage(ExceptionUtil.getMessage(e));
|
||||
errorLog.setExceptionRootCauseMessage(ExceptionUtil.getRootCauseMessage(e));
|
||||
errorLog.setExceptionStackTrace(ExceptionUtil.stacktraceToString(e));
|
||||
StackTraceElement[] stackTraceElements = e.getStackTrace();
|
||||
Assert.notEmpty(stackTraceElements, "异常 stackTraceElements 不能为空");
|
||||
StackTraceElement stackTraceElement = stackTraceElements[0];
|
||||
errorLog.setExceptionClassName(stackTraceElement.getClassName());
|
||||
errorLog.setExceptionFileName(stackTraceElement.getFileName());
|
||||
errorLog.setExceptionMethodName(stackTraceElement.getMethodName());
|
||||
errorLog.setExceptionLineNumber(stackTraceElement.getLineNumber());
|
||||
// 设置其它字段
|
||||
errorLog.setTraceId(TracerUtils.getTraceId());
|
||||
errorLog.setApplicationName(applicationName);
|
||||
errorLog.setRequestUrl(request.getRequestURI());
|
||||
Map<String, Object> requestParams = MapUtil.<String, Object>builder()
|
||||
.put("query", ServletUtils.getParamMap(request))
|
||||
.put("body", ServletUtils.getBody(request)).build();
|
||||
errorLog.setRequestParams(JsonUtils.toJsonString(requestParams));
|
||||
errorLog.setRequestMethod(request.getMethod());
|
||||
errorLog.setUserAgent(ServletUtils.getUserAgent(request));
|
||||
errorLog.setUserIp(ServletUtils.getClientIP(request));
|
||||
errorLog.setExceptionTime(LocalDateTime.now());
|
||||
}
|
||||
|
||||
/**
|
||||
* 处理 Table 不存在的异常情况
|
||||
*
|
||||
* @param ex 异常
|
||||
* @return 如果是 Table 不存在的异常，则返回对应的 CommonResult
|
||||
*/
|
||||
private CommonResult<?> handleTableNotExists(Throwable ex) {
|
||||
String message = ExceptionUtil.getRootCauseMessage(ex);
|
||||
if (!message.contains("doesn't exist")) {
|
||||
return null;
|
||||
}
|
||||
return CommonResult.error(TABLE_NOT_EXISTS.getCode(), TABLE_NOT_EXISTS.getMsg());
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,45 @@
|
||||
package com.njcn.rdms.framework.web.core.handler;
|
||||
|
||||
import com.njcn.rdms.framework.common.pojo.CommonResult;
|
||||
import com.njcn.rdms.framework.web.core.util.WebFrameworkUtils;
|
||||
import org.springframework.core.MethodParameter;
|
||||
import org.springframework.http.MediaType;
|
||||
import org.springframework.http.server.ServerHttpRequest;
|
||||
import org.springframework.http.server.ServerHttpResponse;
|
||||
import org.springframework.http.server.ServletServerHttpRequest;
|
||||
import org.springframework.web.bind.annotation.ControllerAdvice;
|
||||
import org.springframework.web.servlet.mvc.method.annotation.ResponseBodyAdvice;
|
||||
|
||||
/**
|
||||
* 全局响应结果（ResponseBody）处理器
|
||||
*
|
||||
* 不同于在网上看到的很多文章，会选择自动将 Controller 返回结果包上 {@link CommonResult}，
|
||||
* 在 onemall 中，是 Controller 在返回时，主动自己包上 {@link CommonResult}。
|
||||
* 原因是，GlobalResponseBodyHandler 本质上是 AOP，它不应该改变 Controller 返回的数据结构
|
||||
*
|
||||
* 目前，GlobalResponseBodyHandler 的主要作用是，记录 Controller 的返回结果，
|
||||
* 方便 {@link com.njcn.rdms.framework.apilog.core.filter.ApiAccessLogFilter} 记录访问日志
|
||||
*/
|
||||
@ControllerAdvice
|
||||
public class GlobalResponseBodyHandler implements ResponseBodyAdvice {
|
||||
|
||||
@Override
|
||||
@SuppressWarnings("NullableProblems") // 避免 IDEA 警告
|
||||
public boolean supports(MethodParameter returnType, Class converterType) {
|
||||
if (returnType.getMethod() == null) {
|
||||
return false;
|
||||
}
|
||||
// 只拦截返回结果为 CommonResult 类型
|
||||
return returnType.getMethod().getReturnType() == CommonResult.class;
|
||||
}
|
||||
|
||||
@Override
|
||||
@SuppressWarnings("NullableProblems") // 避免 IDEA 警告
|
||||
public Object beforeBodyWrite(Object body, MethodParameter returnType, MediaType selectedContentType, Class selectedConverterType,
|
||||
ServerHttpRequest request, ServerHttpResponse response) {
|
||||
// 记录 Controller 结果
|
||||
WebFrameworkUtils.setCommonResult(((ServletServerHttpRequest) request).getServletRequest(), (CommonResult<?>) body);
|
||||
return body;
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,180 @@
|
||||
package com.njcn.rdms.framework.web.core.util;
|
||||
|
||||
import cn.hutool.core.util.NumberUtil;
|
||||
import com.njcn.rdms.framework.common.enums.RpcConstants;
|
||||
import com.njcn.rdms.framework.common.enums.TerminalEnum;
|
||||
import com.njcn.rdms.framework.common.enums.UserTypeEnum;
|
||||
import com.njcn.rdms.framework.common.pojo.CommonResult;
|
||||
import com.njcn.rdms.framework.web.config.WebProperties;
|
||||
import jakarta.servlet.ServletRequest;
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import org.springframework.web.context.request.RequestAttributes;
|
||||
import org.springframework.web.context.request.RequestContextHolder;
|
||||
import org.springframework.web.context.request.ServletRequestAttributes;
|
||||
|
||||
/**
|
||||
* 专属于 web 包的工具类
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
public class WebFrameworkUtils {
|
||||
|
||||
private static final String REQUEST_ATTRIBUTE_LOGIN_USER_ID = "login_user_id";
|
||||
private static final String REQUEST_ATTRIBUTE_LOGIN_USER_TYPE = "login_user_type";
|
||||
|
||||
private static final String REQUEST_ATTRIBUTE_COMMON_RESULT = "common_result";
|
||||
|
||||
public static final String HEADER_TENANT_ID = "tenant-id";
|
||||
public static final String HEADER_VISIT_TENANT_ID = "visit-tenant-id";
|
||||
|
||||
/**
|
||||
* 终端的 Header
|
||||
*
|
||||
* @see TerminalEnum
|
||||
*/
|
||||
public static final String HEADER_TERMINAL = "terminal";
|
||||
|
||||
private static WebProperties properties;
|
||||
|
||||
public WebFrameworkUtils(WebProperties webProperties) {
|
||||
WebFrameworkUtils.properties = webProperties;
|
||||
}
|
||||
|
||||
/**
|
||||
* 获得租户编号，从 header 中
|
||||
* 考虑到其它 framework 组件也会使用到租户编号，所以不得不放在 WebFrameworkUtils 统一提供
|
||||
*
|
||||
* @param request 请求
|
||||
* @return 租户编号
|
||||
*/
|
||||
public static Long getTenantId(HttpServletRequest request) {
|
||||
String tenantId = request.getHeader(HEADER_TENANT_ID);
|
||||
return NumberUtil.isNumber(tenantId) ? Long.valueOf(tenantId) : null;
|
||||
}
|
||||
|
||||
/**
|
||||
* 获得访问的租户编号，从 header 中
|
||||
* 考虑到其它 framework 组件也会使用到租户编号，所以不得不放在 WebFrameworkUtils 统一提供
|
||||
*
|
||||
* @param request 请求
|
||||
* @return 租户编号
|
||||
*/
|
||||
public static Long getVisitTenantId(HttpServletRequest request) {
|
||||
String tenantId = request.getHeader(HEADER_VISIT_TENANT_ID);
|
||||
return NumberUtil.isNumber(tenantId)? Long.valueOf(tenantId) : null;
|
||||
}
|
||||
|
||||
public static void setLoginUserId(ServletRequest request, Long userId) {
|
||||
request.setAttribute(REQUEST_ATTRIBUTE_LOGIN_USER_ID, userId);
|
||||
}
|
||||
|
||||
/**
|
||||
* 设置用户类型
|
||||
*
|
||||
* @param request 请求
|
||||
* @param userType 用户类型
|
||||
*/
|
||||
public static void setLoginUserType(ServletRequest request, Integer userType) {
|
||||
request.setAttribute(REQUEST_ATTRIBUTE_LOGIN_USER_TYPE, userType);
|
||||
}
|
||||
|
||||
/**
|
||||
* 获得当前用户的编号，从请求中
|
||||
* 注意：该方法仅限于 framework 框架使用！！！
|
||||
*
|
||||
* @param request 请求
|
||||
* @return 用户编号
|
||||
*/
|
||||
public static Long getLoginUserId(HttpServletRequest request) {
|
||||
if (request == null) {
|
||||
return null;
|
||||
}
|
||||
return (Long) request.getAttribute(REQUEST_ATTRIBUTE_LOGIN_USER_ID);
|
||||
}
|
||||
|
||||
/**
|
||||
* 获得当前用户的类型
|
||||
* 注意：该方法仅限于 web 相关的 framework 组件使用！！！
|
||||
*
|
||||
* @param request 请求
|
||||
* @return 用户编号
|
||||
*/
|
||||
public static Integer getLoginUserType(HttpServletRequest request) {
|
||||
if (request == null) {
|
||||
return null;
|
||||
}
|
||||
// 1. 优先，从 Attribute 中获取
|
||||
Integer userType = (Integer) request.getAttribute(REQUEST_ATTRIBUTE_LOGIN_USER_TYPE);
|
||||
if (userType != null) {
|
||||
return userType;
|
||||
}
|
||||
// 2. 其次，基于 URL 前缀的约定
|
||||
if (request.getServletPath().startsWith(properties.getAdminApi().getPrefix())) {
|
||||
return UserTypeEnum.ADMIN.getValue();
|
||||
}
|
||||
if (request.getServletPath().startsWith(properties.getAppApi().getPrefix())) {
|
||||
return UserTypeEnum.MEMBER.getValue();
|
||||
}
|
||||
return null;
|
||||
}
|
||||
|
||||
public static Integer getLoginUserType() {
|
||||
HttpServletRequest request = getRequest();
|
||||
return getLoginUserType(request);
|
||||
}
|
||||
|
||||
public static Long getLoginUserId() {
|
||||
HttpServletRequest request = getRequest();
|
||||
return getLoginUserId(request);
|
||||
}
|
||||
|
||||
public static Integer getTerminal() {
|
||||
HttpServletRequest request = getRequest();
|
||||
if (request == null) {
|
||||
return TerminalEnum.UNKNOWN.getTerminal();
|
||||
}
|
||||
String terminalValue = request.getHeader(HEADER_TERMINAL);
|
||||
return NumberUtil.parseInt(terminalValue, TerminalEnum.UNKNOWN.getTerminal());
|
||||
}
|
||||
|
||||
public static void setCommonResult(ServletRequest request, CommonResult<?> result) {
|
||||
request.setAttribute(REQUEST_ATTRIBUTE_COMMON_RESULT, result);
|
||||
}
|
||||
|
||||
public static CommonResult<?> getCommonResult(ServletRequest request) {
|
||||
return (CommonResult<?>) request.getAttribute(REQUEST_ATTRIBUTE_COMMON_RESULT);
|
||||
}
|
||||
|
||||
@SuppressWarnings("PatternVariableCanBeUsed")
|
||||
public static HttpServletRequest getRequest() {
|
||||
RequestAttributes requestAttributes = RequestContextHolder.getRequestAttributes();
|
||||
if (!(requestAttributes instanceof ServletRequestAttributes)) {
|
||||
return null;
|
||||
}
|
||||
ServletRequestAttributes servletRequestAttributes = (ServletRequestAttributes) requestAttributes;
|
||||
return servletRequestAttributes.getRequest();
|
||||
}
|
||||
|
||||
/**
|
||||
* 判断是否为 RPC 请求
|
||||
*
|
||||
* @param request 请求
|
||||
* @return 是否为 RPC 请求
|
||||
*/
|
||||
public static boolean isRpcRequest(HttpServletRequest request) {
|
||||
return request.getRequestURI().startsWith(RpcConstants.RPC_API_PREFIX);
|
||||
}
|
||||
|
||||
/**
|
||||
* 判断是否为 RPC 请求
|
||||
*
|
||||
* 约定大于配置，只要以 Api 结尾，都认为是 RPC 接口
|
||||
*
|
||||
* @param className 类名
|
||||
* @return 是否为 RPC 请求
|
||||
*/
|
||||
public static boolean isRpcRequest(String className) {
|
||||
return className.endsWith("Api");
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,4 @@
|
||||
/**
|
||||
* 针对 SpringMVC 的基础封装
|
||||
*/
|
||||
package com.njcn.rdms.framework.web;
|
||||
@@ -0,0 +1,62 @@
|
||||
package com.njcn.rdms.framework.xss.config;
|
||||
|
||||
import com.njcn.rdms.framework.common.enums.WebFilterOrderEnum;
|
||||
import com.njcn.rdms.framework.xss.core.clean.JsoupXssCleaner;
|
||||
import com.njcn.rdms.framework.xss.core.clean.XssCleaner;
|
||||
import com.njcn.rdms.framework.xss.core.filter.XssFilter;
|
||||
import com.njcn.rdms.framework.xss.core.json.XssStringJsonDeserializer;
|
||||
import org.springframework.boot.autoconfigure.AutoConfiguration;
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnBean;
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
|
||||
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
|
||||
import org.springframework.boot.autoconfigure.jackson.Jackson2ObjectMapperBuilderCustomizer;
|
||||
import org.springframework.boot.context.properties.EnableConfigurationProperties;
|
||||
import org.springframework.boot.web.servlet.FilterRegistrationBean;
|
||||
import org.springframework.context.annotation.Bean;
|
||||
import org.springframework.util.PathMatcher;
|
||||
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
|
||||
|
||||
import static com.njcn.rdms.framework.web.config.RdmsWebAutoConfiguration.createFilterBean;
|
||||
|
||||
@AutoConfiguration
|
||||
@EnableConfigurationProperties(XssProperties.class)
|
||||
@ConditionalOnProperty(prefix = "rdms.xss", name = "enable", havingValue = "true", matchIfMissing = true) // 设置为 false 时，禁用
|
||||
public class RdmsXssAutoConfiguration implements WebMvcConfigurer {
|
||||
|
||||
/**
|
||||
* Xss 清理者
|
||||
*
|
||||
* @return XssCleaner
|
||||
*/
|
||||
@Bean
|
||||
@ConditionalOnMissingBean(XssCleaner.class)
|
||||
public XssCleaner xssCleaner() {
|
||||
return new JsoupXssCleaner();
|
||||
}
|
||||
|
||||
/**
|
||||
* 注册 Jackson 的序列化器，用于处理 json 类型参数的 xss 过滤
|
||||
*
|
||||
* @return Jackson2ObjectMapperBuilderCustomizer
|
||||
*/
|
||||
@Bean
|
||||
@ConditionalOnMissingBean(name = "xssJacksonCustomizer")
|
||||
@ConditionalOnProperty(value = "rdms.xss.enable", havingValue = "true")
|
||||
public Jackson2ObjectMapperBuilderCustomizer xssJacksonCustomizer(XssProperties properties,
|
||||
PathMatcher pathMatcher,
|
||||
XssCleaner xssCleaner) {
|
||||
// 在反序列化时进行 xss 过滤，可以替换使用 XssStringJsonSerializer，在序列化时进行处理
|
||||
return builder ->
|
||||
builder.deserializerByType(String.class, new XssStringJsonDeserializer(properties, pathMatcher, xssCleaner));
|
||||
}
|
||||
|
||||
/**
|
||||
* 创建 XssFilter Bean，解决 Xss 安全问题
|
||||
*/
|
||||
@Bean
|
||||
@ConditionalOnBean(XssCleaner.class)
|
||||
public FilterRegistrationBean<XssFilter> xssFilter(XssProperties properties, PathMatcher pathMatcher, XssCleaner xssCleaner) {
|
||||
return createFilterBean(new XssFilter(properties, pathMatcher, xssCleaner), WebFilterOrderEnum.XSS_FILTER);
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,29 @@
|
||||
package com.njcn.rdms.framework.xss.config;
|
||||
|
||||
import lombok.Data;
|
||||
import org.springframework.boot.context.properties.ConfigurationProperties;
|
||||
import org.springframework.validation.annotation.Validated;
|
||||
|
||||
import java.util.Collections;
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* Xss 配置属性
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@ConfigurationProperties(prefix = "rdms.xss")
|
||||
@Validated
|
||||
@Data
|
||||
public class XssProperties {
|
||||
|
||||
/**
|
||||
* 是否开启，默认为 true
|
||||
*/
|
||||
private boolean enable = true;
|
||||
/**
|
||||
* 需要排除的 URL，默认为空
|
||||
*/
|
||||
private List<String> excludeUrls = Collections.emptyList();
|
||||
|
||||
}
|
||||
@@ -0,0 +1,64 @@
|
||||
package com.njcn.rdms.framework.xss.core.clean;
|
||||
|
||||
import org.jsoup.Jsoup;
|
||||
import org.jsoup.nodes.Document;
|
||||
import org.jsoup.safety.Safelist;
|
||||
|
||||
/**
|
||||
* 基于 JSONP 实现 XSS 过滤字符串
|
||||
*/
|
||||
public class JsoupXssCleaner implements XssCleaner {
|
||||
|
||||
private final Safelist safelist;
|
||||
|
||||
/**
|
||||
* 用于在 src 属性使用相对路径时，强制转换为绝对路径。 为空时不处理，值应为绝对路径的前缀（包含协议部分）
|
||||
*/
|
||||
private final String baseUri;
|
||||
|
||||
/**
|
||||
* 无参构造，默认使用 {@link JsoupXssCleaner#buildSafelist} 方法构建一个安全列表
|
||||
*/
|
||||
public JsoupXssCleaner() {
|
||||
this.safelist = buildSafelist();
|
||||
this.baseUri = "";
|
||||
}
|
||||
|
||||
/**
|
||||
* 构建一个 Xss 清理的 Safelist 规则。
|
||||
* 基于 Safelist#relaxed() 的基础上:
|
||||
* 1. 扩展支持了 style 和 class 属性
|
||||
* 2. a 标签额外支持了 target 属性
|
||||
* 3. img 标签额外支持了 data 协议，便于支持 base64
|
||||
*
|
||||
* @return Safelist
|
||||
*/
|
||||
private Safelist buildSafelist() {
|
||||
// 使用 jsoup 提供的默认的
|
||||
Safelist relaxedSafelist = Safelist.relaxed();
|
||||
// 富文本编辑时一些样式是使用 style 来进行实现的
|
||||
// 比如红色字体 style="color:red;", 所以需要给所有标签添加 style 属性
|
||||
// 注意：style 属性会有注入风险 <img STYLE="background-image:url(javascript:alert('XSS'))">
|
||||
relaxedSafelist.addAttributes(":all", "style", "class");
|
||||
// 保留 a 标签的 target 属性
|
||||
relaxedSafelist.addAttributes("a", "target");
|
||||
// 支持img 为base64
|
||||
relaxedSafelist.addProtocols("img", "src", "data");
|
||||
|
||||
// 保留相对路径, 保留相对路径时，必须提供对应的 baseUri 属性，否则依然会被删除
|
||||
// WHITELIST.preserveRelativeLinks(false);
|
||||
|
||||
// 移除 a 标签和 img 标签的一些协议限制，这会导致 xss 防注入失效，如 <img src=javascript:alert("xss")>
|
||||
// 虽然可以重写 WhiteList#isSafeAttribute 来处理，但是有隐患，所以暂时不支持相对路径
|
||||
// WHITELIST.removeProtocols("a", "href", "ftp", "http", "https", "mailto");
|
||||
// WHITELIST.removeProtocols("img", "src", "http", "https");
|
||||
return relaxedSafelist;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String clean(String html) {
|
||||
return Jsoup.clean(html, baseUri, safelist, new Document.OutputSettings().prettyPrint(false));
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
package com.njcn.rdms.framework.xss.core.clean;
|
||||
|
||||
/**
|
||||
* 对 html 文本中的有 Xss 风险的数据进行清理
|
||||
*/
|
||||
public interface XssCleaner {
|
||||
|
||||
/**
|
||||
* 清理有 Xss 风险的文本
|
||||
*
|
||||
* @param html 原 html
|
||||
* @return 清理后的 html
|
||||
*/
|
||||
String clean(String html);
|
||||
|
||||
}
|
||||
@@ -0,0 +1,52 @@
|
||||
package com.njcn.rdms.framework.xss.core.filter;
|
||||
|
||||
import com.njcn.rdms.framework.xss.config.XssProperties;
|
||||
import com.njcn.rdms.framework.xss.core.clean.XssCleaner;
|
||||
import jakarta.servlet.FilterChain;
|
||||
import jakarta.servlet.ServletException;
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import jakarta.servlet.http.HttpServletResponse;
|
||||
import lombok.AllArgsConstructor;
|
||||
import org.springframework.util.PathMatcher;
|
||||
import org.springframework.web.filter.OncePerRequestFilter;
|
||||
|
||||
import java.io.IOException;
|
||||
|
||||
/**
|
||||
* Xss 过滤器
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
@AllArgsConstructor
|
||||
public class XssFilter extends OncePerRequestFilter {
|
||||
|
||||
/**
|
||||
* 属性
|
||||
*/
|
||||
private final XssProperties properties;
|
||||
/**
|
||||
* 路径匹配器
|
||||
*/
|
||||
private final PathMatcher pathMatcher;
|
||||
|
||||
private final XssCleaner xssCleaner;
|
||||
|
||||
@Override
|
||||
protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain)
|
||||
throws IOException, ServletException {
|
||||
filterChain.doFilter(new XssRequestWrapper(request, xssCleaner), response);
|
||||
}
|
||||
|
||||
@Override
|
||||
protected boolean shouldNotFilter(HttpServletRequest request) {
|
||||
// 如果关闭，则不过滤
|
||||
if (!properties.isEnable()) {
|
||||
return true;
|
||||
}
|
||||
|
||||
// 如果匹配到无需过滤，则不过滤
|
||||
String uri = request.getRequestURI();
|
||||
return properties.getExcludeUrls().stream().anyMatch(excludeUrl -> pathMatcher.match(excludeUrl, uri));
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,92 @@
|
||||
package com.njcn.rdms.framework.xss.core.filter;
|
||||
|
||||
import com.njcn.rdms.framework.xss.core.clean.XssCleaner;
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import jakarta.servlet.http.HttpServletRequestWrapper;
|
||||
|
||||
import java.util.LinkedHashMap;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* Xss 请求 Wrapper
|
||||
*
|
||||
* @author hongawen
|
||||
*/
|
||||
public class XssRequestWrapper extends HttpServletRequestWrapper {
|
||||
|
||||
private final XssCleaner xssCleaner;
|
||||
|
||||
public XssRequestWrapper(HttpServletRequest request, XssCleaner xssCleaner) {
|
||||
super(request);
|
||||
this.xssCleaner = xssCleaner;
|
||||
}
|
||||
|
||||
// ============================ parameter ============================
|
||||
@Override
|
||||
public Map<String, String[]> getParameterMap() {
|
||||
Map<String, String[]> map = new LinkedHashMap<>();
|
||||
Map<String, String[]> parameters = super.getParameterMap();
|
||||
for (Map.Entry<String, String[]> entry : parameters.entrySet()) {
|
||||
String[] values = entry.getValue();
|
||||
for (int i = 0; i < values.length; i++) {
|
||||
values[i] = xssCleaner.clean(values[i]);
|
||||
}
|
||||
map.put(entry.getKey(), values);
|
||||
}
|
||||
return map;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String[] getParameterValues(String name) {
|
||||
String[] values = super.getParameterValues(name);
|
||||
if (values == null) {
|
||||
return null;
|
||||
}
|
||||
int count = values.length;
|
||||
String[] encodedValues = new String[count];
|
||||
for (int i = 0; i < count; i++) {
|
||||
encodedValues[i] = xssCleaner.clean(values[i]);
|
||||
}
|
||||
return encodedValues;
|
||||
}
|
||||
|
||||
@Override
|
||||
public String getParameter(String name) {
|
||||
String value = super.getParameter(name);
|
||||
if (value == null) {
|
||||
return null;
|
||||
}
|
||||
return xssCleaner.clean(value);
|
||||
}
|
||||
|
||||
// ============================ attribute ============================
|
||||
@Override
|
||||
public Object getAttribute(String name) {
|
||||
Object value = super.getAttribute(name);
|
||||
if (value instanceof String) {
|
||||
return xssCleaner.clean((String) value);
|
||||
}
|
||||
return value;
|
||||
}
|
||||
|
||||
// ============================ header ============================
|
||||
@Override
|
||||
public String getHeader(String name) {
|
||||
String value = super.getHeader(name);
|
||||
if (value == null) {
|
||||
return null;
|
||||
}
|
||||
return xssCleaner.clean(value);
|
||||
}
|
||||
|
||||
// ============================ queryString ============================
|
||||
@Override
|
||||
public String getQueryString() {
|
||||
String value = super.getQueryString();
|
||||
if (value == null) {
|
||||
return null;
|
||||
}
|
||||
return xssCleaner.clean(value);
|
||||
}
|
||||
|
||||
}
|
||||
@@ -0,0 +1,82 @@
|
||||
package com.njcn.rdms.framework.xss.core.json;
|
||||
|
||||
import com.fasterxml.jackson.core.JsonParser;
|
||||
import com.fasterxml.jackson.core.JsonToken;
|
||||
import com.fasterxml.jackson.databind.DeserializationContext;
|
||||
import com.fasterxml.jackson.databind.deser.std.StringDeserializer;
|
||||
import com.njcn.rdms.framework.common.util.servlet.ServletUtils;
|
||||
import com.njcn.rdms.framework.xss.config.XssProperties;
|
||||
import com.njcn.rdms.framework.xss.core.clean.XssCleaner;
|
||||
import jakarta.servlet.http.HttpServletRequest;
|
||||
import lombok.AllArgsConstructor;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.springframework.util.PathMatcher;
|
||||
|
||||
import java.io.IOException;
|
||||
|
||||
/**
|
||||
* XSS 过滤 jackson 反序列化器。
|
||||
* 在反序列化的过程中，会对字符串进行 XSS 过滤。
|
||||
*
|
||||
* @author Hccake
|
||||
*/
|
||||
@Slf4j
|
||||
@AllArgsConstructor
|
||||
public class XssStringJsonDeserializer extends StringDeserializer {
|
||||
|
||||
/**
|
||||
* 属性
|
||||
*/
|
||||
private final XssProperties properties;
|
||||
/**
|
||||
* 路径匹配器
|
||||
*/
|
||||
private final PathMatcher pathMatcher;
|
||||
|
||||
private final XssCleaner xssCleaner;
|
||||
|
||||
@Override
|
||||
public String deserialize(JsonParser p, DeserializationContext ctxt) throws IOException {
|
||||
// 1. 白名单 URL 的处理
|
||||
HttpServletRequest request = ServletUtils.getRequest();
|
||||
if (request != null) {
|
||||
String uri = ServletUtils.getRequest().getRequestURI();
|
||||
if (properties.getExcludeUrls().stream().anyMatch(excludeUrl -> pathMatcher.match(excludeUrl, uri))) {
|
||||
return p.getText();
|
||||
}
|
||||
}
|
||||
|
||||
// 2. 真正使用 xssCleaner 进行过滤
|
||||
if (p.hasToken(JsonToken.VALUE_STRING)) {
|
||||
return xssCleaner.clean(p.getText());
|
||||
}
|
||||
JsonToken t = p.currentToken();
|
||||
// [databind#381]
|
||||
if (t == JsonToken.START_ARRAY) {
|
||||
return _deserializeFromArray(p, ctxt);
|
||||
}
|
||||
// need to gracefully handle byte[] data, as base64
|
||||
if (t == JsonToken.VALUE_EMBEDDED_OBJECT) {
|
||||
Object ob = p.getEmbeddedObject();
|
||||
if (ob == null) {
|
||||
return null;
|
||||
}
|
||||
if (ob instanceof byte[]) {
|
||||
return ctxt.getBase64Variant().encode((byte[]) ob, false);
|
||||
}
|
||||
// otherwise, try conversion using toString()...
|
||||
return ob.toString();
|
||||
}
|
||||
// 29-Jun-2020, tatu: New! "Scalar from Object" (mostly for XML)
|
||||
if (t == JsonToken.START_OBJECT) {
|
||||
return ctxt.extractScalarFromObject(p, this, _valueClass);
|
||||
}
|
||||
|
||||
if (t.isScalarValue()) {
|
||||
String text = p.getValueAsString();
|
||||
return xssCleaner.clean(text);
|
||||
}
|
||||
return (String) ctxt.handleUnexpectedToken(_valueClass, p);
|
||||
}
|
||||
}
|
||||
|
||||
@@ -0,0 +1,6 @@
|
||||
/**
|
||||
* 针对 XSS 的基础封装
|
||||
*
|
||||
* XSS 说明：https://tech.meituan.com/2018/09/27/fe-security.html
|
||||
*/
|
||||
package com.njcn.rdms.framework.xss;
|
||||
@@ -0,0 +1,8 @@
|
||||
com.njcn.rdms.framework.apilog.config.RdmsApiLogAutoConfiguration
|
||||
com.njcn.rdms.framework.jackson.config.RdmsJacksonAutoConfiguration
|
||||
com.njcn.rdms.framework.swagger.config.RdmsSwaggerAutoConfiguration
|
||||
com.njcn.rdms.framework.web.config.RdmsWebAutoConfiguration
|
||||
com.njcn.rdms.framework.apilog.config.RdmsApiLogRpcAutoConfiguration
|
||||
com.njcn.rdms.framework.xss.config.RdmsXssAutoConfiguration
|
||||
com.njcn.rdms.framework.banner.config.RdmsBannerAutoConfiguration
|
||||
com.njcn.rdms.framework.encrypt.config.RdmsApiEncryptAutoConfiguration
|
||||
@@ -0,0 +1,16 @@
|
||||
Application Version: ${rdms.info.version}
|
||||
Spring Boot Version: ${spring-boot.version}
|
||||
|
||||
.__ __. ______ .______ __ __ _______
|
||||
| \ | | / __ \ | _ \ | | | | / _____|
|
||||
| \| | | | | | | |_) | | | | | | | __
|
||||
| . ` | | | | | | _ < | | | | | | |_ |
|
||||
| |\ | | `--' | | |_) | | `--' | | |__| |
|
||||
|__| \__| \______/ |______/ \______/ \______|
|
||||
|
||||
███╗ ██╗ ██████╗ ██████╗ ██╗ ██╗ ██████╗
|
||||
████╗ ██║██╔═══██╗ ██╔══██╗██║ ██║██╔════╝
|
||||
██╔██╗ ██║██║ ██║ ██████╔╝██║ ██║██║ ███╗
|
||||
██║╚██╗██║██║ ██║ ██╔══██╗██║ ██║██║ ██║
|
||||
██║ ╚████║╚██████╔╝ ██████╔╝╚██████╔╝╚██████╔╝
|
||||
╚═╝ ╚═══╝ ╚═════╝ ╚═════╝ ╚═════╝ ╚═════╝
|
||||
Reference in New Issue
Block a user