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、统一正斜杠,与取样路径同源,避免平台分隔符造成静默不匹配。 */