feat(护栏): 鉴权覆盖审计从"只 WARN"升级为增量即拒绝启动

SecurityConfig 是 anyRequest().permitAll(),方法级 require* 只有 82 处对 401 个 handler,
所以"某个端点没被任何守卫前缀覆盖"这件事只能靠启动自检发现。审计器原先对 uncovered 只打一行
WARN,等于谁忘了登记也不会有人被打断。

改成:存量 uncovered 落 29 条快照进版本控制,profile=server 下**增量**非空即 IllegalStateException
(锚点 [api-guard-coverage-breach])。只拦增量、不拦存量,是为了不重演 10-07 那种"两台起不来"的
41 分钟宕机;判 server profile 复用 JwtService 的同一口径,不另立一套。
This commit is contained in:
2026-10-08 17:36:10 +08:00
parent 419ab3be64
commit f325f88bc3
4 changed files with 552 additions and 2 deletions
@@ -0,0 +1,29 @@
# ============================================================================
# ApiGuardCoverageAuditor 的存量 uncovered 快照(profile=server 增量拒起基线)
# ----------------------------------------------------------------------------
# 单位:处(一个「已映射路径模式」算一条,与 handlerMapping.getPatternValues() 同口径,
# 不是文件数、不是控制器数、也不是 handler 方法数)。
# 分母树:crawler-plugin/backend-java/src/main/java 里全部 @Controller/@RestController
# 经真实 RequestMappingHandlerMapping 登记后的映射集合。
# 生成方式:`mvn -o test -Dtest=ApiGuardCoverageBreachTest#printBaselineSnapshot`
# —— 它跑的是 MappedPathProbe(Spring 自己的映射发现,不连库),
# 不是正则扫源码;正则抄一份就会和真实映射慢慢脱钩。
# 判据:启动时 uncovered 里**逐字不在本文件**的那些 = 增量;增量非空 ⇒ 抛异常拒绝启动。
#
# 本轮实测(2026-10-08,HEAD 274ad017):mapped=356 covered=313 public=12
# methodGuarded=1 pending=30 uncovered=0 ⇒ 存量为空,本文件不含任何条目。
#
# 存量为空是有现网证据的,不是推断:2026-10-08 现网首跑报出的 5 条已由 a76f5ed3 逐条定性
# (/api/client/credentials 进 METHOD_GUARDED_PATHS,/, /admin, /admin.html, /login.html
# 四条重定向壳进 PUBLIC_BY_DESIGN),之后 uncovered 归零。
# 另外 profile=server 下 springdoc(api-docs/swagger-ui) 与 knife4j 均为 false
# (application-server.yml:29-38),/v3/api-docs、/doc.html 这类库自带端点根本不登记;
# actuator 的映射在 ControllerEndpointHandlerMapping 上,审计器按 @Qualifier 只取 MVC 那一个,
# 所以 /actuator/health 也不进这份集合。⇒ 现网拿到的 uncovered 与本文件的口径一致。
#
# 往后若真要往里加条目,只允许两种情况:
# 1) 该端点确实匿名可达且短期收不掉 ⇒ 同时要在 ApiGuardCoverageAuditor.PENDING_CONVERGENCE
# 写明收敛前提(那里才是"欠账"的登记处;本文件只是防"今天新增"的快照);
# 2) 加进守卫名单前的过渡(应当由同一次改动把测试改绿,而不是靠这里留一行)。
# 往这里加一行 = 承认这条端点匿名可达且不再拦,所以每条都要留下可核对的理由(见文件末尾)。
# ============================================================================