AI 驱动的代码审查与提交规范实践指南

前言

在现代软件开发中，代码质量和提交规范是保证项目可维护性的关键因素。本文将介绍一套基于 AI 辅助的代码审查与提交规范实践方案，通过自动化工具和标准化流程，提升开发效率和代码质量。

一、核心价值

1.1 为什么需要自动化代码审查？

一致性：确保所有代码都遵循相同的质量标准
效率：减少人工审查时间，快速发现常见问题
学习：帮助团队成员养成良好的编码习惯
风险控制：在提交前发现潜在的安全和性能问题

1.2 Conventional Commits 规范的价值

可追溯性：清晰的提交历史便于问题定位
自动化：支持基于提交类型的自动化流程（如自动生成 CHANGELOG）
团队协作：统一的提交格式提升团队协作效率

二、配置指南

2.1 什么是 .cursorrules 文件？

.cursorrules 是 Cursor IDE 的配置文件，用于定义 AI 助手的行为规则。通过配置此文件，可以让 AI 助手按照团队的开发规范和最佳实践来工作。

2.2 如何配置？

步骤 1：创建 .cursorrules 文件

在项目根目录下创建 .cursorrules 文件：

# 在项目根目录执行
touch .cursorrules

步骤 2：添加规则内容

将以下完整的 AI 快捷指令规则复制到 .cursorrules 文件中：

# AI 快捷指令规则

## Commit 相关指令

当用户说以下指令时，执行对应操作：

1. **"commit"** 或 **"cz"**

   - 分析当前 git 变更（通过 git status 和 git diff）
   - **执行 Code Review 检查清单**
   - 自动生成符合 Conventional Commits 规范的 commit message
   - 提供完整的 commit message 建议，包括 type、scope、subject、body

2. **"commit:feat"**

   - 自动识别新功能相关的变更
   - **执行 Code Review 检查清单**
   - 生成 feat 类型的 commit message

3. **"commit:fix"**

   - 自动识别 bug 修复相关的变更
   - **执行 Code Review 检查清单**
   - 生成 fix 类型的 commit message

4. **"commit:refactor"**

   - 自动识别重构相关的变更
   - **执行 Code Review 检查清单**
   - 生成 refactor 类型的 commit message

5. **"commit:docs"**

   - 自动识别文档相关的变更
   - 生成 docs 类型的 commit message

6. **"commit:style"**

   - 自动识别代码格式相关的变更（不影响代码运行的变动）
   - 生成 style 类型的 commit message

7. **"commit:test"**

   - 自动识别测试相关的变更
   - 生成 test 类型的 commit message

8. **"commit:chore"**
   - 自动识别构建过程或辅助工具的变动
   - 生成 chore 类型的 commit message

## 格式化指令

9. **"format"** 或 **"fmt"**

   - 执行 Prettier 格式化所有代码
   - 命令：npm run format 或 yarn format

10. **"format:check"**
    - 检查代码格式是否符合规范
    - 命令：npm run format:check 或 yarn format:check

## 组合指令

11. **"precommit"** 或 **"prep"**
    - 执行格式化 → 检查格式 → **执行 Code Review 检查清单** → 分析变更 → 生成 commit message 建议
    - 完整的工作流：format → format:check → code review → commit 分析

## 执行规则

- 当用户说 "commit" 时，我应该：

  1. 先运行 `git status` 查看变更状态
  2. 运行 `git diff` 分析具体变更内容
  3. **执行 Code Review 检查清单（详见下方）**
  4. 根据变更内容智能判断 commit type
  5. 生成符合 Conventional Commits 规范的完整 commit message
  6. 提供可以直接使用的 commit message
  7. 最后执行建议的 commit（使用生成的 commit message 执行 `git commit -m "生成的message"`）

- 当用户说 "format" 时，我应该：

  1. 执行 `yarn format` 或 `npm run format`
  2. 格式化所有匹配的文件

- 当用户说 "precommit" 时，我应该：
  1. 执行格式化
  2. 检查格式
  3. **执行 Code Review 检查清单（详见下方）**
  4. 分析 git 变更
  5. 生成 commit message 建议
  6. 最后执行建议的 commit（使用生成的 commit message 执行 `git commit -m "生成的message"`）

## ✅ 业界标准 Code Review 检查清单

在执行 commit 相关指令时，必须对变更的代码进行以下检查，并给出详细的检查报告：

### 功能

- [ ] **代码实现符合需求**

  - 检查代码是否实现了预期的功能
  - 验证业务逻辑是否正确
  - 确认没有遗漏的功能点

- [ ] **边界情况已处理**

  - 检查空值、null、undefined 的处理
  - 检查数组/对象为空的情况
  - 检查数值边界（最大值、最小值、0、负数等）
  - 检查字符串边界（空字符串、超长字符串等）

- [ ] **错误处理完善**
  - 检查是否有 try-catch 或错误处理机制
  - 检查 API 调用是否有错误处理
  - 检查是否有用户友好的错误提示
  - 检查错误日志是否完善

### 代码质量

- [ ] **命名清晰易懂**

  - 检查变量、函数、类名是否语义清晰
  - 检查是否使用了有意义的命名（避免 a、b、temp 等）
  - 检查命名是否符合项目规范（驼峰、下划线等）

- [ ] **函数职责单一**

  - 检查函数是否只做一件事
  - 检查函数是否过长（建议不超过 50 行）
  - 检查是否有可以拆分的复杂函数

- [ ] **没有重复代码**

  - 检查是否有重复的逻辑可以提取
  - 检查是否有可以复用的函数
  - 检查是否有重复的常量定义

- [ ] **注释适当（解释 why，不是 what）**
  - 检查复杂逻辑是否有注释说明
  - 检查注释是否解释了"为什么"而不是"是什么"
  - 检查是否有过时的注释需要更新
  - 检查是否有 TODO/FIXME 需要处理

### 性能

- [ ] **没有不必要的渲染**

  - 检查 Vue/React 组件是否有不必要的重新渲染
  - 检查是否使用了 useMemo、useCallback、computed 等优化
  - 检查列表渲染是否使用了 key
  - 检查是否有可以优化的条件渲染

- [ ] **没有内存泄漏**

  - 检查是否有未清理的事件监听器
  - 检查是否有未清理的定时器
  - 检查是否有未取消的异步请求
  - 检查组件卸载时是否正确清理资源

- [ ] **异步操作正确处理**
  - 检查 async/await 是否正确使用
  - 检查 Promise 的错误处理
  - 检查是否有竞态条件（race condition）
  - 检查 loading 状态是否正确管理

### 安全

- [ ] **没有 XSS 风险**

  - 检查用户输入是否进行了转义
  - 检查是否使用了 v-html 或 dangerouslySetInnerHTML（需要验证内容安全）
  - 检查 URL 参数是否进行了验证
  - 检查是否使用了安全的 DOM 操作方法

- [ ] **敏感信息未暴露**

  - 检查代码中是否硬编码了密码、密钥、token
  - 检查 console.log 是否暴露了敏感信息
  - 检查错误信息是否暴露了系统内部信息
  - 检查 API 响应是否过滤了敏感字段

- [ ] **输入验证完善**
  - 检查用户输入是否进行了验证
  - 检查表单验证是否完善
  - 检查 API 参数是否进行了验证
  - 检查是否有 SQL 注入、命令注入等风险

### 测试

- [ ] **单元测试覆盖**

  - 检查核心业务逻辑是否有单元测试
  - 检查工具函数是否有测试
  - 检查测试覆盖率是否足够

- [ ] **边界情况测试**
  - 检查是否测试了边界情况
  - 检查是否测试了错误情况
  - 检查是否测试了异常流程

## Code Review 执行方式

在执行 Code Review 时，我应该：
1. 读取所有变更的文件（通过 git diff 获取）
2. 对每个文件进行逐项检查
3. 生成详细的检查报告，格式如下：
   ```
   ## Code Review 报告
   
   ### ✅ 通过项
   - [x] 代码实现符合需求
   - [x] 命名清晰易懂
   
   ### ⚠️ 需要注意项
   - [ ] 边界情况处理：建议添加空值检查
   - [ ] 错误处理：建议添加 try-catch
   
   ### ❌ 必须修复项
   - [ ] 安全风险：发现硬编码的 API key
   - [ ] 内存泄漏：事件监听器未清理
   ```
4. 如果有必须修复项（❌），应该阻止提交并提示用户修复
5. 如果只有需要注意项（⚠️），可以提示用户但允许提交
6. 所有检查通过后，才继续执行 commit 流程

## Conventional Commits 规范

commit message 格式：
```
<type>(<scope>): <subject>

<body>

<footer>
```

类型说明：
- feat: 新功能
- fix: 修复 bug
- docs: 文档变更
- style: 代码格式（不影响代码运行的变动）
- refactor: 重构（既不是新增功能，也不是修复 bug）
- perf: 性能优化
- test: 增加测试
- chore: 构建过程或辅助工具的变动
- ci: CI 配置文件和脚本的变更
- build: 影响构建系统或外部依赖的变更
- revert: 回滚

步骤 3：验证配置

配置完成后，重启 Cursor IDE 或重新加载窗口，使配置生效。之后，你就可以在 Cursor 中使用这些快捷指令了。

2.3 配置说明

文件位置

文件路径：项目根目录下的 .cursorrules
文件格式：Markdown 格式（.md 扩展名可选）
编码：建议使用 UTF-8 编码

自定义规则

你可以根据团队的实际需求，对规则进行自定义：

修改检查清单：根据项目特点调整 Code Review 检查项
添加自定义指令：定义团队特有的快捷指令
调整执行流程：根据项目需求修改指令的执行步骤

团队共享

建议将 .cursorrules 文件提交到版本控制系统（如 Git），这样团队成员都可以使用相同的规则：

# 将 .cursorrules 添加到版本控制
git add .cursorrules
git commit -m "docs: 添加 AI 快捷指令规则配置"

2.4 快速开始

复制规则：将上述完整的规则内容复制到 .cursorrules 文件
重启 IDE：重启 Cursor IDE 使配置生效
测试指令：尝试使用 commit 或 format 指令验证配置是否生效

三、快捷指令系统

3.1 Commit 相关指令

基础提交指令

commit 或 cz

自动分析当前 git 变更
执行完整的 Code Review 检查清单
智能生成符合 Conventional Commits 规范的 commit message
提供包含 type、scope、subject、body 的完整提交信息

使用场景：日常开发中的常规提交

类型化提交指令

根据不同的变更类型，提供专门的提交指令：

commit:feat - 新功能提交
- 自动识别新功能相关的变更
- 执行 Code Review 检查清单
- 生成 feat 类型的 commit message
commit:fix - Bug 修复提交
- 自动识别 bug 修复相关的变更
- 执行 Code Review 检查清单
- 生成 fix 类型的 commit message
commit:refactor - 重构提交
- 自动识别重构相关的变更
- 执行 Code Review 检查清单
- 生成 refactor 类型的 commit message
commit:docs - 文档变更提交
- 自动识别文档相关的变更
- 生成 docs 类型的 commit message
commit:style - 代码格式提交
- 自动识别代码格式相关的变更（不影响代码运行的变动）
- 生成 style 类型的 commit message
commit:test - 测试相关提交
- 自动识别测试相关的变更
- 生成 test 类型的 commit message
commit:chore - 构建工具变更提交
- 自动识别构建过程或辅助工具的变动
- 生成 chore 类型的 commit message

3.2 格式化指令

format 或 fmt

执行 Prettier 格式化所有代码
命令：npm run format 或 yarn format
确保代码风格统一

format:check

检查代码格式是否符合规范
命令：npm run format:check 或 yarn format:check
在 CI/CD 流程中使用，不修改文件

3.3 组合指令

precommit 或 prep - 完整提交流程

这是最强大的指令，执行完整的工作流：

格式化：自动格式化所有代码
格式检查：验证格式是否符合规范
Code Review：执行完整的代码审查检查清单
变更分析：分析 git 变更内容
生成提交信息：智能生成 commit message
执行提交：使用生成的 commit message 执行提交

使用场景：提交前的最后检查，确保代码质量和提交规范

四、执行流程详解

4.1 Commit 指令执行流程

当执行 commit 指令时，系统会按以下步骤执行：

1. git status          → 查看变更状态
2. git diff            → 分析具体变更内容
3. Code Review         → 执行代码审查检查清单
4. 智能判断类型        → 根据变更内容判断 commit type
5. 生成提交信息        → 生成符合规范的 commit message
6. 提供建议            → 展示完整的 commit message
7. 执行提交            → 使用生成的 message 执行 git commit

4.2 Precommit 指令执行流程

当执行 precommit 指令时，系统会按以下步骤执行：

1. 格式化代码          → yarn format / npm run format
2. 检查格式            → yarn format:check / npm run format:check
3. Code Review         → 执行完整的代码审查检查清单
4. 分析 git 变更       → git status + git diff
5. 生成提交信息        → 智能生成 commit message
6. 执行提交            → 使用生成的 message 执行 git commit

五、业界标准 Code Review 检查清单

5.1 功能检查

✅ 代码实现符合需求

检查代码是否实现了预期的功能
验证业务逻辑是否正确
确认没有遗漏的功能点

✅ 边界情况已处理

空值处理：检查 null、undefined 的处理
集合边界：检查数组/对象为空的情况
数值边界：检查最大值、最小值、0、负数等边界值
字符串边界：检查空字符串、超长字符串等情况

✅ 错误处理完善

检查是否有 try-catch 或错误处理机制
检查 API 调用是否有错误处理
检查是否有用户友好的错误提示
检查错误日志是否完善

5.2 代码质量检查

✅ 命名清晰易懂

检查变量、函数、类名是否语义清晰
避免使用无意义的命名（如 a、b、temp 等）
检查命名是否符合项目规范（驼峰、下划线等）

✅ 函数职责单一

检查函数是否只做一件事（单一职责原则）
检查函数是否过长（建议不超过 50 行）
检查是否有可以拆分的复杂函数

✅ 没有重复代码

检查是否有重复的逻辑可以提取
检查是否有可以复用的函数
检查是否有重复的常量定义

✅ 注释适当

检查复杂逻辑是否有注释说明
重要：注释应该解释"为什么"而不是"是什么"
检查是否有过时的注释需要更新
检查是否有 TODO/FIXME 需要处理

5.3 性能检查

✅ 没有不必要的渲染

Vue/React 组件：检查是否有不必要的重新渲染
性能优化：检查是否使用了 useMemo、useCallback、computed 等优化
列表渲染：检查是否使用了 key
条件渲染：检查是否有可以优化的条件渲染

✅ 没有内存泄漏

检查是否有未清理的事件监听器
检查是否有未清理的定时器
检查是否有未取消的异步请求
检查组件卸载时是否正确清理资源

✅ 异步操作正确处理

检查 async/await 是否正确使用
检查 Promise 的错误处理
检查是否有竞态条件（race condition）
检查 loading 状态是否正确管理

5.4 安全检查

✅ 没有 XSS 风险

检查用户输入是否进行了转义
检查是否使用了 v-html 或 dangerouslySetInnerHTML（需要验证内容安全）
检查 URL 参数是否进行了验证
检查是否使用了安全的 DOM 操作方法

✅ 敏感信息未暴露

检查代码中是否硬编码了密码、密钥、token
检查 console.log 是否暴露了敏感信息
检查错误信息是否暴露了系统内部信息
检查 API 响应是否过滤了敏感字段

✅ 输入验证完善

检查用户输入是否进行了验证
检查表单验证是否完善
检查 API 参数是否进行了验证
检查是否有 SQL 注入、命令注入等风险

5.5 测试检查

✅ 单元测试覆盖

检查核心业务逻辑是否有单元测试
检查工具函数是否有测试
检查测试覆盖率是否足够

✅ 边界情况测试

检查是否测试了边界情况
检查是否测试了错误情况
检查是否测试了异常流程

六、Code Review 报告格式

系统会生成标准化的 Code Review 报告，格式如下：

## Code Review 报告

### ✅ 通过项

- [x] 代码实现符合需求
- [x] 命名清晰易懂
- [x] 函数职责单一

### ⚠️ 需要注意项

- [ ] 边界情况处理：建议添加空值检查
- [ ] 错误处理：建议添加 try-catch
- [ ] 性能优化：建议使用 useMemo 优化计算

### ❌ 必须修复项

- [ ] 安全风险：发现硬编码的 API key
- [ ] 内存泄漏：事件监听器未清理
- [ ] 错误处理：API 调用缺少错误处理

6.1 报告处理规则

必须修复项（❌）：阻止提交，提示用户修复后再提交
需要注意项（⚠️）：提示用户，但允许提交
通过项（✅）：所有检查通过后，继续执行 commit 流程

七、Conventional Commits 规范

7.1 提交信息格式

<type>(<scope>): <subject>

<body>

<footer>

7.2 类型说明

类型	说明	示例
`feat`	新功能	`feat(auth): 添加用户登录功能`
`fix`	修复 bug	`fix(api): 修复用户信息获取失败的问题`
`docs`	文档变更	`docs(readme): 更新安装说明`
`style`	代码格式（不影响代码运行的变动）	`style(component): 格式化代码`
`refactor`	重构（既不是新增功能，也不是修复 bug）	`refactor(utils): 重构工具函数`
`perf`	性能优化	`perf(chart): 优化图表渲染性能`
`test`	增加测试	`test(api): 添加用户接口测试`
`chore`	构建过程或辅助工具的变动	`chore(deps): 更新依赖包版本`
`ci`	CI 配置文件和脚本的变更	`ci(github): 添加 GitHub Actions 配置`
`build`	影响构建系统或外部依赖的变更	`build(webpack): 更新 webpack 配置`
`revert`	回滚	`revert: 回滚提交 abc123`

7.3 最佳实践

Subject（主题）：
- 使用祈使句，首字母小写
- 不超过 50 个字符
- 不以句号结尾
Body（正文）：
- 解释"为什么"而不是"是什么"
- 说明变更的动机和与之前行为的对比
Scope（范围）：
- 可选，表示影响的范围
- 如：feat(auth), fix(api), refactor(utils)

八、实施建议

8.1 团队推广

培训阶段：向团队介绍这套规范和工具
试用阶段：在小范围内试用，收集反馈
推广阶段：逐步推广到整个团队
持续优化：根据团队实际情况调整检查清单

8.2 工具集成

IDE 插件：在 IDE 中集成快捷指令
Git Hooks：使用 pre-commit hook 自动执行检查
CI/CD：在持续集成流程中加入格式检查和代码审查

8.3 持续改进

定期回顾：定期回顾检查清单的有效性
收集反馈：收集开发者的使用反馈
优化规则：根据项目特点优化检查规则
更新文档：保持文档与实际情况同步

九、总结

通过这套 AI 驱动的代码审查与提交规范实践方案，我们可以：

✅ 提升代码质量：通过自动化检查发现潜在问题
✅ 统一提交规范：确保提交历史清晰可追溯
✅ 提高开发效率：减少人工审查时间
✅ 降低项目风险：在提交前发现安全和性能问题
✅ 培养良好习惯：帮助团队成员养成良好的编码习惯

这套方案不仅是一套工具，更是一种开发文化和最佳实践的体现。通过持续的使用和改进，它将帮助团队构建更高质量、更易维护的软件项目。

posted @ 2025-12-03 16:54 一尘子! 阅读(3) 评论(0) 收藏举报

刷新页面返回顶部

道法自然

一言半句便通玄，何须丹经千万篇。 人若不为形所困，眼前便是大罗天。