@huicai/cli 2026.814.0 → 2026.1021.0

package/skills/code-quality/references/languages.md

@@ -0,0 +1,107 @@
+# 分语言规则详解
+
+`code_inspect` 的通用七类对所有语言都跑；下面这三组是**语言专属**的，
+共同点是：通用规则一条也看不见，而它们恰恰是各自语言里最会出事的地方。
+
+随时可以从实现里现取完整清单（不会与本文漂移）：
+`python3 skills/code-quality/scripts/code_check.py --rules`
+
+## Java：另有 33 条专属规则
+
+Java 真正会出事的地方，通用规则几乎一条都看不见——它们的共同点是
+**编译通过、运行不报错、出事时离现场很远**：
+
+| 分组 | 抓什么 |
+|---|---|
+| 事务（`framework.tx-*`） | @Transactional 落在 private/final/static（代理包不住，**注解完全不生效**）· 抛受检异常却没写 rollbackFor（Spring 默认只回滚 RuntimeException）· 方法内 catch 住异常不再抛（异常不出方法，事务不回滚）· 事务内起新线程（事务绑在当前线程上） |
+| 代理（`framework.self-invocation`） | 同类内直接调用 @Transactional / @Async / @Cacheable 方法——走的是 this 不是代理，注解等于没写 |
+| 注入与 Bean | @Autowired 字段注入 · @Value 无默认值 · 单例 Bean 的可变实例字段 |
+| 精度与拆箱 | `new BigDecimal(double)`（0.1 会变成 0.1000000000000000055…）· BigDecimal 用 equals（2.0 ≠ 2.00）· 装箱类型用 `==`（128 以内因缓存"碰巧正确"） |
+| 并发与资源 | static SimpleDateFormat（非线程安全）· ThreadLocal.set 无 remove（线程池串数据）· Executors 快捷工厂（无界队列/无限线程都是 OOM）· 资源不在 try-with-resources |
+| 集合与语法 | Arrays.asList 后 add · for-each 里增删 · 循环内 String `+=` · 整数除法赋给 double · switch 无 default · finally 里 return · equals/hashCode 不成对 · `YYYY`（周年，跨年那周错一整年） |
+| 持久层 | MyBatis `${}` 拼接（字符串替换，注入入口） |
+| 文档与测试 | Javadoc @throws 写了但方法不抛 · assertEquals 参数顺序反了 · try/fail 断言异常 |
+
+这一组与 `dev-java` 技能里的「事务失效八景」「常见坑 TOP」是**同一件事的两面**：
+那边是评审时人要记住的，这边是每次改完代码机器都查一遍的。方法论会忘，机器不会。
+
+```
+code_inspect(path, only="framework")   # 只看 Spring/MyBatis 用法
+code_inspect(path, only="logic")       # 含 Java 语言陷阱
+```
+
+## Python：另有 30 条专属规则（走真 AST，判得最准）
+
+JS 与 Java 走的是「掩码 + 括号配对」，而 Python 有标准库 `ast`——引擎早就把整棵语法树
+解析好了。所以这一组能做**正则根本无从下手**的判断：类型层级、作用域、名字绑定。
+
+| 分组 | 抓什么 |
+|---|---|
+| 共享可变 | 类属性是 list/dict（**所有实例共享同一个**）· dataclass 可变默认 · 可变默认参数 |
+| 闭包与迭代 | 循环里定义的函数捕获循环变量（全都拿到最后一次的值）· 遍历时增删同一个容器（会跳过元素） |
+| 异常 | **`except` 顺序错**（父类在前，子类分支永远执行不到）· 宽捕获直接 pass · 窄捕获无说明 · `raise` 不带 `from`（丢原始堆栈）· finally 里 return |
+| 语义陷阱 | `is` 比较字面量（靠对象缓存，时对时错）· `== None/True` · `type(x) == T` · 遮蔽内置名 · 生产代码用 `assert`（`-O` 会整行删掉） |
+| 环境相关 | `open()` 不写 encoding（**Windows 默认 GBK**，开发机永远复现不了）· `datetime.now()` 不带时区 · `Decimal(0.1)` 浮点构造 · `os.path.join` 后段绝对路径会吞掉前缀 |
+| 异步 | async 函数里 `time.sleep`/`requests`/`open` —— 事件循环整个卡住，同循环的协程一起停 |
+| pandas | **链式赋值 `df[a][b]=x`**（改到副本，只给个 warning）· 读表不指定 dtype（前导零丢失、长编号变科学计数法且精度已丢）· `df.append`（2.0 已移除）· `iterrows` · `inplace=True` |
+| 安全 | `subprocess(shell=True)` · `yaml.load` 无 Loader · `pickle.loads` |
+
+pandas 这一组的事故形态特别值得留意：**不改变外观、只改变数字**。
+表格看上去一切正常，只是数对不上——而人盯着屏幕是看不出来的。
+
+这一组同样与 `dev-python` 技能的「常见坑 TOP」对齐：那边是评审时人要记住的，这边是机器每次都查。
+
+## JS / TS / Vue：另有 20 条专属规则
+
+JS 这边只有「掩码 + 括号配对」，没有真 AST（托管 Python 里没有可靠的 JS 解析器，
+为体检去装一个等于让它在最需要时先卡几分钟）。所以判据一律取**确定形态，拿不准不报**。
+
+| 分组 | 抓什么 |
+|---|---|
+| 异步 | **`.forEach(async …)`**（forEach 不等 Promise，循环"瞬间跑完"）· 循环内 await 串行 |
+| 空值 | **`a?.b.c`**——可选链只保护了第一层，后半段照样抛 TypeError（最常见的误用：它给人"已经防过空"的错觉） |
+| 经典陷阱 | `x === NaN`（永远 false）· `for...in` 遍历数组（拿到字符串下标 + 原型链属性）· 排数字忘了比较函数 · `delete arr[i]`（留空洞、length 不变）· `JSON.parse` 无防护 · `parseInt` 无基数 · 松散比较 |
+| TS 类型逃逸 | `as any`（这一行之后类型检查全失效）· `@ts-ignore` 无理由 · 函数返回 `any`（顺着调用链扩散） |
+| **Vue 模板** | `v-for` 无 `:key`（列表变动时输入框内容、勾选状态串到别的行）· `:key="index"`（等于没给 key）· **`v-if` 与 `v-for` 同元素**（Vue 3 里 v-if 优先级更高，循环变量还不存在）· `v-html`（XSS） |
+| Vue 脚本 | 直接改 props（单向数据流，父组件重渲染会覆盖回去）· 解构 `reactive`（响应性当场断掉） |
+
+Vue 的一半问题在 `<template>` 里。改造前解析器只抠 `<script>`，template 被整个丢弃——
+那时 `v-for` 少了 `:key` 这类最常见的问题**一条也查不到，而报告照样显示「已体检」**。
+
+这一组与 `dev-frontend` 技能对齐：那边写着「`as any` 评审必问」「列表 key 用稳定 id 禁 index」，
+这边是每次改完代码机器都查一遍。
+
+## C#：另有 20 条专属规则
+
+与 Java 同走「掩码 + 括号配对」，但坑不一样——而且好几个属于**写错了反而更像对的**：
+
+| 分组 | 抓什么 |
+|---|---|
+| 异步 | **`async void`**（异常无人能接，直接终结进程；比 `async Task` 还短）· **`.Result` / `.Wait()`**（有同步上下文时必然死锁，而控制台和单测里一切正常）· `async` 却没有 `await` |
+| 异常 | **`throw ex;`**（堆栈从这一行重新开始，原始位置丢失；正确写法 `throw;` 反而更短） |
+| 时间与精度 | `DateTime.Now`（换时区/夏令时全错）· `double` 算金额（应 `decimal`）· `Parse` 不带 IFormatProvider（德法区域小数点是逗号） |
+| 并发 | `lock(this)` / `lock(typeof(X))` / `lock("串")`（锁对象公开，外部也能锁）· `static Random`（非线程安全，并发下一起返回 0）· 事件订阅无退订 |
+| LINQ | **延迟查询被多次枚举**（每次都重跑，EF 上就是重复发 SQL）· `.Count() > 0`（应 `.Any()`） |
+| 资源 | `FileStream`/`SqlConnection` 等不走 `using` |
+| EF / DI | 循环里查库（N+1）· **DbContext 注册成 Singleton**（非线程安全 + 变更跟踪只增不减）· `FromSqlRaw` 拼接 · 手 `new HttpClient()` |
+| 测试 | **`async void` 测试方法**（框架不等它，断言没跑用例就绿了） |
+
+与 `dev-csharp` 技能的「常见坑 TOP / DI 生命周期 / async 全链」对齐。
+
+> **一条必须说明的局限**：本仓库没有 C# 代码。
+> 前四轮的误报都是在真实项目上治出来的（Java 在 836 个文件上从 237 条假必修降到个位数，
+> Python 在 94 个文件上从 136 条降到 19 条），这一组只经过压测台的合规样本验证。
+> 判据因此刻意取得比 Java 那组更保守——拿不准一律不报。
+> 接到真实 C# 项目后建议先跑一遍 `code_inspect`，按前几轮的方式治一次误报。
+
+## 为什么各套的"深度"不一样
+
+| 语言 | 解析方式 | 因此敢做的判断 |
+|---|---|---|
+| Python | 标准库 `ast`，真语法树 | 类型层级（`ValueError ⊂ Exception`）、作用域、名字绑定 |
+| Java | 掩码 + 括号配对 + 注解/字段/throws 提取 | 注解落在哪个修饰符上、字段类型、方法声明抛什么 |
+| JS/TS/Vue | 掩码 + 括号配对 | 只取**确定形态**（`.forEach(async`、`?.b.c`、`=== NaN`），拿不准不报 |
+| C# | 掩码 + 括号配对 + `[Attribute]`/字段提取 | 同 Java 的形态，但判据更保守（无真实语料验证误报） |
+
+托管 Python 里没有可靠的 JS/Java 解析器，而为了体检去装一个，
+等于让体检在最需要它的时候先卡几分钟——那样就不会有人真的去用它。