Microservice/cn-rdms

Fork 0

Files

History

hongawen 5708f80091 初始化

2026-03-11 19:32:37 +08:00

src/main

初始化

2026-03-11 19:32:37 +08:00

pom.xml

初始化

2026-03-11 19:32:37 +08:00

README.md

初始化

2026-03-11 19:32:37 +08:00

README.md

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：

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 无默认值，需要显式配置

例如：

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");
    }
}

实际访问路径是：

/admin-api/user/get

如果 Controller 放在：

com.xxx.xxx.controller.app.xxx

则会自动挂到 /app-api 下。

3.1.2 `CommonResult` 不是自动包装

这个模块不会把任意 Controller 返回值自动包成 CommonResult。

GlobalResponseBodyHandler 的作用，是在返回前记录已经构造好的 CommonResult，供访问日志等能力读取，而不是替开发者自动改写返回结构。

因此 Controller 仍然需要显式返回：

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

使用示例：

@Resource
private RestTemplate restTemplate;

@Resource(name = "loadBalancedRestTemplate")
private RestTemplate loadBalancedRestTemplate;

适用场景：

restTemplate：直接调用固定地址
loadBalancedRestTemplate：通过服务名访问注册中心中的其他服务

3.7 Swagger / Knife4j 文档

模块会自动装配 OpenAPI，并按管理端、应用端拆分分组：

/admin-api/**
/app-api/**

同时会在文档中预置常见请求头，例如认证头、租户头，便于在 Swagger 页面直接调试接口。

Swagger 配置示例：

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 暂存结果中读取出来的。

默认会记录访问日志；如需关闭，可配置：

rdms:
  access-log:
    enable: false

如果需要对某个接口单独调整日志行为，可使用 @ApiAccessLog。

常见用法示例：

@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 片段等需要保留原始内容的接口。

示例：

rdms:
  xss:
    enable: true
    exclude-urls:
      - /admin-api/rich-text/**
      - /app-api/article/save

3.10 API 加解密

模块提供了接口级加解密能力，核心组成包括：

@ApiEncrypt
ApiEncryptFilter
ApiDecryptRequestWrapper
ApiEncryptResponseWrapper

适合理解为：

请求进入时先解密
Controller / Service 内部仍然处理明文
响应返回前再加密

开发使用上，一般是在需要加解密的接口上增加 @ApiEncrypt，其余请求不受影响。

示例：

@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 时自动脱敏。

示例：

@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 引入依赖

<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 准备基础配置

建议至少配置以下内容：

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 写法建议保持统一：

@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 使用访问日志

多数情况下，不需要额外写代码，访问日志会自动生效。

如果需要补充操作名、操作类型、响应体记录等信息，可以加：

@ApiAccessLog(responseEnable = true)

建议同时补齐：

@Tag
@Operation

这样日志中的操作模块和操作名称会更完整；建议将 @Tag / @Operation 作为接口开发的必填规范。

4.6 使用加解密

只在需要的接口上加：

@ApiEncrypt

然后让调用方按约定传输密文即可。接口内部仍按明文对象开发，不需要在 Controller 内手工做解密逻辑。

4.7 使用字段脱敏

在返回对象字段上直接加注解即可：

@MobileDesensitize
private String mobile;

适合用户信息、联系方式、证件信息等对外展示场景。

4.8 使用 RestTemplate

固定地址调用：

@Resource
private RestTemplate restTemplate;

服务名调用：

@Resource(name = "loadBalancedRestTemplate")
private RestTemplate loadBalancedRestTemplate;

4.9 开发时需要注意的几个点

这个模块不会自动把任意返回值包装成 CommonResult，需要显式返回。
接口前缀是按包路径匹配出来的，不是看 Controller 名称。
访问日志默认开启，但是否真正异步落库，还取决于日志相关 RPC 接口是否可用。
XSS、防脱敏、加解密都属于横切能力，原则上应该通过统一配置或注解使用，不建议在业务代码里重复造轮子。
如果项目已经在网关层处理跨域、日志、安全头等逻辑，需要评估是否与本模块职责重叠。

5. 适合承载什么，不适合承载什么

适合放在这个模块里的能力：

Web 层公共配置
HTTP 请求/响应横切处理
接口文档
访问日志
安全性输入输出处理
Web 基础工具注册

不适合放在这个模块里的能力：

具体业务规则
菜单、权限、数据权限等业务权限判断
某个业务模块专属的 Controller 逻辑
与单一业务强耦合的转换规则

从职责上看，这个模块更接近“Web 基础设施层”，而不是“业务功能层”。

README.md Unescape Escape

rdms-spring-boot-starter-web

1. 模块定位

2. 设计思路

3. 功能模块

3.1 Web 基础自动配置

3.1.1 按包路径自动增加接口前缀

3.1.2 CommonResult 不是自动包装

3.2 全局异常处理

3.3 接口返回结果暂存

3.4 请求体缓存

3.5 跨域处理

3.6 RestTemplate 支持

3.7 Swagger / Knife4j 文档

3.8 API 访问日志

3.9 XSS 防护

3.10 API 加解密

3.11 返回字段脱敏

3.12 Jackson JSON 定制

3.13 Banner

4. 开发人员上手

4.1 引入依赖

4.2 准备基础配置

4.3 按约定放置 Controller

4.4 统一返回 CommonResult

4.5 使用访问日志

4.6 使用加解密

4.7 使用字段脱敏

4.8 使用 RestTemplate

4.9 开发时需要注意的几个点

5. 适合承载什么，不适合承载什么

README.md

3.1.2 `CommonResult` 不是自动包装

4.4 统一返回 `CommonResult`