From 1f20d7e68c26ebcf4986544bb7a52f0826d6bf54 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E9=BB=84=E8=87=AA=E8=BE=BE?= <980324341@qq.com> Date: Mon, 5 Oct 2026 07:06:01 +0800 Subject: [PATCH] =?UTF-8?q?test(=E5=85=AC=E5=8F=B8=E8=8C=83=E5=9B=B4):=20G?= =?UTF-8?q?2=20=E5=9D=97=E8=BE=B9=E7=95=8C=E6=94=B9=E7=94=B1=E6=8B=AC?= =?UTF-8?q?=E5=8F=B7=E5=B7=AE=E7=AE=97,handler=20=E4=B9=8B=E9=97=B4?= =?UTF-8?q?=E4=B8=8D=E5=86=8D=E4=BA=92=E5=80=9F=E8=AF=81=E6=8D=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Task 6 修复轮 3 的四条 finding:文档行不得判成绑定行(含 @RequestParam 的行 先归绑定)、方法体开界用 parenDelta 跳过字符串字面量里的括号、闭界按 mapping 行缩进找同级 },text() 只截到块尾——否则下一支 handler 的 readScope 会被当成 这一支的证据,正是「新请求无失败出口」那一型。 全量后端在 detached worktree 跑:3653 例 0 红、Skipped 7、BUILD SUCCESS。 --- ...ompanyIdParamGoesThroughReadScopeTest.java | 368 ++++++++++++++---- 1 file changed, 299 insertions(+), 69 deletions(-) diff --git a/backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyIdParamGoesThroughReadScopeTest.java b/backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyIdParamGoesThroughReadScopeTest.java index ca5dc016a..7ab41212d 100644 --- a/backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyIdParamGoesThroughReadScopeTest.java +++ b/backend-java/src/test/java/com/nanri/aiimage/common/service/CompanyIdParamGoesThroughReadScopeTest.java @@ -7,7 +7,6 @@ import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.util.ArrayList; -import java.util.Arrays; import java.util.HashSet; import java.util.List; import java.util.Set; @@ -37,23 +36,55 @@ import org.junit.jupiter.api.Test; * "一个文件多个 handler 只接一个"因此是默认形状,而 Task 8 明写 {@code detail}/{@code download-zip} * 也要补(评审 I-4b:文件级比对下 list() 没收、detail() 收了 ⇒ 整文件仍绿)。 * 所以按 mapping 注解把文件切成 handler 块,逐块跑两条断言;切不进 handler 的残块 - * (package/import/类级注解/字段)由一条显式断言看守,不许静默跳过。 + * (package/import/类级注解/字段,以及一支 handler 收口之后、下一支之前的尾随方法) + * 由一条显式断言看守,不许静默跳过(触发形状按第 9 条收窄)。 *
  • 白名单键是 handler 级(相对 {@code src/main/java} 的路径 + 该 handler 的 mapping 注解文本, * 形如 {@code .../AdminUserController.java#@GetMapping("/users")})。round 1 用文件级键,往被豁免 * 文件里新加的任何端点会被一并免掉;round 1 的裸文件名版更是让任意包下同名文件自动豁免(评审 I-5)。 * 降级到 handler 级后,{@code hasSize(1)} 钉条目数、liveness 钉"每一项仍对应一个真在收公司 id 的 * handler",并额外咬住"被豁免文件里冒出第二个没点名的公司 id handler"。
  • - *
  • 断言 A 与 B 用同一个"该 handler 是否收公司 id 参数"谓词({@link Block#takesCompanyParam()})。 + *
  • 断言 A 与 B 用同一个"该 handler 是否收公司 id 参数"谓词({@link Block#takesCompanyParam()}, + * B 再按本轮 F-C 收窄到 {@code @RequestParam} 那一族,见下面第 8 条)。 * round 1 的 B 用下划线字面量 {@code company_id} 当触发键、A 用参数形状键,两者不同源 ⇒ * "驼峰参数名 + 真调 readScope + 全文不出现下划线"这种形状 A 绿、B 根本不触发(评审 N1: * 正是"接口 200、前端发 company_id=、参数恒 null、tab 切了纹丝不动"那一记)。统一谓词后它必红。
  • *
  • "公司参数"判定认声明窗口,不认同行。round 1 要求公司 token 与 {@code @RequestParam} * 落在同一物理行,本仓签名大量折行({@code AdminUserController:36-43} 一次摊 7 个参数), - * 折行写法就被静默跳过(评审 N2)。现从该 handler 的 mapping 注解行起、到第一个以 { - * 结尾的行为止取"声明窗口",窗口内同时出现 {@code @RequestParam} 与公司 token(排除 - * {@code @Operation}/{@code description=} 这类文档串)即算"收公司 id 参数";另把 - * {@code request.getParameter("company_id"/"companyId")} 这一族也纳入触发。窗口取不到(整块没有 - * 以 { 结尾的行)判红并报块名,不许"窗口取不到就当没有公司参数"。
  • + * 折行写法就被静默跳过(评审 N2)。现从该 handler 的 mapping 注解行起、到方法体开行为止取 + * "声明窗口"。方法体开行的判据是可判别的那一条:以 { 结尾且到该行左右括号配平 + * (括号只在字符串字面量与行尾注释之外计数)。于是 @ApiResponses({ 这类注解数组开行 + * (括号未闭合)不会把窗口截在参数表之前(评审 F-B:真树 13 支 controller 有 61 行 {@code ApiResponses}, + * {@code ShopManageController.page}、{@code ZiniaoAuthController:44-46} 都是这个形状), + * 而 throws IOException {、折行签名的收尾行 ...Long companyId) { 照样收口(N2 仍成立)。 + * 窗口内同时出现 {@code @RequestParam} 与公司 token 即算"收公司 id 参数";另把 + * {@code request.getParameter("company_id"/"companyId")} 这一族也纳入触发。 + *
  • 出现绑定注解的那一行不是文档行(评审 F-A)。本仓写"被文档化的查询参数"的主流约定是把 + * {@code @Parameter(description = "公司 ID")} 与 {@code @RequestParam(name = "company_id")} 挤在同一行: + * 全树 controller 里含 {@code @Parameter(description} 的行 289 行,其中 93 行同行还带 + * {@code @RequestParam};{@code ShopManageController.page} 的四个参数全部是这个形状,而它正是 + * Task 11 要接线的旗舰端点。round 2 的 {@code isDocLine} 用整行 {@code contains("description =")} + * 判定,把这一族真参数整行当文档吃掉 ⇒ 谓词判"没收公司参数"⇒ A、B 都不跑 = 护栏静默绿(相对 + * round 1 的覆盖倒退)。现规则:一行里出现绑定注解({@code @RequestParam}/{@code @PathVariable}/ + * {@code @ModelAttribute})它就不是文档行;纯文档行({@code @Operation(summary = …)}、单独成行的 + * {@code @Parameter(description = …)}、{@code @ApiResponse})仍然排除,免得把 {@code @Operation} + * 文案里提一句 companyId 当成参数声明而误伤别人。
  • + *
  • handler 块止于它自己的闭括号(复评"范围外观察 1",本轮第 5 条)。round 2 里最后一个 handler + * 的块一路开到文件尾,于是尾随私有方法里的 {@code readScope(} 能替那支没接出口的 handler 过关 + * ——而计划的 Task 11 模板恰恰鼓励在 controller 里写私有收口方法,这一刀会真的放空。现在每个块的主体 + * 收口在"与 mapping 注解同缩进的单独 } 行"上,断言 A 只在该块内找 {@code readScope(}; + * 最后一个块也一样收口,不许开到 EOF。收口找不到 = 边界不可判定,判红并报块名,绝不退回"整块到文件尾"。
  • + *
  • 断言 B 只咬绑定注解那一族(评审 F-C)。{@code request.getParameter("company_id")} 这一族的下划线 + * 本来就在串里,而那个形状永远给不出 {@code name = "company_id"} 字面量 ⇒ 一支只用 getParameter 且 + * 确实走了出口的完全合规 handler 会被 B 判红,只能改写法或塞一句无关声明才绿。现 A 由 + * {@code viaRequestParam || viaGetParameter} 触发(两种都必须走出口),B 只在 {@code viaRequestParam} 时要求。
  • + *
  • 结构守卫只在相关时响(评审 F-D)。"窗口不可判定""主体收口不可判定"这两道新守卫若对本文件的 + * 每一支 handler 生效,射程就随取样键一起扩大(今天 3 支、Task 8-12 后约 10 支),别人的 + * 无关单行体 handler 会红在一道与他无关的护栏上。现两道都加了同一把 {@code hasCompanyToken} 门槛: + * 块内不出现公司 token 就不判。残块守卫同样从"行里有公司 token 就红"收到"行里既有公司 token、又有 + * 参数绑定形状(绑定注解或 {@code getParameter(})才红"——那才是"某支 handler 根本没被切成块"的唯一 + * 可观察证据;私有辅助方法或字段里提一句 {@code companyId}(Task 11 就会写)不再误伤。 + * 取舍写在这里:这样会漏掉"公司 token 落在 handler 之外但形状不像参数声明"那一族(如类级常量), + * 那一族交给人审与变异测试,换的是"不红在无关代码上"。
  • * * *

    取样键:可执行行里出现 {@code company_id} 或 {@code companyId}(裸 token 即入样本,交给逐 handler @@ -61,7 +92,9 @@ import org.junit.jupiter.api.Test; * 连窗口判定都不会跑(N2 的静默跳过正是这么发生的)。真实树今天含这两个 token 的 controller 恰有 3 支 * ({@code AdminUserController}/{@code AdminConsoleController}/{@code ZiniaoAuthController}),后两支的公司 * token 只在 {@code @Operation}/{@code item.put} 里、不在 {@code @RequestParam} 声明窗口上 ⇒ 零假阳性, - * 白名单不必重写。

    + * 白名单不必重写。round 3 没有动这把键(放宽到裸 token 是修 N2 静默跳过的前提),动的是逐 handler 的窗口 + * 判定与块边界;上面 F-A/F-B 两条修的正是"进了样本却被谓词判成没收公司参数"的静默绿,取样面不缩, + * 结构守卫与残块守卫的射程按第 9 条收窄到"与公司相关"。

    */ class CompanyIdParamGoesThroughReadScopeTest { @@ -94,6 +127,15 @@ class CompanyIdParamGoesThroughReadScopeTest { private static final String REQUEST_PARAM = "@RequestParam"; private static final String GET_PARAMETER = "getParameter("; private static final String WINDOW_OPEN = "{"; + private static final String CLOSE_BRACE = "}"; + + /** + * 参数绑定注解(F-A):一行里出现它们,这一行就是真参数声明,无论同行是否还写着 + * {@code description =}——本仓 93 行 {@code @Parameter(description = "…") @RequestParam(…)} 挤同一行的 + * 主流写法靠这条区分。 + */ + private static final List BINDING_ANNOTATIONS = + List.of("@RequestParam", "@PathVariable", "@ModelAttribute"); /** handler 的边界:这些注解组后面跟方法签名的是端点,跟类型声明的是类级。 */ private static final List MAPPING_ANNOTATIONS = List.of( @@ -113,6 +155,22 @@ class CompanyIdParamGoesThroughReadScopeTest { } """; + /** + * 块边界自检样本(第 5 条):handler 自己不走出口,尾随的私有方法里写着 {@code readScope(}。 + * 块边界若一路开到 EOF(round 2 的最后一个块正是这样),这一支就静默绿。 + * 文本块的去缩进让它第一行缩进 = 0:mapping 行缩进 0、方法闭括号行缩进 0 ⇒ 与真树 controller 的形状同构。 + */ + private static final String BLOCK_BOUNDARY_PROBE = """ + @GetMapping("/probe") + public String probe(@RequestParam(name = "company_id", required = false) Long companyId) { + return "probe=" + companyId; + } + + private String tailCall(Long companyId) { + return String.valueOf(readScope(null, companyId)); + } + """; + @Test @DisplayName("每个收公司 id 参数的 handler 都走唯一出口,并且显式写了 name = \"company_id\"") void everyCompanyIdHandlerGoesThroughReadScope() throws IOException { @@ -130,6 +188,24 @@ class CompanyIdParamGoesThroughReadScopeTest { "return \"list=\" + companyId;", "}"); + // 口径 7 的自检(本轮第 5 条):块边界必须止于该 handler 自己的闭括号。两条一起写才不是恒真断言—— + // 反面证据(整段里确有 readScope()说明 readScope( 只出现在收口之后的尾随方法里。 + List probeBlocks = splitBlocks(sourceLines(BLOCK_BOUNDARY_PROBE)).handlers(); + assertThat(probeBlocks) + .as("块边界自检:切块连探针样本里的 handler 都认不出来,扫描无从判定") + .hasSize(1); + Block probe = probeBlocks.get(0); + assertThat(probe.takesCompanyParam()) + .as("块边界自检:探针 handler 必须被认成收公司 id 参数,否则下面的边界断言是空跑") + .isTrue(); + assertThat(probe.text()) + .as("块边界自检:handler 块必须止于与 mapping 注解同缩进的 } 行 —— " + + "否则尾随私有方法里的 readScope( 会替这支没接出口的 handler 过关") + .doesNotContain(READ_SCOPE_CALL); + assertThat(probe.spanText()) + .as("块边界自检的反面证据:readScope( 确实写在收口之后的尾随方法里") + .contains(READ_SCOPE_CALL); + List sampled = sampledControllers(); assertThat(sampled) .as("取样集非空自检:一条都没扫到说明扫描失效,护栏等于没写") @@ -137,16 +213,19 @@ class CompanyIdParamGoesThroughReadScopeTest { for (Path controller : sampled) { String rel = relativeKey(controller); - List lines = executableLines(read(controller)); + List lines = sourceLines(read(controller)); assertThat(lines).as(rel + " 的可执行行为空:整份文件只剩注释,扫描无从判定").isNotEmpty(); Blocks blocks = splitBlocks(lines); for (Block handler : blocks.handlers()) { String where = rel + " 的 handler " + handler.header(); - // 声明窗口取不到 = 切块形状失效,绝不能"当作没公司参数"静默放过,必须红并报块名。 - if (handler.windowUndeterminable()) { - fail(where + " 里找不到以 " + WINDOW_OPEN + " 结尾的行,无法确定声明窗口 —— " - + "切块形状失效(折行签名/单行体等),必须人工核对,不许当作\"该 handler 没收公司参数\"静默跳过"); + // 结构守卫(F-D:只在相关时响——块内没有公司 token 就不判,免得别人红在无关护栏上)。 + // 窗口/主体收口取不到 = 切块形状失效,绝不能"当作没公司参数"、也不能把块边界退到 + // 下一支 handler 或文件尾(那样尾随私有方法里的 readScope( 会替这支过关),必须红并报块名。 + String structure = handler.structureFailure(); + if (structure != null && handler.hasCompanyTokenInSpan()) { + fail(where + structure + " —— 切块形状失效(单行体、闭括号缩进与 mapping 注解不一致等)," + + "必须人工核对,不许当作\"该 handler 没收公司参数\"静默跳过"); } // A 与 B 共用同一个参数形状谓词(N1:触发键必须同源,否则"驼峰+走了出口"的错没人看守)。 boolean takesCompanyParam = handler.takesCompanyParam(); @@ -156,21 +235,25 @@ class CompanyIdParamGoesThroughReadScopeTest { .as(where + " 收了公司 id 参数,但该 handler 体内没有出现 readScope( —— 文件里别处接了不算") .contains(READ_SCOPE_CALL); } - // 断言 B:收了公司 id 参数的 handler 必须写显式 name=(白名单不豁免这条)。 - if (takesCompanyParam) { + // 断言 B:显式 name= 只咬 @RequestParam 那一族(F-C:getParameter("company_id") 的下划线 + // 本来就在串里,那个形状永远给不出 name = "company_id",合规写法不该被逼着改写法才绿)。 + if (handler.viaRequestParam()) { assertThat(handler.text()) .as(where + " 的公司 id 参数没写显式 name = \"company_id\"") .contains(EXPLICIT_PARAM_NAME); } } - // 残块(package/import/类级注解/字段)显式看守:公司 id 形状落在 handler 之外说明切块形状失效, - // 静默跳过 = 又一处惰护栏,所以这里必须红并交人工核对。 + // 残块(package/import/类级注解/字段,以及 handler 收口之后、下一支 handler 之前的尾随方法) + // 显式看守(F-D 收窄触发形状):只有"公司 token + 参数绑定形状"才红——那才是"某支 handler 根本没 + // 被切成块、它的公司参数在块外"的唯一可观察证据,静默跳过 = 又一处惰护栏,必须红并交人工核对。 + // 取舍:handler 之外的类级常量/字段里提一句 companyId 不再判红(否则 Task 8-12 后取样面里的 + // 无关代码会红在这道与他无关的护栏上)。 List unattributed = blocks.residual().stream() - .filter(CompanyIdParamGoesThroughReadScopeTest::isCompanyShapeLine) + .filter(CompanyIdParamGoesThroughReadScopeTest::isCompanyParamDeclarationLine) .collect(Collectors.toList()); assertThat(unattributed) - .as(rel + " 的公司 id 形状落在 handler 之外(切块没覆盖到,可能是类级注解或字段)—— 必须显式核对,不许静默跳过") + .as(rel + " 的公司参数声明落在 handler 之外(切块没覆盖到,可能是类级注解/字段/尾随方法)—— 必须显式核对,不许静默跳过") .isEmpty(); } } @@ -216,7 +299,7 @@ class CompanyIdParamGoesThroughReadScopeTest { Set keys = new HashSet<>(); for (Path controller : sampledControllers()) { String rel = relativeKey(controller); - for (Block handler : splitBlocks(executableLines(read(controller))).handlers()) { + for (Block handler : splitBlocks(sourceLines(read(controller))).handlers()) { if (handler.takesCompanyParam()) keys.add(exemptionKey(rel, handler)); } } @@ -233,11 +316,20 @@ class CompanyIdParamGoesThroughReadScopeTest { return hash < 0 ? key : key.substring(0, hash); } - /** 取样与残块的触发条件:可执行行里出现公司 token(下划线或驼峰)。 */ + /** 取样的触发条件:可执行行里出现公司 token(下划线或驼峰)即入样本,交给逐 handler 的窗口谓词判定。 */ private static boolean isCompanyShapeLine(String line) { return hasCompanyToken(line); } + /** + * 残块守卫的触发条件(F-D):公司 token 且参数绑定形状(绑定注解或 {@code getParameter(})。 + * 只有这种行才说明"某支 handler 根本没被切成块";类级常量或尾随私有方法里提一句 {@code companyId} + * 是本仓正常写法(Task 11 就会写私有收口方法),不该红在无关护栏上。 + */ + private static boolean isCompanyParamDeclarationLine(String line) { + return hasCompanyToken(line) && (isBindingLine(line) || line.contains(GET_PARAMETER)); + } + private static boolean hasCompanyToken(String line) { return line.contains(SNAKE_PARAM) || line.contains(CAMEL_PARAM); } @@ -246,11 +338,22 @@ class CompanyIdParamGoesThroughReadScopeTest { return MAPPING_ANNOTATIONS.stream().anyMatch(line::startsWith); } + /** 绑定注解所在行=真参数声明(F-A)。 */ + private static boolean isBindingLine(String line) { + return BINDING_ANNOTATIONS.stream().anyMatch(line::contains); + } + /** - * 文档串行:{@code @Operation}/{@code @Parameter}/{@code @ApiResponse} 或带 {@code summary =}/ - * {@code description =} 的注解行——这些里出现的 companyId 只是文案,不代表该 handler 真收了公司参数。 + * 文档行:纯 {@code @Operation}/{@code @Parameter}/{@code @ApiResponse},或带 {@code summary =}/ + * {@code description =} 的注解行——里面出现的 companyId 只是文案,不代表该 handler 真收了公司参数。 + *

    判定顺序(F-A 的关键):先认绑定注解,再认文档串。 + * {@code @Parameter(description = "公司 ID") @RequestParam(name = "company_id") Long companyId} + * 这种"文档 + 绑定挤在一行"的本仓主流写法(真树 93 行,{@code ShopManageController.page} 四个参数全中) + * 是真参数声明,round 2 的整行 {@code contains("description =")} 把它当文档吃掉 ⇒ 谓词判"没收公司参数" + * ⇒ A、B 都不跑 = 静默绿。纯文档行仍按原样排除,免得 {@code @Operation} 文案里的 companyId 误伤。

    */ private static boolean isDocLine(String line) { + if (isBindingLine(line)) return false; return line.startsWith("@Operation") || line.startsWith("@Parameter") || line.startsWith("@ApiResponse") @@ -259,101 +362,228 @@ class CompanyIdParamGoesThroughReadScopeTest { } /** - * 按 mapping 注解切 handler 块:连续的注解行(含至少一个 mapping 注解)后面紧跟的不是类型声明, - * 就是一个端点;块尾=下一个端点的注解组首行(最后一个块到文件尾)。 - * 第一个端点之前的所有行(package/import/类级注解/字段)是残块,交给上面那条显式断言。 + * 一行的括号增量:只数字符串字面量、字符字面量与行尾注释之外的 {@code (} 与 {@code )}。 + * 注解里的中文文案常带不成对括号,数进去会让窗口收口找不到(判红),那是误伤。 */ - private static Blocks splitBlocks(List ex) { + private static int parenDelta(String line) { + int delta = 0; + boolean inString = false; + for (int j = 0; j < line.length(); j++) { + char c = line.charAt(j); + if (inString) { + if (c == '\\') j++; + else if (c == '"') inString = false; + } else if (c == '"') { + inString = true; + } else if (c == '/' && j + 1 < line.length() && line.charAt(j + 1) == '/') { + break; + } else if (c == '\'' && j + 2 < line.length() && line.charAt(j + 2) == '\'') { + j += 2; + } else if (c == '(') { + delta++; + } else if (c == ')') { + delta--; + } + } + return delta; + } + + private static List textsOf(List lines) { + return lines.stream().map(SrcLine::text).collect(Collectors.toList()); + } + + /** + * 按 mapping 注解切 handler 块:连续的注解行(含至少一个 mapping 注解)后面紧跟的不是类型声明, + * 就是一个端点;块尾=下一个端点的注解组首行,但每个块再按自己的闭括号收口(第 5 条), + * 于是尾随的私有方法不再算在这支 handler 头上。 + *

    残块=第一个端点之前的行(package/import/类级注解/字段)加上每两支 handler 收口之后、 + * 下一支注解组之前的行(尾随私有方法/字段);两者都交给那条"公司参数声明不许落在 handler 之外"的 + * 显式断言(触发形状见 F-D)。收口找不到的块整段留在块内(由结构守卫判红),不留缝隙。

    + */ + private static Blocks splitBlocks(List ex) { List starts = new ArrayList<>(); int i = 0; while (i < ex.size()) { - if (!ex.get(i).startsWith("@")) { + if (!ex.get(i).text().startsWith("@")) { i++; continue; } int runEnd = i; - while (runEnd + 1 < ex.size() && ex.get(runEnd + 1).startsWith("@")) runEnd++; + while (runEnd + 1 < ex.size() && ex.get(runEnd + 1).text().startsWith("@")) runEnd++; boolean mappingRun = ex.subList(i, runEnd + 1).stream() + .map(SrcLine::text) .anyMatch(CompanyIdParamGoesThroughReadScopeTest::isMappingLine); - String signature = runEnd + 1 < ex.size() ? ex.get(runEnd + 1) : ""; + String signature = runEnd + 1 < ex.size() ? ex.get(runEnd + 1).text() : ""; if (mappingRun && !signature.isEmpty() && !TYPE_DECL.matcher(signature).find()) { starts.add(i); } i = runEnd + 1; } List handlers = new ArrayList<>(); + List residual = new ArrayList<>(); + int prevEnd = 0; for (int k = 0; k < starts.size(); k++) { int from = starts.get(k); int to = k + 1 < starts.size() ? starts.get(k + 1) : ex.size(); - handlers.add(new Block(ex.subList(from, to))); + Block block = new Block(ex.subList(from, to)); + handlers.add(block); + residual.addAll(textsOf(ex.subList(prevEnd, from))); + prevEnd = from + block.blockEndIdx() + 1; } - int first = starts.isEmpty() ? ex.size() : starts.get(0); - return new Blocks(handlers, new ArrayList<>(ex.subList(0, first))); + residual.addAll(textsOf(ex.subList(prevEnd, ex.size()))); + return new Blocks(handlers, residual); } - private record Block(List lines) { + private record Block(List span) { String header() { - return lines.get(0); + return span.get(0).text(); } - String text() { - return String.join("\n", lines); + /** 未收口的整段文本:块边界自检的反面证据用({@code readScope(} 是否只出现在收口之后)。 */ + String spanText() { + return String.join("\n", textsOf(span)); + } + + int mappingIdx() { + for (int j = 0; j < span.size(); j++) { + if (isMappingLine(span.get(j).text())) return j; + } + return -1; } /** 该 handler 的 mapping 注解文本,作为 handler 级豁免键的后缀;没有 mapping 行就退回块首行。 */ String mappingLine() { - return lines.stream() - .filter(CompanyIdParamGoesThroughReadScopeTest::isMappingLine) - .findFirst() - .orElse(lines.get(0)); + int i = mappingIdx(); + return i < 0 ? header() : span.get(i).text(); } /** - * 声明窗口:从本块的 mapping 注解行起、到第一个以 { 结尾的行为止(含该行)。 - * 返回 {@code null} 表示整块找不到以 { 结尾的行(切块形状失效),由调用方判红并报块名。 + * 方法体开行(声明窗口的收口行,F-B):从 mapping 行起累计括号增量,第一个 + * "以 { 结尾且累计配平为 0"的行就是它。判据是两条可区分的字面事实: + * 注解数组开行 @ApiResponses({ 的括号没闭合(累计 > 0),方法体开行是 + * ) {、 {、throws IOException { 这类闭合之后的开行。 + * 于是 @ApiResponses({ 夹在 mapping 行与参数表之间时,整张参数表照样在窗口内(不再静默绿), + * 折行签名(N2)也照样命中。返回 -1 = 整块找不到这样的行(单行体等切块形状失效)。 + */ + int bodyOpenIdx() { + int start = mappingIdx(); + if (start < 0) return -1; + int depth = 0; + for (int j = start; j < span.size(); j++) { + depth += parenDelta(span.get(j).text()); + if (span.get(j).text().endsWith(WINDOW_OPEN) && depth == 0) return j; + } + return -1; + } + + /** + * 声明窗口:mapping 注解行 → 方法体开行(含该行)。返回 {@code null} 表示窗口不可判定, + * 由结构守卫判红并报块名,不许"窗口取不到就当没有公司参数"。 */ List declarationWindow() { - int start = 0; - while (start < lines.size() && !isMappingLine(lines.get(start))) start++; - for (int j = start; j < lines.size(); j++) { - if (lines.get(j).endsWith(WINDOW_OPEN)) { - return lines.subList(start, j + 1); - } + int start = mappingIdx(); + int open = bodyOpenIdx(); + return open < 0 ? null : textsOf(span.subList(start, open + 1)); + } + + /** + * 主体收口行(第 5 条):方法体开行之后,第一个"与 mapping 注解同缩进的单独 } 行"。 + * 最后一个 handler 也一样收口,块边界不许开到 EOF —— 否则尾随私有方法里的 {@code readScope(} + * 能替那支没接出口的 handler 过关(计划的 Task 11 模板恰恰鼓励在 controller 里写私有收口方法)。 + * 返回 -1 = 收口找不到(闭括号缩进与 mapping 注解不一致等),由结构守卫判红。 + */ + int bodyCloseIdx() { + int open = bodyOpenIdx(); + if (open < 0) return -1; + int indent = span.get(mappingIdx()).indent(); + for (int j = open + 1; j < span.size(); j++) { + SrcLine line = span.get(j); + if (line.indent() == indent && CLOSE_BRACE.equals(line.text())) return j; + } + return -1; + } + + /** 块的有效末行:主体收口行;收口找不到时退回整段(那种形状由 {@link #structureFailure()} 判红)。 */ + int blockEndIdx() { + int close = bodyCloseIdx(); + return close >= 0 ? close : span.size() - 1; + } + + /** 断言 A/B 的作用域:从该 handler 的注解组到它自己的闭括号行。 */ + String text() { + return String.join("\n", textsOf(span.subList(0, blockEndIdx() + 1))); + } + + /** 块内(含收口之后的尾随部分)是否出现公司 token:结构守卫只在相关时才响(F-D)。 */ + boolean hasCompanyTokenInSpan() { + return span.stream().anyMatch(line -> hasCompanyToken(line.text())); + } + + /** + * 结构守卫的失败原因,{@code null} = 形状可判定。调用方必须再过一道 {@link #hasCompanyTokenInSpan()} + * (F-D):这两道守卫管的是"本护栏能不能看清这一支",与别人收不收公司参数无关时不该响。 + */ + String structureFailure() { + if (bodyOpenIdx() < 0) { + return " 里找不到方法体开行(以 " + WINDOW_OPEN + " 结尾、且从 mapping 注解行起左右括号配平)的行," + + "无法确定声明窗口"; + } + if (bodyCloseIdx() < 0) { + return " 里找不到与 mapping 注解同缩进的单独 " + CLOSE_BRACE + " 收口行,无法确定该 handler 的主体边界"; } return null; } - boolean windowUndeterminable() { - return declarationWindow() == null; - } - /** - * 该 handler 是否收公司 id 参数(A、B 共用,N1 要求同源): - * ① 声明窗口里同时出现 {@code @RequestParam} 与非文档行的公司 token(覆盖 inline 与折行签名, - * 排除 {@code @Operation}/{@code description=} 里的文案提及); - * ② 或整块里出现 {@code request.getParameter("company_id"/"companyId")} 同族写法(这一族写在方法体内)。 + * ① 声明窗口里同时出现 {@code @RequestParam} 与非文档行的公司 token(覆盖 inline 与折行签名; + * F-A:绑定注解所在行不是文档行)。这是 A、B 共同的触发键里"能给出 name="的那一支。 */ - boolean takesCompanyParam() { + boolean viaRequestParam() { List window = declarationWindow(); - boolean viaRequestParam = window != null + return window != null && window.stream().anyMatch(line -> line.contains(REQUEST_PARAM)) && window.stream().anyMatch(line -> hasCompanyToken(line) && !isDocLine(line)); - boolean viaGetParameter = lines.stream() - .anyMatch(line -> line.contains(GET_PARAMETER) && hasCompanyToken(line)); - return viaRequestParam || viaGetParameter; } + + /** ② 该 handler 主体里的 {@code request.getParameter("company_id"/"companyId")} 同族写法(只触发 A,F-C)。 */ + boolean viaGetParameter() { + return textsOf(span.subList(0, blockEndIdx() + 1)).stream() + .anyMatch(line -> line.contains(GET_PARAMETER) && hasCompanyToken(line)); + } + + /** 该 handler 是否收公司 id 参数(断言 A 的触发键,N1 要求同源;B 另按 {@link #viaRequestParam()})。 */ + boolean takesCompanyParam() { + return viaRequestParam() || viaGetParameter(); + } + } + + /** 源码行:{@code text} 已 trim(口径同仓内既有过滤器),{@code indent} 保留原始缩进(块边界靠它收口)。 */ + private record SrcLine(int indent, String text) { } private record Blocks(List handlers, List residual) { } - /** 剔空行、行注释、块注释起始行与以星号打头的注释续行;口径同 CompanyReadPathMenuGateTest:69-75。 */ + /** + * 剔空行、行注释、块注释起始行与以星号打头的注释续行;口径同 CompanyReadPathMenuGateTest:69-75。 + * 与 {@link #executableLines} 是同一份实现(后者只是取 {@code text}),不会出现"取样用的口径 + * 与切块用的口径不一致"这种静默跳过;额外保留原始缩进,供主体收口按"与 mapping 注解同缩进的 + * 单独 } 行"判定(第 5 条)。 + */ + private static List sourceLines(String text) { + List out = new ArrayList<>(); + for (String raw : text.split("\n", -1)) { + String trimmed = raw.trim(); + if (trimmed.isEmpty() || trimmed.startsWith("//") || trimmed.startsWith("/*") || trimmed.startsWith("*")) { + continue; + } + out.add(new SrcLine(raw.length() - raw.stripLeading().length(), trimmed)); + } + return out; + } + private static List executableLines(String text) { - return Arrays.stream(text.split("\n", -1)) - .map(String::trim) - .filter(line -> !line.isEmpty()) - .filter(line -> !line.startsWith("//") && !line.startsWith("/*") && !line.startsWith("*")) - .collect(Collectors.toList()); + return textsOf(sourceLines(text)); } /** 白名单键的文件部分:相对 src/main/java、统一正斜杠,与取样路径同源,避免平台分隔符造成静默不匹配。 */