@huicai/cli 2026.814.0 → 2026.1021.0

package/skills/code-quality/scripts/code_java.py

@@ -0,0 +1,695 @@
+# Java 专属体检：语言陷阱 + 框架（Spring / MyBatis / 分片）用法。
+#
+# ── 为什么 Java 要单独一份 ──
+# 通用规则（函数过长、空捕获、注释与实现不符）对所有语言都成立，Java 也不例外。
+# 但 Java 真正会出事的地方，几乎都是**通用规则看不见的**：
+#
+#   @Transactional 写在 private 方法上 —— 编译通过、运行不报错、事务根本不生效，
+#                                        直到某天一半数据写进去一半没写；
+#   new BigDecimal(0.1)               —— 结果是 0.1000000000000000055511151231257827…，
+#                                        对账时差几分钱，查三天；
+#   同类内调用 @Transactional 方法     —— 不走代理，注解等于没写；
+#   static SimpleDateFormat            —— 单线程测试永远正常，压测时日期串成乱码；
+#   Integer == Integer                 —— 128 以内因为缓存是对的，128 以上突然为 false。
+#
+# 这些的共同点是：**编译器不管、单测容易漏、出事时离现场很远**。
+# 正是最该交给机器每次都查一遍的那一类。
+#
+# ── 分组 ──
+#   logic.java-*     语言陷阱（拆箱、精度、并发、资源、集合）
+#   framework.*      框架用法（Spring 事务/注入/异步、MyBatis、分片表）
+#   comment.javadoc-* Javadoc 与签名不符
+#   test.junit-*     JUnit / Mockito
+#
+# 误报纪律与主引擎一致：所有模式在掩码视图上跑；每条规则都要在真实 Spring 代码上验过。
+
+import os
+import re
+import sys
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+
+# ── 语言陷阱 ────────────────────────────────────────────────────────────────
+_RE_PRINT_STACK = re.compile(r'\.printStackTrace\s*\(\s*\)')
+_RE_BROAD_CATCH = re.compile(r'catch\s*\(\s*(?:final\s+)?(Exception|Throwable|RuntimeException)\s+(\w+)\s*\)')
+_RE_BIGDECIMAL_DOUBLE = re.compile(r'new\s+BigDecimal\s*\(\s*(?!"|\')([\w.]*\d[\w.]*|\w+)\s*\)')
+_RE_BIGDECIMAL_EQ = re.compile(r'\b(\w+)\s*\.\s*equals\s*\(\s*(\w+)\s*\)')
+# 需要显式关闭的资源：不在 try-with-resources 里 new 出来就有泄漏风险
+# `(?:[\w.]+\.)?` 这一段不能省：真实代码里写全限定名（`new java.io.FileInputStream(...)`）很常见，
+# 少了它这条规则在一半的场景下静默不响，而报告照样显示「已体检」。
+_RE_CLOSEABLE = re.compile(
+    r'\bnew\s+(?:[\w.]+\.)?(FileInputStream|FileOutputStream|FileReader|FileWriter'
+    r'|BufferedReader|BufferedWriter|RandomAccessFile|Socket|ServerSocket'
+    r'|ZipFile|ZipInputStream|ZipOutputStream|Scanner)\s*\(')
+_RE_ASLIST = re.compile(r'\bArrays\s*\.\s*asList\s*\(')
+_RE_SWITCH = re.compile(r'\bswitch\s*\(')
+_RE_INT_DIV = re.compile(r'\b(?:double|float)\s+\w+\s*=\s*([A-Za-z_$][\w$.]*|\d+)\s*/\s*([A-Za-z_$][\w$.]*|\d+)\s*[;)]')
+_RE_BOXED_EQ = re.compile(
+    r'\b([a-z]\w*(?:Id|Num|Count|Size|Code|Type|Status|Amount|Age|Level|No)?)\s*(==|!=)\s*'
+    r'([a-z]\w*(?:Id|Num|Count|Size|Code|Type|Status|Amount|Age|Level|No)?)\b')
+_BOXED_TYPES = ('Integer', 'Long', 'Short', 'Byte', 'Character', 'Double', 'Float', 'Boolean')
+
+
+def _line_of(lens, off):
+    return lens.text.count('\n', 0, off) + 1
+
+
+def _unit_at(lens, line):
+    u = lens.unit_at(line)
+    return u.label if u else None
+
+
+def check_java_traps(lens, ctx, out, add):
+    """Java 语言层面的坑：编译器不管、单测容易漏、出事时离现场很远的那些。"""
+    code = lens.code
+
+    # ── e.printStackTrace()：打到 stderr，日志系统收不到，线上等于没记 ──
+    for m in _RE_PRINT_STACK.finditer(code):
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.java-print-stack-trace', 'warn', lens, ln,
+            '用 printStackTrace() 打异常：它写到 stderr，不进日志系统，线上查不到也报不了警',
+            '改成 log.error("做什么失败, 关键参数={}", 参数, e)——异常对象要作为最后一个参数传进去，'
+            '否则堆栈会丢', _unit_at(lens, ln))
+
+    # ── 捕获范围过宽 ──
+    # 这条规则最初写成「catch (Exception) 且块里没重抛没记日志就报」，在真实 Spring 代码上
+    # 报出 67 条、无一为真：`catch (Exception ignore) { // 非 JSON，退化为分隔拆分 }`
+    # 是有意识的降级，不是疏忽。而「捕获了什么都不做」本来就归 logic.empty-catch 管。
+    #
+    # 所以改成只盯两个**真正的**风险点：
+    #   ① catch (Throwable)：连 OutOfMemoryError / StackOverflowError 一起吞，几乎从不是对的；
+    #   ② catch (Exception) 罩住一大段代码：业务异常和 NPE、类型转换错误被拉平成一种，
+    #      出事时既分不清是哪一类，也定位不到是哪一行。
+    for m in _RE_BROAD_CATCH.finditer(code):
+        ln = _line_of(lens, m.start())
+        kind, var = m.group(1), m.group(2)
+        brace = code.find('{', m.end())
+        if brace < 0:
+            continue
+        # try 块有多大：从 catch 往回找配对的 `try {`
+        try_head = code.rfind('try', max(0, m.start() - 6000), m.start())
+        try_lines = code.count('\n', try_head, m.start()) if try_head >= 0 else 0
+        if kind == 'Throwable':
+            add(out, ctx, 'logic.java-catch-throwable', 'warn', lens, ln,
+                f'`catch (Throwable {var})` 会连 Error 一起捕获'
+                '（OutOfMemoryError、StackOverflowError 这些，JVM 已经处于不可靠状态）',
+                '改成 catch (Exception)；真要兜住 Error 只应发生在最外层线程边界，'
+                '且必须记日志后让进程退出，而不是继续跑', _unit_at(lens, ln))
+            continue
+        if try_lines >= 25:
+            add(out, ctx, 'logic.java-broad-catch', 'warn', lens, ln,
+                f'`catch ({kind} {var})` 罩住了约 {try_lines} 行代码：'
+                '业务异常与 NPE、类型转换错误被拉平成同一种，出事时分不清是哪一类、也定位不到哪一行',
+                '把 try 的范围缩到真正会抛的那几行；或按异常类型分别捕获，'
+                '让调用方能据此决定重试、降级还是直接失败', _unit_at(lens, ln))
+
+    # ── new BigDecimal(double)：二进制浮点的误差会原样带进金额 ──
+    for m in _RE_BIGDECIMAL_DOUBLE.finditer(code):
+        arg = m.group(1)
+        ln = _line_of(lens, m.start())
+        if re.fullmatch(r'\d+', arg) or arg.endswith('L'):
+            continue                       # 整数字面量没有精度问题
+        add(out, ctx, 'logic.java-bigdecimal-double', 'error', lens, ln,
+            f'`new BigDecimal({arg})` 用 double 构造：0.1 会变成 0.1000000000000000055511151231257827',
+            '改用 `BigDecimal.valueOf(x)` 或 `new BigDecimal("0.1")`（字符串构造）——'
+            '金额差几分钱就是对不上账', _unit_at(lens, ln))
+
+    # ── BigDecimal.equals：值相同但标度不同会判不等（2.0 != 2.00） ──
+    for m in _RE_BIGDECIMAL_EQ.finditer(code):
+        ln = _line_of(lens, m.start())
+        line_txt = lens.line(ln)
+        names = (m.group(1) + m.group(2)).lower()
+        if not re.search(r'(amount|price|money|fee|cost|balance|total|decimal|rate|tax|金额)', names):
+            continue
+        if 'BigDecimal' not in line_txt and not re.search(r'(amount|price|money|fee|balance)', names):
+            continue
+        add(out, ctx, 'logic.java-bigdecimal-equals', 'warn', lens, ln,
+            'BigDecimal 用 equals 比较：它同时比较值和标度，`2.0` 与 `2.00` 会判为不等',
+            '改用 `a.compareTo(b) == 0`', _unit_at(lens, ln))
+
+    # ── 装箱类型用 == 比较：128 以内因缓存为真，128 以上突然为假 ──
+    boxed_vars = {f['name'] for f in lens.fields if f['type'].split('<')[0] in _BOXED_TYPES}
+    for m in _RE_BOXED_EQ.finditer(code):
+        left, right = m.group(1), m.group(3)
+        if left not in boxed_vars and right not in boxed_vars:
+            continue
+        if 'null' in (left, right):
+            continue
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'logic.java-unboxing-eq', 'error', lens, ln,
+            f'`{left} {m.group(2)} {right}` 比较的是装箱对象的引用，不是数值'
+            '——-128~127 因为有缓存会"碰巧正确"，超出这个范围突然为 false',
+            '改用 `equals()`，或 `Objects.equals(a, b)`（同时防 NPE）', _unit_at(lens, ln))
+
+    # ── static SimpleDateFormat：它不是线程安全的，压测时日期会串 ──
+    for f in lens.fields:
+        if 'static' not in f['modifiers']:
+            continue
+        base = f['type'].split('<')[0]
+        if base in ('SimpleDateFormat', 'DateFormat', 'Calendar'):
+            add(out, ctx, 'logic.java-shared-dateformat', 'error', lens, f['line'],
+                f'`static {base} {f["name"]}` —— 它**不是线程安全的**，'
+                '并发时会解析出错误日期甚至抛异常，而单线程测试永远正常',
+                '换成 `DateTimeFormatter`（线程安全，java.time 包），'
+                '或者每次用时 new 一个；真要复用就套 ThreadLocal', f['owner'])
+
+    # ── 需要 close 的资源没走 try-with-resources ──
+    for m in _RE_CLOSEABLE.finditer(code):
+        ln = _line_of(lens, m.start())
+        # 往前找最近的 try：`try (` 开头就是 try-with-resources
+        head = code.rfind('try', max(0, m.start() - 300), m.start())
+        if head >= 0 and re.match(r'try\s*\(', code[head:head + 8]):
+            continue
+        if re.search(r'\breturn\s+new\s+', lens.line(ln)):
+            continue                       # 造出来交给调用方关，责任不在这里
+        add(out, ctx, 'logic.java-resource-leak', 'warn', lens, ln,
+            f'`{m.group(1)}` 在 try-with-resources 之外创建，异常路径上不会被关闭',
+            '改成 `try (var in = new ...()) { … }`——句柄泄漏平时看不出来，'
+            '到达上限时整个服务一起打不开文件', _unit_at(lens, ln))
+
+    # ── Arrays.asList(...) 之后又改它：它返回的是定长视图，add/remove 直接抛 ──
+    for m in _RE_ASLIST.finditer(code):
+        ln = _line_of(lens, m.start())
+        var = re.search(r'(\w+)\s*=\s*Arrays\s*\.\s*asList', lens.line(ln))
+        if not var:
+            continue
+        name = var.group(1)
+        tail = code[m.end():m.end() + 1200]
+        if re.search(rf'\b{re.escape(name)}\s*\.\s*(add|remove|clear|set|sort)\s*\(', tail):
+            add(out, ctx, 'logic.java-aslist-modify', 'error', lens, ln,
+                f'`{name}` 来自 `Arrays.asList`，它是定长视图，'
+                '对它 add/remove 会抛 UnsupportedOperationException',
+                '要可变列表就包一层：`new ArrayList<>(Arrays.asList(...))`', _unit_at(lens, ln))
+
+    # ── for-each 里增删集合：ConcurrentModificationException ──
+    for m in re.finditer(r'for\s*\(\s*(?:final\s+)?[\w<>\[\],.\s?]+\s+(\w+)\s*:\s*(\w+)\s*\)', code):
+        coll = m.group(2)
+        brace = code.find('{', m.end())
+        if brace < 0 or brace - m.end() > 4:
+            continue
+        depth, end = 0, brace
+        for i in range(brace, min(len(code), brace + 4000)):
+            if code[i] == '{':
+                depth += 1
+            elif code[i] == '}':
+                depth -= 1
+                if depth == 0:
+                    end = i
+                    break
+        body = code[brace:end]
+        if re.search(rf'\b{re.escape(coll)}\s*\.\s*(add|remove|clear)\s*\(', body):
+            ln = _line_of(lens, m.start())
+            add(out, ctx, 'logic.java-concurrent-modify', 'error', lens, ln,
+                f'在 for-each 遍历 `{coll}` 的同时增删它，会抛 ConcurrentModificationException',
+                '用 `Iterator.remove()`，或 `removeIf(...)`，或先收集再统一处理', _unit_at(lens, ln))
+
+    # ── 循环里 String += ：每次都新建对象，n 大了就是 O(n²) ──
+    for m in re.finditer(r'\b(?:for|while)\s*\([^)]*\)\s*\{', code):
+        brace = m.end() - 1
+        depth, end = 0, brace
+        for i in range(brace, min(len(code), brace + 3000)):
+            if code[i] == '{':
+                depth += 1
+            elif code[i] == '}':
+                depth -= 1
+                if depth == 0:
+                    end = i
+                    break
+        body = code[brace:end]
+        hit = re.search(r'\b(\w+)\s*\+=\s*(?!\d)', body)
+        if not hit:
+            continue
+        name = hit.group(1)
+        decl = re.search(rf'\bString\s+{re.escape(name)}\b', code[:m.start()])
+        if not decl:
+            continue
+        ln = _line_of(lens, m.start()) + body[:hit.start()].count('\n')
+        add(out, ctx, 'logic.java-concat-in-loop', 'warn', lens, ln,
+            f'循环里对 String `{name}` 做 `+=`：每次都新建一个对象并复制全部内容，'
+            '循环次数一多就是 O(n²)',
+            '循环外建 `StringBuilder`，循环里 `append`，出循环再 `toString()`', _unit_at(lens, ln))
+
+    # ── 整数相除赋给浮点：先按整数截断，再转成 double，小数部分早没了 ──
+    for m in _RE_INT_DIV.finditer(code):
+        ln = _line_of(lens, m.start())
+        if '.' in m.group(1) or '.' in m.group(2):
+            continue
+        add(out, ctx, 'logic.java-int-division', 'warn', lens, ln,
+            f'`{m.group(1)} / {m.group(2)}` 两边都是整数，会先做整数除法截断，再转成浮点'
+            '（3/2 得到的是 1.0 不是 1.5）',
+            '给一边加 `* 1.0` 或强转 `(double)`；算百分比/占比时这一条几乎总是 bug',
+            _unit_at(lens, ln))
+
+    # ── switch 没有 default：新增枚举值时静默什么都不做 ──
+    for m in _RE_SWITCH.finditer(code):
+        brace = code.find('{', m.end())
+        if brace < 0:
+            continue
+        depth, end = 0, brace
+        for i in range(brace, min(len(code), brace + 4000)):
+            if code[i] == '{':
+                depth += 1
+            elif code[i] == '}':
+                depth -= 1
+                if depth == 0:
+                    end = i
+                    break
+        if 'default' not in code[brace:end]:
+            ln = _line_of(lens, m.start())
+            add(out, ctx, 'logic.java-switch-no-default', 'warn', lens, ln,
+                'switch 没有 default 分支：将来枚举加了新值，这里会静默地什么都不做',
+                '补 default——即使只是抛 IllegalArgumentException 或记一条日志，'
+                '也好过让未知取值悄悄走过去', _unit_at(lens, ln))
+
+    # ── Optional.get() 不先判存在：等同于用一个更麻烦的方式抛 NPE ──
+    # 先把本文件里所有声明成 Optional 的名字收齐（方法参数、局部变量、字段都在内）——
+    # 只看 `.get()` 所在那一行是找不到类型的，类型几乎总是声明在别处。
+    opt_vars = set(re.findall(r'\bOptional\s*<[^>]*>\s+(\w+)', code))
+    opt_vars |= {f['name'] for f in lens.fields if f['type'].split('<')[0] == 'Optional'}
+    # 返回 Optional 的常见方法，链式调用 `.findById(x).get()` 同样要管
+    chained = re.compile(r'\.\s*(findById|findOne|findFirst|findAny|reduce|max|min|'
+                         r'stream\(\)[^;]*?)\s*\([^;]*\)\s*\.\s*get\s*\(\s*\)')
+    for m in list(re.finditer(r'\b(\w+)\s*\.\s*get\s*\(\s*\)', code)) + list(chained.finditer(code)):
+        ln = _line_of(lens, m.start())
+        line_txt = lens.line(ln)
+        name = m.group(1) if m.re.groups and m.lastindex else ''
+        is_opt = name in opt_vars or 'Optional' in line_txt or m.re is chained
+        if not is_opt:
+            continue
+        if re.search(r'(isPresent|isEmpty|orElse|ifPresent|orElseThrow)', line_txt):
+            continue
+        prev = lens.line(ln - 1) + lens.line(ln - 2)
+        if 'isPresent' in prev or 'isEmpty' in prev:
+            continue
+        add(out, ctx, 'logic.java-optional-get', 'warn', lens, ln,
+            '`Optional.get()` 没有先判存在，空值时抛 NoSuchElementException',
+            '用 `orElse(默认值)` / `orElseThrow(() -> new 业务异常())` / `ifPresent(...)`——'
+            '把"取不到怎么办"显式写出来', _unit_at(lens, ln))
+
+    # ── finally 里 return：会吞掉 try 块里正在抛的异常 ──
+    for m in re.finditer(r'\bfinally\s*\{', code):
+        brace = m.end() - 1
+        depth, end = 0, brace
+        for i in range(brace, min(len(code), brace + 2000)):
+            if code[i] == '{':
+                depth += 1
+            elif code[i] == '}':
+                depth -= 1
+                if depth == 0:
+                    end = i
+                    break
+        if re.search(r'\breturn\b|\bthrow\b', code[brace:end]):
+            ln = _line_of(lens, m.start())
+            add(out, ctx, 'logic.java-finally-return', 'error', lens, ln,
+                'finally 块里 return/throw：会把 try 块中正在抛出的异常直接丢弃，故障现场就此消失',
+                '把 finally 限制成只做资源清理；要改返回值就在 try 里改', _unit_at(lens, ln))
+
+    # ── 重写了 equals 却没重写 hashCode：放进 HashMap/HashSet 会找不到 ──
+    for cls in lens.classes():
+        methods = [u for u in lens.functions() if u.owner == cls.name]
+        has_eq = any(u.name == 'equals' for u in methods)
+        has_hash = any(u.name == 'hashCode' for u in methods)
+        if has_eq and not has_hash:
+            add(out, ctx, 'logic.java-equals-no-hashcode', 'error', lens, cls.start,
+                f'`{cls.name}` 重写了 equals 但没有重写 hashCode',
+                '两者必须成对：只改 equals 的话，两个"相等"的对象散列到不同的桶，'
+                'HashMap/HashSet 里放进去就再也取不出来', cls.name)
+        if has_hash and not has_eq:
+            add(out, ctx, 'logic.java-equals-no-hashcode', 'warn', lens, cls.start,
+                f'`{cls.name}` 重写了 hashCode 但没有重写 equals',
+                '两者必须成对，否则散列到同一个桶之后仍然会被判为不同对象', cls.name)
+
+
+# ── Spring / 持久层 ────────────────────────────────────────────────────────
+# 这一组的共同点：**注解写了、编译过了、运行不报错，但它根本没生效**。
+# 事务不回滚、异步没异步、注入是 null——都要等到线上某次异常路径才暴露，
+# 而那时离写下这行代码已经过去几个月。编译器不管的事，就该机器每次都查。
+_BEAN_ANNOS = ('@Service', '@Component', '@Repository', '@Controller', '@RestController',
+               '@Configuration', '@Mapper')
+_RE_VALUE_ANNO = re.compile(r'@Value\s*\(\s*["\']\$\{([^}:]+)(:[^}]*)?\}["\']\s*\)')
+_RE_MAPPING = re.compile(r'@(RequestMapping)\s*\(([^)]*)\)')
+# MyBatis：${} 是字符串替换（注入面），#{} 才是预编译参数
+_RE_MYBATIS_DOLLAR = re.compile(r'\$\{([A-Za-z_][\w.]*)\}')
+_RE_SQL_IN_ANNO = re.compile(r'@(Select|Insert|Update|Delete)\s*\(')
+
+
+def _class_of(lens, line):
+    """这一行落在哪个类里。"""
+    best = None
+    for c in lens.classes():
+        if c.start <= line <= c.end and (best is None or c.start > best.start):
+            best = c
+    return best
+
+
+def check_java_framework(lens, ctx, out, add):
+    """Spring 事务/注入/异步 与 MyBatis、分片表的用法检查。"""
+    code = lens.code
+    methods = lens.functions()
+    tx_methods = {u.name for u in methods if u.has_annotation('Transactional')}
+    async_methods = {u.name for u in methods if u.has_annotation('Async')}
+    cached_methods = {u.name for u in methods if u.has_annotation('Cacheable', 'CachePut', 'CacheEvict')}
+
+    for u in methods:
+        anno_tx = u.has_annotation('Transactional')
+
+        # ── @Transactional 落在 private / final / static 上：AOP 代理根本包不住它 ──
+        if anno_tx and ({'private', 'final', 'static'} & set(u.modifiers)):
+            bad = sorted({'private', 'final', 'static'} & set(u.modifiers))
+            add(out, ctx, 'framework.tx-not-effective', 'error', lens, u.start,
+                f'`{u.label}` 是 {"/".join(bad)} 方法，但标了 @Transactional —— '
+                'Spring 靠动态代理织入事务，代理包不住这三种方法，**注解完全不生效**',
+                '改成 public 非 final 非 static；真需要私有就把事务边界上移到调用它的 public 方法上。'
+                '这类问题编译不报错、平时也看不出来，直到某次异常时数据写了一半', u.label)
+
+        # ── @Transactional 只声明在类上 / 方法 throws 受检异常却没写 rollbackFor ──
+        if anno_tx and u.throws:
+            decl = ' '.join(str(a) for a in u.decorators)
+            checked = [t for t in u.throws if not re.search(r'Runtime|Unchecked', t)]
+            if checked and 'rollbackFor' not in decl:
+                add(out, ctx, 'framework.tx-no-rollback-for', 'error', lens, u.start,
+                    f'`{u.label}` 声明抛出受检异常 {"、".join(checked)}，但 @Transactional 没写 rollbackFor —— '
+                    '**Spring 默认只对 RuntimeException 回滚**，抛受检异常时事务照常提交',
+                    '写成 `@Transactional(rollbackFor = Exception.class)`；'
+                    '这是所有事务陷阱里最安静的一个——数据写进去了，异常也抛出来了，两边都"正常"', u.label)
+
+        # ── @Transactional 方法里把异常吞了：异常不往外抛，事务就不回滚 ──
+        if anno_tx:
+            for cm in re.finditer(r'\bcatch\s*\(([^)]*)\)\s*\{', u.body):
+                brace = cm.end() - 1
+                depth, end = 0, brace
+                for i in range(brace, len(u.body)):
+                    if u.body[i] == '{':
+                        depth += 1
+                    elif u.body[i] == '}':
+                        depth -= 1
+                        if depth == 0:
+                            end = i
+                            break
+                blk = u.body[brace:end]
+                if re.search(r'\bthrow\b|setRollbackOnly', blk):
+                    continue
+                ln = u.line_at(cm.start())
+                add(out, ctx, 'framework.tx-swallow', 'error', lens, ln,
+                    f'`{u.label}` 带 @Transactional，却在方法内 catch 住异常且不再抛出 —— '
+                    '异常不出方法，事务就**不会回滚**，前面写进去的数据会留下来',
+                    '要么重新抛出（或包成运行时异常），要么显式 '
+                    '`TransactionAspectSupport.currentTransactionStatus().setRollbackOnly()`；'
+                    '想"忽略这个异常并继续提交"就必须在注释里写明是刻意的', u.label)
+
+        # ── 同类内自调用 @Transactional / @Async / @Cacheable：不过代理，注解等于没写 ──
+        for target, kind, why in ((tx_methods, '@Transactional', '事务不会开启'),
+                                  (async_methods, '@Async', '不会异步执行，仍在当前线程同步跑完'),
+                                  (cached_methods, '@Cacheable', '缓存不生效，每次都真的执行')):
+            for name in target:
+                if name == u.name:
+                    continue
+                if not re.search(rf'(?<![\w.]){re.escape(name)}\s*\(', u.body) and \
+                        not re.search(rf'\bthis\s*\.\s*{re.escape(name)}\s*\(', u.body):
+                    continue
+                ln = u.start
+                add(out, ctx, 'framework.self-invocation', 'error', lens, ln,
+                    f'`{u.label}` 在**同一个类内**直接调用了带 {kind} 的 `{name}()` —— '
+                    f'这样走的是 this 引用而不是 Spring 代理，{why}',
+                    '把被调方法挪到另一个 Bean 再注入进来调用；'
+                    '或注入自身代理（@Lazy 自注入 / AopContext.currentProxy()）。'
+                    '这个坑的隐蔽之处在于：单独调那个方法时一切正常，只有内部调用这条路径是坏的', u.label)
+                break
+
+        # ── @RequestMapping 不限定 method：一个地址同时接受 GET 与 POST ──
+        for am in _RE_MAPPING.finditer(' '.join(str(a) for a in u.decorators)):
+            if 'method' not in am.group(2) and '…' not in am.group(2):
+                add(out, ctx, 'framework.mapping-no-method', 'warn', lens, u.start,
+                    f'`{u.label}` 用 @RequestMapping 却没限定 method，该地址会同时接受 GET/POST/PUT/DELETE',
+                    '改用 @GetMapping / @PostMapping 等语义化注解；'
+                    '写操作被 GET 打开意味着它能被浏览器预取、被爬虫触发', u.label)
+
+    # ── 字段注入：拿不到编译期的依赖检查，测试里也没法直接构造 ──
+    cls_is_bean = {}
+    for c in lens.classes():
+        cls_is_bean[c.name] = any(str(a).split('(')[0] in _BEAN_ANNOS for a in c.decorators)
+    for f in lens.fields:
+        annos = [str(a).split('(')[0] for a in f['annotations']]
+        if '@Autowired' in annos or '@Resource' in annos or '@Inject' in annos:
+            add(out, ctx, 'framework.field-injection', 'warn', lens, f['line'],
+                f'`{f["owner"]}.{f["name"]}` 用字段注入 —— 依赖关系不出现在构造器上，'
+                '写单测时没法直接 new 出来，循环依赖也要等到启动才暴露',
+                '改成构造器注入（配合 final）：依赖一目了然、对象一建好就完整、测试可以直接传替身进去。'
+                'Lombok 项目加 @RequiredArgsConstructor 即可，改动很小', f['owner'])
+        # ── @Value 不给默认值：配置漏配时整个应用起不来，且报错很难懂 ──
+        for a in f['annotations']:
+            vm = _RE_VALUE_ANNO.search(str(a))
+            if vm and not vm.group(2):
+                add(out, ctx, 'framework.value-no-default', 'info', lens, f['line'],
+                    f'`@Value("${{{vm.group(1)}}}")` 没有默认值，这一项漏配时应用启动会直接失败',
+                    f'写成 `${{{vm.group(1)}:合理的默认值}}`；确实必须由部署方提供的，'
+                    '就在文档与配置样例里标成必填项', f['owner'])
+
+    # ── 单例 Bean 里的可变实例字段：多线程共享同一份状态 ──
+    # 配置类天生就该有可变字段——Spring 启动时按配置往里注值，那正是它的工作方式。
+    # 不排掉它们，这条规则在一个真实后端上报出 82 条，其中绝大多数是 @ConfigurationProperties。
+    conf_classes = set()
+    for c in lens.classes():
+        annos = ' '.join(str(a) for a in c.decorators)
+        if 'ConfigurationProperties' in annos or 'ConfigMap' in annos:
+            conf_classes.add(c.name)
+        if re.search(r'(Properties|Config|Configuration|Settings|Options|Props)$', c.name):
+            conf_classes.add(c.name)
+    for f in lens.fields:
+        if not cls_is_bean.get(f['owner']) or f['owner'] in conf_classes:
+            continue
+        mods = set(f['modifiers'])
+        # volatile 与 final/static 一样，是作者**已经意识到**这是共享状态的标记：
+        # `private volatile Map<..> snapshot = emptyMap()` 是标准的快照缓存写法，不是疏忽。
+        # 报它等于在指责一段深思熟虑的代码，这类误报最伤工具的可信度。
+        if mods & {'static', 'final', 'volatile'}:
+            continue
+        if any('Value' in str(a) or 'ConfigurationProperties' in str(a) for a in f['annotations']):
+            continue                      # 由配置注入的字段，同上
+        base = f['type'].split('<')[0]
+        # 接口类型必须一起收：字段几乎总是声明成 `List<X>` / `Map<K,V>` 而不是 ArrayList/HashMap，
+        # 只列具体类的话，这条规则在最常见的写法上静默不响。
+        mutable = base in ('List', 'Map', 'Set', 'Collection', 'Queue', 'Deque', 'Iterable',
+                           'ArrayList', 'HashMap', 'HashSet', 'LinkedList', 'StringBuilder',
+                           'StringBuffer', 'ArrayDeque', 'LinkedHashMap', 'TreeMap', 'TreeSet')
+        counter = base in ('int', 'long', 'Integer', 'Long', 'double', 'Double') and bool(f['init'])
+        if not (mutable or counter):
+            continue
+        add(out, ctx, 'framework.singleton-mutable-state', 'warn', lens, f['line'],
+            f'`{f["owner"]}` 是单例 Bean，字段 `{f["name"]}`（{base}）是可变的实例状态 —— '
+            '所有请求线程共用同一份，并发下会互相看见对方的数据',
+            '把状态挪进方法局部变量；确实要跨请求共享就用线程安全容器'
+            '（ConcurrentHashMap / AtomicLong）并说明为什么需要共享', f['owner'])
+
+    # ── MyBatis ${} 拼接：它是字符串替换，不是预编译参数 ──
+    for m in _RE_MYBATIS_DOLLAR.finditer(lens.text):
+        if lens.in_literal(m.start()) is False:
+            continue                      # 只看写在字符串里的 SQL 片段
+        ln = _line_of(lens, m.start())
+        line_txt = lens.line(ln)
+        if not re.search(r'(select|insert|update|delete|from|where|order\s+by|group\s+by)', line_txt, re.I):
+            continue                      # 不是 SQL 上下文（日志模板、路径模板里的 ${} 无害）
+        add(out, ctx, 'framework.mybatis-dollar', 'error', lens, ln,
+            f'SQL 里用了 `${{{m.group(1)}}}` —— 它是**字符串替换**，参数被原样拼进语句，是注入入口',
+            '值一律用 `#{}`（预编译占位符）。表名/列名/排序方向确实不能预编译，'
+            '那就用白名单把取值限死，绝不能让调用方直接决定', _unit_at(lens, ln))
+
+
+# ── Javadoc 与 JUnit ───────────────────────────────────────────────────────
+_RE_DOC_THROWS = re.compile(r'@throws\s+([A-Za-z_$][\w$.]*)')
+_RE_ASSERT_EQ = re.compile(r'\bassert(?:Equals|Same|ArrayEquals)\s*\(')
+
+
+# 构造「期望值」的常见工厂——它们带括号，但绝不是「被测代码算出来的结果」
+_LITERAL_FACTORY = re.compile(
+    r'^(List|Map|Set|Arrays|Collections|Optional|BigDecimal|BigInteger|Integer|Long|Double|'
+    r'String|Instant|Duration|LocalDate\w*|LocalDateTime|UUID)\s*\.\s*'
+    r'(of|ofEntries|asList|valueOf|empty\w*|singleton\w*|emptyList|emptyMap|parse|ofPattern|ofSeconds)')
+
+
+def _looks_literal(arg):
+    """这个实参像不像「写死的期望值」。"""
+    arg = arg.strip()
+    if not arg:
+        return False
+    if re.match(r'^["\']|^-?\d|^(true|false|null)$', arg):
+        return True                      # 字面量
+    if _LITERAL_FACTORY.match(arg):
+        return True                      # List.of(...) 这类
+    if re.match(r'^new\s+\w', arg):
+        return True                      # new ExpectedDto(...)
+    if re.match(r'^[A-Z][A-Z0-9_]*$', arg):
+        return True                      # 常量
+    return False
+
+
+def _first_arg(code, lparen):
+    """取调用的第一个实参（按顶层逗号切）。
+
+    不能用 `([^,()]+?),` 这种正则：真实的第一个参数几乎总是带括号的调用
+    （`assertEquals(service.compute(1), 42)`），正则一遇到括号就匹配不上，
+    规则于是静默不响——而这正是它最该响的场景。
+    """
+    depth = 0
+    for i in range(lparen, len(code)):
+        ch = code[i]
+        if ch in '([{':
+            depth += 1
+        elif ch in ')]}':
+            depth -= 1
+            if depth == 0:
+                return code[lparen + 1:i].strip()
+        elif ch == ',' and depth == 1:
+            return code[lparen + 1:i].strip()
+    return ''
+
+
+def _first_two_args(code, lparen):
+    """取前两个实参（按顶层逗号切）。"""
+    args, depth, start = [], 0, lparen + 1
+    for i in range(lparen, len(code)):
+        ch = code[i]
+        if ch in '([{':
+            depth += 1
+        elif ch in ')]}':
+            depth -= 1
+            if depth == 0:
+                args.append(code[start:i].strip())
+                break
+        elif ch == ',' and depth == 1:
+            args.append(code[start:i].strip())
+            start = i + 1
+            if len(args) >= 2:
+                break
+    return (args + ['', ''])[:2]
+_RE_TRY_FAIL = re.compile(r'\btry\s*\{[^{}]{0,600}?\bfail\s*\(')
+
+
+def check_java_doc_and_test(lens, ctx, out, add, doc_text):
+    """Javadoc 声明与实现是否一致；JUnit 用例的几个经典写错。
+
+    doc_text 由主引擎传进来（剥注释记号的那个函数），避免两处各写一份剥法——
+    两份剥法迟早会对同一段注释给出不同结果，而那种分歧极难排查。
+    """
+    for u in lens.functions():
+        doc = doc_text(u.doc)
+        if not doc:
+            continue
+        # ── @throws 写了，方法既不声明也不抛 ──
+        declared = _RE_DOC_THROWS.findall(doc)
+        if declared:
+            thrown_in_body = set(re.findall(r'\bthrow\s+new\s+([A-Za-z_$][\w$.]*)', u.body))
+            sig = {t.split('.')[-1] for t in u.throws}
+            ghost = [t for t in declared
+                     if t.split('.')[-1] not in sig and t.split('.')[-1] not in
+                     {x.split('.')[-1] for x in thrown_in_body}]
+            # 运行时异常不必出现在 throws 上，只有确实也没 throw 过才算不符
+            ghost = [t for t in ghost if not re.search(r'(Runtime|Illegal|Unsupported|NullPointer)', t)]
+            if ghost:
+                add(out, ctx, 'comment.javadoc-throws', 'warn', lens, u.start,
+                    f'`{u.label}` 的 Javadoc 写了 @throws {"、".join(ghost)}，'
+                    '但方法签名不声明、方法体里也没有抛',
+                    '异常改过之后注释没跟着改——按现在的实现更新 @throws；'
+                    '调用方是照着这份文档写 catch 的', u.label)
+
+    if not lens.is_test:
+        return
+    # ── assertEquals 的参数顺序：第一个是**期望值** ──
+    # 写反了不会让用例失败，但失败信息会把期望和实际说反，排查时直接把人带沟里
+    # 判据必须**同时看两个参数**：只看第一个带不带括号是不够的——
+    # `assertEquals(List.of(1L, 2L), ids(got))` 的第一个参数带括号，但它正是期望值，顺序完全正确。
+    # 真正写反的形状是「第一个是算出来的、第二个是写死的」。
+    for m in _RE_ASSERT_EQ.finditer(lens.code):
+        first, second = _first_two_args(lens.code, m.end() - 1)
+        if not first or not second:
+            continue
+        ln = _line_of(lens, m.start())
+        first_is_computed = (not _looks_literal(first)
+                             and bool(re.search(r'\w\s*\(|^(result|actual|res|out|ret)\b', first)))
+        if not (first_is_computed and _looks_literal(second)):
+            continue
+        add(out, ctx, 'test.junit-assert-order', 'info', lens, ln,
+            f'`assertEquals({first[:30]}, …)` 的第一个参数像是**实际值** —— JUnit 的约定是 (期望, 实际)',
+            '调换顺序。写反了用例照样通过，但失败信息会把「期望 X 实际 Y」说反，排查时会被带偏',
+            _unit_at(lens, ln))
+
+    # ── 用 try/fail() 断言异常：漏写 fail 或被 catch 吞掉都会让用例变成永远通过 ──
+    for m in _RE_TRY_FAIL.finditer(lens.code):
+        ln = _line_of(lens, m.start())
+        add(out, ctx, 'test.junit-try-fail', 'info', lens, ln,
+            '用 try/fail() 断言异常：这种写法一旦 catch 范围写宽了（或忘了 fail），用例会永远通过',
+            '改用 `assertThrows(XxxException.class, () -> …)`，顺带还能断言异常消息', _unit_at(lens, ln))
+
+
+# ── 与 dev-java「事务失效八景 / 常见坑 TOP」对齐的几条 ────────────────────
+# 这一组不是新想出来的，是把团队已经写进技能文档的评审自查项变成机器每次都查一遍。
+# 方法论写在文档里靠人记得，写在这里靠机器不忘——两者要说同一件事，不能各说各的。
+_RE_NEW_THREAD = re.compile(
+    r'\bnew\s+Thread\s*\(|\bCompletableFuture\s*\.\s*(?:runAsync|supplyAsync)\s*\('
+    r'|\b\w*(?:executor|Executor|pool|Pool)\w*\s*\.\s*(?:submit|execute)\s*\(')
+_RE_EXECUTORS = re.compile(r'\bExecutors\s*\.\s*(newFixedThreadPool|newCachedThreadPool|'
+                           r'newSingleThreadExecutor|newScheduledThreadPool|newWorkStealingPool)\s*\(')
+_RE_WEEK_YEAR = re.compile(r'["\'][^"\']*\bYYYY\b[^"\']*["\']')
+_RE_TL_SET = re.compile(r'\b(\w+)\s*\.\s*set\s*\(')
+
+
+def check_java_pitfalls(lens, ctx, out, add):
+    """dev-java 技能里「评审必查」的那几条，改由机器每次都查。"""
+    code = lens.code
+
+    for u in lens.functions():
+        # ── 事务内起新线程：事务绑定在当前线程上，新线程里的操作不在这个事务里 ──
+        if u.has_annotation('Transactional'):
+            m = _RE_NEW_THREAD.search(u.body)
+            if m:
+                ln = u.line_at(m.start())
+                add(out, ctx, 'framework.tx-new-thread', 'error', lens, ln,
+                    f'`{u.label}` 带 @Transactional，方法内却起了新线程/异步任务 —— '
+                    '事务是绑在**当前线程**上的，新线程里的数据库操作不属于这个事务，'
+                    '外层回滚时它已经提交了',
+                    '把异步部分挪到事务提交之后（`TransactionSynchronizationManager` 的 afterCommit 回调），'
+                    '或者让异步任务自己开事务并自行保证幂等', u.label)
+
+    # ── ThreadLocal.set 之后没有 remove：线程池复用会把上一个请求的数据带给下一个 ──
+    tl_vars = {f['name'] for f in lens.fields if f['type'].split('<')[0].endswith('ThreadLocal')}
+    tl_vars |= set(re.findall(r'\bThreadLocal\s*<[^>]*>\s+(\w+)', code))
+    for u in lens.functions():
+        for m in _RE_TL_SET.finditer(u.body):
+            if m.group(1) not in tl_vars:
+                continue
+            # 在整个文件里找 remove，而不是只看当前方法：
+            # `UserContext.set(x)` 与 `UserContext.clear()`（里面统一 remove）是标准写法，
+            # 只看同一个方法会把这种正确实现全部报成泄漏。
+            if re.search(rf'\b{re.escape(m.group(1))}\s*\.\s*remove\s*\(', code):
+                continue
+            ln = u.line_at(m.start())
+            add(out, ctx, 'logic.java-threadlocal-leak', 'error', lens, ln,
+                f'`{m.group(1)}.set(...)` 之后没有对应的 `remove()` —— '
+                '线程池会复用线程，残留的值会被下一个请求读到（串数据），同时造成内存泄漏',
+                '用 `try { tl.set(x); … } finally { tl.remove(); }`，remove 必须在 finally 里',
+                u.label)
+            break
+
+    # ── Executors 快捷工厂：无界队列 / 无限线程，两种都是 OOM ──
+    for m in _RE_EXECUTORS.finditer(code):
+        ln = _line_of(lens, m.start())
+        why = ('队列无界（LinkedBlockingQueue 不限长），任务堆积直到 OOM'
+               if m.group(1) in ('newFixedThreadPool', 'newSingleThreadExecutor', 'newScheduledThreadPool')
+               else '线程数无上限，峰值时能把机器创建线程创建到崩')
+        add(out, ctx, 'logic.java-executors-factory', 'warn', lens, ln,
+            f'`Executors.{m.group(1)}()` —— {why}',
+            '手动 new ThreadPoolExecutor：核心/最大线程数、**有界**队列、'
+            '显式拒绝策略（CallerRuns 做背压 / Abort 快速失败）、带名字的 ThreadFactory 便于排查',
+            _unit_at(lens, ln))
+
+    # ── 日期格式里的 YYYY：它是「周年」不是「年」，跨年那一周会错一整年 ──
+    for m in _RE_WEEK_YEAR.finditer(lens.text):
+        ln = _line_of(lens, m.start())
+        line_txt = lens.line(ln)
+        if not re.search(r'(DateFormat|DateTimeFormatter|ofPattern|format|parse|pattern)', line_txt, re.I):
+            continue
+        add(out, ctx, 'logic.java-week-year', 'error', lens, ln,
+            '日期格式里用了 `YYYY`（week-based year，周年），它不是普通的年份 —— '
+            '每年跨年那一周会算成下一年，比如 2026-12-28 会格式化成 2027',
+            '改成小写 `yyyy`。这个 bug 一年只在跨年那几天出现，测试期几乎必然测不到',
+            _unit_at(lens, ln))