code-review

# 代码审查框架 **审查原则**：理性、客观、实际、真实、不恭维、实事求是 ## 概述 基于模块化设计的代码审查框架： 1. **通用审查流程**：所有语言通用的审查步骤和原则 2. **语言规则引用**：按需加载语言特定审查规则 3. **组合审查支持**：支持多语言混合项目 **优势**：减少LLM上下文负担（按需加载）、维护简单、扩展灵活、复用性强。 ## 语言支持 ### 直接源码文件 | 语言 | 文件类型 | 规范文件 | |------------|-------------------------------|-------------------| | Java | `*.java` | `spec.java.md` | | Python | `*.py` | `spec.python.md` | | C++ | `*.cpp *.hpp *.cxx *.hxx *.h` | `spec.cpp.md` | | Rust | `*.rs` | `spec.rust.md` | | Kotlin | `*.kt *.kts` | `spec.kotlin.md` | | ANSI C | `*.c *.h` | `spec.ansi_c.md` | | JavaScript | `*.js *.mjs *.cjs` | `spec.js.md` | | TypeScript | `*.ts *.tsx *.mts *.cts` | `spec.js.md` | | Shell | `*.sh *.bash *.zsh` | `spec.shell.md` | **加载指令**： ```text Read ${AI_SPEC_ROOT}/lang-spec/spec.{lang}.md Read ${AI_SPEC_ROOT}/lang-spec/review.{lang}.md ``` ### SQL 来源（需拼接提取） | 来源类型 | 文件/位置 | 审查要点 | |----------------|------------------|--------------------| | SQL文件 | `*.sql` | SQL注入、性能、索引| | MyBatis Mapper | `**/*Mapper.xml` | `$`符号拼接风险 | | 内嵌SQL | 各种源码 | 正则匹配审查 | ## 审查模式 ### 1. 全量审查（默认） 遍历项目所有源代码文件，自动识别语言并加载对应规则。 ### 2. 增量审查 根据 git/svn diff 进行增量审查。 ### 3. 混合语言审查 对于多语言项目，按文件类型加载不同规则。 ## 审查流程 1. **项目分析**：识别技术栈、主要语言、项目结构 2. **规则加载**：根据语言加载对应规则集，应用通用审查框架 3. **代码遍历**：遍历所有源代码文件，理解代码结构和意图 4. **执行审查**：应用通用规则 + 语言特定规则，记录问题和建议 5. **生成报告**：汇总结果，输出审查报告 ## 通用审查规则 ### 安全规则 - **敏感信息泄露**：硬编码的密码、密钥、API Key - **SQL注入风险**：字符串拼接的SQL语句 - **XSS漏洞**：用户输入未转义 - **敏感数据内存残留**：内存中敏感数据未安全清除 ### 中间件消息追踪规则（强制） - **消息通道清单**：检索所有中间件的 Topic/Group/Queue 名称 - **跨应用数据流**：追踪数据在应用间的流动路径（生产者→消费者） - **幽灵通道检测**：只有生产者没有消费者的 Topic/Queue - **孤儿通道检测**：只有消费者没有生产者的 Topic/Queue - **消息体格式记录**：记录消息体关键字段和结构 ### 性能规则 - **资源泄漏**：文件句柄、数据库连接、网络连接未关闭 - **内存泄漏**：动态分配的内存未释放 - **循环性能**：嵌套循环、N+1查询 - **对象创建**：循环中不必要的对象实例化 ### 代码质量规则 - **重复代码**、**方法长度**（> 50行）、**圈复杂度**、**命名规范** ### 并发安全规则 - **线程安全**、**死锁风险**、**优雅退出** ### 坏味道分类 详见 [templates/code-smells.md](templates/code-smells.md)：8 大类 50+ 种。 ### AI 生成代码特有审查 **必查项**：安全漏洞、零测试覆盖、性能陷阱 **建议项**：代码规范、错误处理、配置管理 **可忽略项**：个人风格差异 关键检查点：零测试覆盖、过度复杂化、魔法字符串/数字、缺少错误处理、性能陷阱、安全漏洞、硬编码配置、不符合团队规范、注释质量、过度抽象。 ### 数据库审查规则 详见 [templates/database-review.md](templates/database-review.md)：SQL安全性、SQL性能、表结构设计、数据库架构。 ## 审查输出 ### 文件命名规范 ```text docs/review/code-review-{yyyymmdd}-{seq%000}-{lang}.md ``` ### 报告模板 详见 [templates/report-full.md](templates/report-full.md) ### 语言规则文件模板 详见 [templates/lang-rule.md](templates/lang-rule.md) ## 审查执行器 ### 单语言项目 1. 加载语言规则：`Read ${AI_SPEC_ROOT}/lang-spec/spec.{lang}.md` 2. 应用通用框架（安全/性能/代码质量审查） 3. 应用语言特定规则（语法/最佳实践/并发模式） 4. 生成报告：`docs/review/code-review-{yyyymmdd}-{seq%000}.md` ### 多语言项目 按文件类型分组，每组加载对应语言规则后执行审查。 ## 扩展和维护 ### 新增语言支持 1. 创建规则文件：`${AI_SPEC_ROOT}/lang-spec/spec.{new_lang}.md` 2. 更新本文件"语言支持"部分 ### 规则更新 - 语言规则独立更新，互不影响 - 通用框架独立更新，所有语言受益 - 向后兼容 ## 最佳实践 - **上下文优化**：按需加载语言规则，缓存常用规则 - **规则设计**：语言规则聚焦特有内容，通用规则放框架 - **审查效率**：优先严重问题，批量处理相同模式 - **报告质量**：问题定位到文件路径:行号，区分严重等级 ## AST 自动审查规则（ast-grep-mcp） 当 ast-grep-mcp 可用时，优先使用 `find_code_by_rule` 自动扫描以下规则，替代人工 grep/rg 遍历。 ### 安全规则 **硬编码敏感信息**： ``` find_code_by_rule( project_folder: "<project_root>", yaml: ''' id: hardcoded-secret language: java rule: pattern: 'String $VAR = "$VAL";' constraints: VAR: regex: '(?i)(password|secret|key|token|api_key|apikey|access_key|private_key)' ''' ) ``` **SQL 注入风险**：复用 `sql-extract` 技能的 rule，参见 `sql-extract/templates/recipes.md`。 ### 性能规则 **资源泄漏（JDBC Statement 未关闭）**： ``` find_code_by_rule( project_folder: "<project_root>", yaml: ''' id: jdbc-resource-leak language: java rule: pattern: '$TYPE $VAR = $CONN.createStatement()' ''' ) ``` **System.out.println（生产代码）**： ``` find_code_by_rule( project_folder: "<project_root>", yaml: ''' id: system-out-print language: java rule: any: - pattern: 'System.out.println($$$ARGS)' - pattern: 'System.out.print($$$ARGS)' ''' ) ``` **e.printStackTrace（生产代码）**： ``` find_code_by_rule( project_folder: "<project_root>", yaml: ''' id: print-stack-trace language: java rule: pattern: '$E.printStackTrace()' ''' ) ``` ### 代码质量规则 **空 catch 块**： ``` find_code_by_rule( project_folder: "<project_root>", yaml: ''' id: empty-catch language: java rule: pattern: 'catch ($TYPE $VAR) {}' ''' ) ``` > **注意**：多行空 catch 块（`{` 和 `}` 不在同一行）需用 `find_code(pattern: 'catch ($TYPE $VAR) {')` 辅助定位。 ### 使用方式 1. 在"代码遍历"步骤中，先调用上述 `find_code_by_rule` 自动扫描 2. 将命中结果纳入审查报告，标注文件路径和行号 3. 人工复核命中结果，排除误报 4. MCP 不可用时回退到 grep/rg 人工遍历 ### MCP 限制 - 不支持 XML 语言（MyBatis mapper 需用 rg 兜底） - 不支持 `--globs` 排除目录（需限定 `project_folder` 或人工过滤） - 大型项目（>10k 文件）可能超时，需分目录搜索或回退 CLI ## 与其他技能集成 | 技能 | 用途 | |----------------------|------------------| | `lets-loop` | 循环性能专项审查 | | `code-detect-dup` | 重复代码专项检测 | | `code-detect-problem`| 项目层面问题检测 | | `sql-extract` | SQL 注入风险点抽取（ast-grep-mcp 联动） |