主题
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. 关键类
| 类 | 作用 | 路径 |
|---|---|---|
PmforgeWebAutoConfiguration | Web 层总装配:路径前缀、异常处理、CORS、请求体缓存 | web/config/PmforgeWebAutoConfiguration.java |
WebProperties | pmforge.web.*:app-api、admin-api、admin-ui | web/config/WebProperties.java |
GlobalExceptionHandler | 把 10 余种异常统一转 CommonResult;@ExceptionHandler 方法之间的 switch 分派入口是 allExceptionHandler | web/core/handler/GlobalExceptionHandler.java |
GlobalResponseBodyHandler | 兜底把未被包装的返回值包成 CommonResult,并回填 ApiAccessLog 状态 | web/core/handler/GlobalResponseBodyHandler.java |
WebFrameworkUtils | tenant-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 / XssStringJsonDeserializer | XSS 清洗:Filter 层 + Jackson 反序列化层双保险 | xss/core/ |
PmforgeSwaggerAutoConfiguration / Knife4jOpenApiCustomizer | OpenAPI 信息、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.web | admin-api.url | /admin-api | 管理端前缀 |
pmforge.web | admin-api.controller | **.controller.admin.** | 命中包名的 Controller 才加前缀 |
pmforge.web | app-api.url / app-api.controller | /app-api / **.controller.app.** | 用户端前缀 |
pmforge.web | admin-ui.url | 无默认值(@NotNull,示例 http://localhost:80) | Swagger 里「打开前端」的地址,不配启动即失败 |
pmforge.access-log | enable | true | 访问日志开关 |
pmforge.xss | enable / exclude-urls | true / 空 | XSS 过滤开关与排除路径(示例配置里已关掉,并排除 admin 与 actuator) |
pmforge.api-encrypt | enable / algorithm / header | false / 无 / X-Api-Encrypt | 接口加解密;AES/SM4 用密钥,RSA/SM2 时 request-key 是私钥、response-key 是公钥 |
pmforge.swagger | title/description/version/author/url/email/license/license-url | 全部 @NotEmpty | 缺一个就启动校验失败 |
springdoc.api-docs | enabled | true(示例配置显式 true) | 关掉后 Swagger 自动配置整体不生效 |
spring.jackson.serialization | write-dates-as-timestamps 等 | true | 与 PmforgeJacksonAutoConfiguration 配合,LocalDateTime 输出毫秒数 |
5. 扩展点
- 错误码 → 提示语:抛
ServiceException,GlobalExceptionHandler直接转CommonResult;想自定义响应形态就再注册一个@RestControllerAdvice,注意与本类的@Order。 - 放行路径:认证相关走
starter-security的@PermitAll或AuthorizeRequestsCustomizer;本模块只负责前缀,不负责放行。 - 自定义序列化:加
Jackson2ObjectMapperBuilderCustomizerBean,不要直接替换ObjectMapper(会丢掉 Long 转字符串等约定)。 - XSS 规则:实现自己的
XssCleanerBean 即可替换默认的JsoupXssCleaner。 - 加解密算法:
ApiEncryptFilter依赖ApiEncryptProperties.algorithm,新增算法需改encrypt/core/filter里的工具类,无法纯配置扩展。 - 接口文档分组:用
PmforgeSwaggerAutoConfiguration.buildGroupedOpenApi(group, path)加分组。
6. 常见坑
admin-ui.url没有默认值:WebProperties.AdminUi.url标了@NotNull,本地新起一个模块忘配就直接启动失败;pmforge.swagger.*同理(8 个字段全@NotEmpty)。- 路径前缀靠包名,不靠注解:把 Controller 放到
controller.admin之外的包,URL 会少掉/admin-api,而且不会报错——前端 404 才被发现。 ApiAccessLogFilter是 Filter 不是 Interceptor:它拿不到@RequestBody参数;需要记录请求体时依赖CacheRequestBodyFilter包装后缓存的 body,且只对 JSON 请求生效。- XSS 有两层,可能被「绕过」一半:
XssFilter处理 query/header,xssJacksonCustomizer处理 JSON body;只在pmforge.xss.enable=true时都生效,示例配置里是false。 springdoc.api-docs.enabled=false之外还要注意 Knife4j:PmforgeSwaggerAutoConfiguration用@AutoConfiguration(before = Knife4jAutoConfiguration.class)抢先覆写Knife4jOpenApiCustomizer,自建@Primary同名 Bean 才有效。ApiAccessLog的状态回填在GlobalResponseBodyHandler里:业务自己写ResponseEntity或直接操作HttpServletResponse时,日志里的状态码会不准。
7. 关联页面
- pmforge-common:
CommonResult、WebFilterOrderEnum、JsonUtils - starter-security:Filter 链顺序与放行规则
- starter-websocket:
/infra/ws为何不带 API 前缀 - 横切机制、/modules/system/、访问日志