Skip to content

starter-web ​

1. 职责 ​

统一 Web 层的「出入口」:请求进来先过 Filter 链(CORS、请求体缓存、XSS、加解密),出去前统一成 CommonResult(GlobalResponseBodyHandler),异常统一成 JSON(GlobalExceptionHandler)。

它同时钉死三件项目级约定:/admin-api、/app-api 路径前缀由包名自动推导(避免 Swagger/Actuator 经 Nginx 暴露)、Long 序列化成字符串(防前端精度丢失)、LocalDateTime 用时间戳传输。

它不解决:认证授权(starter-security)、接口文档之外的路由规范(业务 Controller 自己写 @RequestMapping)、静态资源服务(Spring Boot 默认)。

本节路径均省略公共前缀 framework/pmforge-spring-boot-starter-web/src/main/java/com/pmforge/framework/。

2. 关键类 ​

类作用路径
PmforgeWebAutoConfigurationWeb 层总装配:路径前缀、异常处理、CORS、请求体缓存web/config/PmforgeWebAutoConfiguration.java
WebPropertiespmforge.web.*:app-api、admin-api、admin-uiweb/config/WebProperties.java
GlobalExceptionHandler把 10 余种异常统一转 CommonResult;@ExceptionHandler 方法之间的 switch 分派入口是 allExceptionHandlerweb/core/handler/GlobalExceptionHandler.java
GlobalResponseBodyHandler兜底把未被包装的返回值包成 CommonResult,并回填 ApiAccessLog 状态web/core/handler/GlobalResponseBodyHandler.java
WebFrameworkUtilstenant-id、visit-tenant-id、terminal 三个请求头的读取;登录用户挂/取web/core/util/WebFrameworkUtils.java
CacheRequestBodyFilter仅对 JSON 请求包装 CacheRequestBodyWrapper,让 body 可重复读web/core/filter/CacheRequestBodyFilter.java
ApiAccessLogFilter / ApiAccessLogInterceptor访问日志:Filter 记录耗时与异常,Interceptor 记录 handler 信息apilog/core/filter/、apilog/core/interceptor/
ApiEncryptFilter + ApiDecryptRequestWrapper / ApiEncryptResponseWrapper请求解密、响应加密(AES/SM4/RSA/SM2)encrypt/core/filter/
XssFilter / XssCleaner / XssStringJsonDeserializerXSS 清洗:Filter 层 + Jackson 反序列化层双保险xss/core/
PmforgeSwaggerAutoConfiguration / Knife4jOpenApiCustomizerOpenAPI 信息、all 分组、operationId 规范、x-order 排序swagger/config/
BannerApplicationRunner启动后打一行项目横幅日志banner/core/BannerApplicationRunner.java

3. 自动配置 ​

配置类生效条件注册了什么
PmforgeWebAutoConfiguration始终装配WebMvcRegistrations(按 pmforge.web.*-api.controller 包名加路径前缀);GlobalExceptionHandler、GlobalResponseBodyHandler、WebFrameworkUtils;CorsFilter(order CORS_FILTER);CacheRequestBodyFilter;DemoFilter(仅 pmforge.demo=true);RestTemplate(@ConditionalOnMissingBean)
PmforgeApiLogAutoConfiguration@AutoConfiguration(after = PmforgeWebAutoConfiguration.class);Filter 上 @ConditionalOnProperty(prefix="pmforge.access-log", value="enable", matchIfMissing=true)FilterRegistrationBean<ApiAccessLogFilter> + ApiAccessLogInterceptor
PmforgeJacksonAutoConfiguration@AutoConfiguration(after = JacksonAutoConfiguration.class)Jackson2ObjectMapperBuilderCustomizer(Long → 字符串、LocalDateTime ↔ 毫秒)、Module "TimestampSupportModule"、JsonUtils 初始化
PmforgeXssAutoConfiguration@ConditionalOnProperty(prefix="pmforge.xss", name="enable", havingValue="true", matchIfMissing=true)XssCleaner(默认 JsoupXssCleaner)、xssJacksonCustomizer、XssFilter(order XSS_FILTER)
PmforgeApiEncryptAutoConfiguration@ConditionalOnProperty(prefix="pmforge.api-encrypt", name="enable", havingValue="true")ApiEncryptFilter(order API_ENCRYPT_FILTER)
PmforgeSwaggerAutoConfiguration@ConditionalOnClass(OpenAPI.class) + springdoc.api-docs.enabled=true(缺省 true)OpenAPI、@Primary OpenAPIService、GroupedOpenApi("all");@Import(Knife4jOpenApiCustomizer.class)
PmforgeBannerAutoConfiguration始终装配BannerApplicationRunner

路径前缀的判定:类上有 @RestController 且包名命中 adminApi.controller(默认 **.controller.admin.**)→ 加 /admin-api;命中 **.controller.app.** → 加 /app-api;不在这些包里的 Controller 不加前缀(如 /ws、/infra/ws)。

4. 配置项 ​

前缀键默认值说明
pmforge.webadmin-api.url/admin-api管理端前缀
pmforge.webadmin-api.controller**.controller.admin.**命中包名的 Controller 才加前缀
pmforge.webapp-api.url / app-api.controller/app-api / **.controller.app.**用户端前缀
pmforge.webadmin-ui.url无默认值(@NotNull,示例 http://localhost:80)Swagger 里「打开前端」的地址,不配启动即失败
pmforge.access-logenabletrue访问日志开关
pmforge.xssenable / exclude-urlstrue / 空XSS 过滤开关与排除路径(示例配置里已关掉,并排除 admin 与 actuator)
pmforge.api-encryptenable / algorithm / headerfalse / 无 / X-Api-Encrypt接口加解密;AES/SM4 用密钥,RSA/SM2 时 request-key 是私钥、response-key 是公钥
pmforge.swaggertitle/description/version/author/url/email/license/license-url全部 @NotEmpty缺一个就启动校验失败
springdoc.api-docsenabledtrue(示例配置显式 true)关掉后 Swagger 自动配置整体不生效
spring.jackson.serializationwrite-dates-as-timestamps 等true与 PmforgeJacksonAutoConfiguration 配合,LocalDateTime 输出毫秒数

5. 扩展点 ​

  • 错误码 → 提示语:抛 ServiceException,GlobalExceptionHandler 直接转 CommonResult;想自定义响应形态就再注册一个 @RestControllerAdvice,注意与本类的 @Order。
  • 放行路径:认证相关走 starter-security 的 @PermitAll 或 AuthorizeRequestsCustomizer;本模块只负责前缀,不负责放行。
  • 自定义序列化:加 Jackson2ObjectMapperBuilderCustomizer Bean,不要直接替换 ObjectMapper(会丢掉 Long 转字符串等约定)。
  • XSS 规则:实现自己的 XssCleaner Bean 即可替换默认的 JsoupXssCleaner。
  • 加解密算法:ApiEncryptFilter 依赖 ApiEncryptProperties.algorithm,新增算法需改 encrypt/core/filter 里的工具类,无法纯配置扩展。
  • 接口文档分组:用 PmforgeSwaggerAutoConfiguration.buildGroupedOpenApi(group, path) 加分组。

6. 常见坑 ​

  1. admin-ui.url 没有默认值:WebProperties.AdminUi.url 标了 @NotNull,本地新起一个模块忘配就直接启动失败;pmforge.swagger.* 同理(8 个字段全 @NotEmpty)。
  2. 路径前缀靠包名,不靠注解:把 Controller 放到 controller.admin 之外的包,URL 会少掉 /admin-api,而且不会报错——前端 404 才被发现。
  3. ApiAccessLogFilter 是 Filter 不是 Interceptor:它拿不到 @RequestBody 参数;需要记录请求体时依赖 CacheRequestBodyFilter 包装后缓存的 body,且只对 JSON 请求生效。
  4. XSS 有两层,可能被「绕过」一半:XssFilter 处理 query/header,xssJacksonCustomizer 处理 JSON body;只在 pmforge.xss.enable=true 时都生效,示例配置里是 false。
  5. springdoc.api-docs.enabled=false 之外还要注意 Knife4j:PmforgeSwaggerAutoConfiguration 用 @AutoConfiguration(before = Knife4jAutoConfiguration.class) 抢先覆写 Knife4jOpenApiCustomizer,自建 @Primary 同名 Bean 才有效。
  6. ApiAccessLog 的状态回填在 GlobalResponseBodyHandler 里:业务自己写 ResponseEntity 或直接操作 HttpServletResponse 时,日志里的状态码会不准。

7. 关联页面 ​