forked from Gitlink/gitlink-cli
408 lines
10 KiB
Markdown
408 lines
10 KiB
Markdown
# 全面审查工作流示例
|
||
|
||
本文档展示一个完整的代码审查工作流，包括数据获取、AI 分析、报告生成和评论集成。
|
||
|
||
## 📋 场景描述
|
||
|
||
**场景**: Reviewer 需要对一个 PR 进行全面的代码审查，包括代码质量、安全性、性能等多个维度。
|
||
|
||
**目标**:
|
||
1. 获取完整的 PR 代码变更数据
|
||
2. 使用 AI 进行多维度代码分析
|
||
3. 生成结构化的审查报告
|
||
4. 将审查意见添加为 PR 评论
|
||
|
||
## 🔄 工作流程
|
||
|
||
```
|
||
开始全面审查
|
||
↓
|
||
1. 获取 PR 基本信息
|
||
├─ 获取 PR 详情
|
||
├─ 获取变更文件列表
|
||
└─ 获取 diff 内容
|
||
↓
|
||
2. 数据预处理
|
||
├─ 过滤无关文件
|
||
├─ 提取代码片段
|
||
└─ 组织分析数据
|
||
↓
|
||
3. AI 代码分析
|
||
├─ 代码质量检查
|
||
├─ 安全性检查
|
||
├─ 性能检查
|
||
└─ 可维护性检查
|
||
↓
|
||
4. 生成审查报告
|
||
├─ 汇总分析结果
|
||
├─ 按优先级排序问题
|
||
└─ 生成改进建议
|
||
↓
|
||
5. 输出审查报告
|
||
├─ 打印 JSON 格式（AI 解析）
|
||
└─ 打印 Markdown 格式（人类阅读）
|
||
↓
|
||
6. （可选）添加评论到 PR
|
||
↓
|
||
完成
|
||
```
|
||
|
||
## 🔧 实施步骤
|
||
|
||
### 步骤 1：获取 PR 基本信息
|
||
|
||
```bash
|
||
# 1.1 获取 PR 详情
|
||
gitlink-cli pr +view --id 123 --format json > pr_info.json
|
||
|
||
# 1.2 获取变更文件列表
|
||
gitlink-cli pr +files --id 123 --format json > pr_files.json
|
||
|
||
# 1.3 获取 diff 内容
|
||
gitlink-cli pr +diff --id 123 --format json > pr_diff.json
|
||
|
||
# 验证数据获取成功
|
||
echo "=== PR 信息 ===" && cat pr_info.json | jq '.ok'
|
||
echo "=== 变更文件 ===" && cat pr_files.json | jq '.data.total_files'
|
||
echo "=== Diff 大小 ===" && cat pr_diff.json | jq '.data | length'
|
||
```
|
||
|
||
### 步骤 2：数据预处理
|
||
|
||
```bash
|
||
# 2.1 过滤代码文件（排除二进制、配置、文档文件）
|
||
cat pr_files.json | jq '.data.files[] |
|
||
select(.filename | test("\\.(go|js|ts|py|java|rb)$"))' > code_files.json
|
||
|
||
# 2.2 统计代码文件
|
||
CODE_FILES_COUNT=$(cat code_files.json | jq 'length')
|
||
echo "代码文件数: $CODE_FILES_COUNT"
|
||
|
||
# 2.3 提取主要变更文件
|
||
cat pr_files.json | jq '.data.files |
|
||
map(select(.changes > 10)) |
|
||
sort_by(.changes) | reverse' > main_changes.json
|
||
```
|
||
|
||
### 步骤 3：准备 AI 分析数据
|
||
|
||
```bash
|
||
# 3.1 组织分析数据
|
||
cat > analysis_input.json <<EOF
|
||
{
|
||
"pr_info": $(cat pr_info.json | jq '.data'),
|
||
"files": $(cat pr_files.json | jq '.data.files'),
|
||
"diff": $(cat pr_diff.json | jq -r '.data.diff')
|
||
}
|
||
EOF
|
||
|
||
# 3.2 验证数据格式
|
||
cat analysis_input.json | jq '.'
|
||
```
|
||
|
||
### 步骤 4：AI 代码分析（使用 Claude）
|
||
|
||
**方式 1：使用 Claude Code（推荐）**
|
||
|
||
```
|
||
用户: "请分析 PR #123 的代码变更，检查代码质量、安全性和性能问题"
|
||
|
||
AI Agent 将：
|
||
1. 读取 analysis_input.json
|
||
2. 分析代码质量和潜在问题
|
||
3. 生成结构化的审查报告
|
||
4. 输出 JSON 和 Markdown 格式报告
|
||
```
|
||
|
||
**方式 2：使用 Claude API**
|
||
|
||
```bash
|
||
# 调用 Claude API 进行代码分析
|
||
curl https://api.anthropic.com/v1/messages \
|
||
-H "x-api-key: $ANTHROPIC_API_KEY" \
|
||
-H "anthropic-version: 2023-06-01" \
|
||
-H "content-type: application/json" \
|
||
-d '{
|
||
"model": "claude-3-5-sonnet-20240620",
|
||
"max_tokens": 4096,
|
||
"messages": [
|
||
{
|
||
"role": "user",
|
||
"content": "请分析以下 PR 的代码变更，检查代码质量、安全性和性能问题。输出 JSON 格式的审查报告。\n\nPR 数据：\n'$(cat analysis_input.json)'"
|
||
}
|
||
]
|
||
}' > analysis_result.json
|
||
```
|
||
|
||
### 步骤 5：生成审查报告
|
||
|
||
```bash
|
||
# 5.1 提取 JSON 报告
|
||
cat analysis_result.json | jq -r '.content' > review_report.json
|
||
|
||
# 5.2 生成 Markdown 报告
|
||
cat analysis_result.json | jq -r '.content' > review_report.md
|
||
|
||
# 5.3 验证报告格式
|
||
cat review_report.json | jq '.overall_assessment'
|
||
cat review_report.md | head -50
|
||
```
|
||
|
||
### 步骤 6：输出审查报告
|
||
|
||
```bash
|
||
# 6.1 打印概要信息
|
||
echo "=== 代码审查报告 ==="
|
||
echo "PR ID: $(cat pr_info.json | jq -r '.data.project_issues_index')"
|
||
echo "总体评分: $(cat review_report.json | jq -r '.overall_assessment.total_score')/100"
|
||
echo "质量评分: $(cat review_report.json | jq -r '.overall_assessment.quality_score')/100"
|
||
echo "安全评分: $(cat review_report.json | jq -r '.overall_assessment.security_score')/100"
|
||
|
||
# 6.2 打印问题列表
|
||
echo -e "\n=== 发现的问题 ==="
|
||
cat review_report.json | jq -r '.issues[] |
|
||
"\(.severity) - \(.category): \(.file):\(.line)"'
|
||
|
||
# 6.3 打印优秀实践
|
||
echo -e "\n=== 优秀实践 ==="
|
||
cat review_report.json | jq -r '.positive_notes[] |
|
||
"⭐ \(.file):\(.line) - \(.description)"'
|
||
|
||
# 6.4 打印改进建议
|
||
echo -e "\n=== 改进建议 ==="
|
||
cat review_report.json | jq -r '.recommendations[]' | nl
|
||
```
|
||
|
||
### 步骤 7：（可选）添加评论到 PR
|
||
|
||
```bash
|
||
# 7.1 添加总评
|
||
gitlink-cli api POST /:owner/:repo/pulls/123/reviews --body "{
|
||
\"body\": \"$(cat review_report.md)\",
|
||
\"event\": \"COMMENT\"
|
||
}"
|
||
|
||
# 7.2 批量添加行内评论
|
||
cat review_report.json | jq -r '.issues[] |
|
||
"gitlink-cli api POST /:owner/:repo/pulls/123/comments --body '"'"'{
|
||
\"body\": \"\(.suggestion)\",
|
||
\"path\": \"\(.file)\",
|
||
\"position\": \(.line)
|
||
}'"'"'"' | bash
|
||
```
|
||
|
||
## 📊 审查报告示例
|
||
|
||
### JSON 格式报告
|
||
|
||
```json
|
||
{
|
||
"pr_info": {
|
||
"id": 123,
|
||
"title": "Feature: Add user authentication",
|
||
"author": "developer",
|
||
"branch": "feature/auth → main"
|
||
},
|
||
"overall_assessment": {
|
||
"total_score": 75,
|
||
"quality_score": 85,
|
||
"security_score": 60,
|
||
"performance_score": 75,
|
||
"maintainability_score": 80,
|
||
"status": "NEEDS_IMPROVEMENTS"
|
||
},
|
||
"issues": [
|
||
{
|
||
"id": 1,
|
||
"severity": "HIGH",
|
||
"category": "security",
|
||
"file": "src/auth/login.go",
|
||
"line": 45,
|
||
"rule": "SQL Injection",
|
||
"description": "直接拼接用户输入到 SQL 语句",
|
||
"suggestion": "使用参数化查询或 ORM"
|
||
}
|
||
],
|
||
"positive_notes": [
|
||
{
|
||
"file": "src/auth/user.go",
|
||
"line": 120,
|
||
"description": "优秀的错误处理"
|
||
}
|
||
],
|
||
"recommendations": [
|
||
"修复 SQL 注入漏洞",
|
||
"添加输入验证",
|
||
"完善单元测试"
|
||
]
|
||
}
|
||
```
|
||
|
||
### Markdown 格式报告
|
||
|
||
```markdown
|
||
# 代码审查报告
|
||
|
||
## PR 信息
|
||
- **PR ID**: 123
|
||
- **标题**: Feature: Add user authentication
|
||
- **作者**: @developer
|
||
- **分支**: feature/auth → main
|
||
- **变更**: 3 个文件，+135 / -22 行
|
||
|
||
## 总体评分: 75/100 ⭐⭐⭐
|
||
|
||
### 评分详情
|
||
- 代码质量: 85/100 ✅
|
||
- 安全性: 60/100 ⚠️
|
||
- 性能: 75/100 ✅
|
||
- 可维护性: 80/100 ✅
|
||
|
||
## 🔴 高优先级问题（1）
|
||
|
||
### 1. SQL 注入漏洞
|
||
- **文件**: `src/auth/login.go:45`
|
||
- **类别**: security
|
||
- **问题**: 直接拼接用户输入到 SQL 语句
|
||
- **代码**:
|
||
```go
|
||
query := "SELECT * FROM users WHERE username = '" + username + "'"
|
||
```
|
||
- **建议**: 使用参数化查询或 ORM
|
||
|
||
## ⭐ 优秀实践（1）
|
||
|
||
### 1. 优秀的错误处理
|
||
- **文件**: `src/auth/user.go:120`
|
||
- **描述**: 完善的错误处理和日志记录
|
||
|
||
## 💡 改进建议
|
||
|
||
1. 修复 SQL 注入漏洞
|
||
2. 添加输入验证
|
||
3. 完善单元测试
|
||
|
||
## 📝 总结
|
||
|
||
代码整体质量良好，但存在 1 个需要立即修复的安全问题。建议修复后再合并。
|
||
|
||
**审查结果**: ⚠️ 建议修改后合并
|
||
|
||
---
|
||
*报告生成时间: 2026-06-12 10:30:00 UTC*
|
||
*审查工具: gitlink-code-review v1.0.0*
|
||
```
|
||
|
||
## 🎯 审查标准
|
||
|
||
### 评分标准
|
||
|
||
| 分数范围 | 等级 | 合并建议 |
|
||
|---------|------|---------|
|
||
| 90-100 | ⭐⭐⭐⭐⭐ 优秀 | 可以直接合并 |
|
||
| 75-89 | ⭐⭐⭐⭐ 良好 | 建议合并 |
|
||
| 60-74 | ⭐⭐⭐ 一般 | 需要改进 |
|
||
| < 60 | ⭐⭐ 较差 | 不建议合并 |
|
||
|
||
### 问题优先级
|
||
|
||
| 优先级 | 图标 | 合并影响 |
|
||
|--------|------|---------|
|
||
| CRITICAL | 🚨 | 阻止合并 |
|
||
| HIGH | 🔴 | 强烈建议修复 |
|
||
| MEDIUM | ⚠️ | 建议修复 |
|
||
| LOW | ℹ️ | 可选修复 |
|
||
|
||
## 💡 最佳实践
|
||
|
||
### 1. 定期审查
|
||
|
||
- PR 创建后 24 小时内完成初审
|
||
- PR 更新后及时审查新代码
|
||
- 合并前进行最终审查
|
||
|
||
### 2. 平衡严格与灵活
|
||
|
||
- 核心模块严格审查
|
||
- 工具函数适度审查
|
||
- 文档和配置文件宽松审查
|
||
|
||
### 3. 建设性反馈
|
||
|
||
- 指出问题的同时提供解决方案
|
||
- 认可优秀的代码实践
|
||
- 解释为什么需要修改
|
||
|
||
## 🔧 自动化脚本
|
||
|
||
完整的审查脚本：
|
||
|
||
```bash
|
||
#!/bin/bash
|
||
# comprehensive-review.sh - 全面代码审查脚本
|
||
|
||
set -e
|
||
|
||
PR_ID=${1:-123}
|
||
OWNER=${2:-"myuser"}
|
||
REPO=${3:-"myrepo"}
|
||
|
||
echo "=== 开始全面审查 PR #$PR_ID ==="
|
||
|
||
# 步骤 1：获取数据
|
||
echo "步骤 1：获取 PR 数据..."
|
||
gitlink-cli pr +view --id $PR_ID --format json > pr_info.json
|
||
gitlink-cli pr +files --id $PR_ID --format json > pr_files.json
|
||
gitlink-cli pr +diff --id $PR_ID --format json > pr_diff.json
|
||
|
||
# 步骤 2：验证数据
|
||
echo "步骤 2：验证数据..."
|
||
if [ "$(cat pr_info.json | jq '.ok')" != "true" ]; then
|
||
echo "错误：无法获取 PR 信息"
|
||
exit 1
|
||
fi
|
||
|
||
# 步骤 3：组织分析数据
|
||
echo "步骤 3：组织分析数据..."
|
||
cat > analysis_input.json <<EOF
|
||
{
|
||
"pr_info": $(cat pr_info.json | jq '.data'),
|
||
"files": $(cat pr_files.json | jq '.data.files'),
|
||
"diff": $(cat pr_diff.json | jq -r '.data.diff')
|
||
}
|
||
EOF
|
||
|
||
# 步骤 4：AI 分析
|
||
echo "步骤 4：AI 分析（需要 Claude Code 或 API）..."
|
||
# 这里调用 AI 分析工具
|
||
# claude-code-analyze analysis_input.json > analysis_result.json
|
||
|
||
# 步骤 5：生成报告
|
||
echo "步骤 5：生成审查报告..."
|
||
# cat analysis_result.json | jq -r '.content' > review_report.json
|
||
# cat analysis_result.json | jq -r '.content' > review_report.md
|
||
|
||
# 步骤 6：输出报告
|
||
echo "步骤 6：输出审查报告..."
|
||
# cat review_report.md
|
||
|
||
echo "=== 审查完成 ==="
|
||
```
|
||
|
||
使用方法：
|
||
```bash
|
||
chmod +x comprehensive-review.sh
|
||
./comprehensive-review.sh 123 myuser myrepo
|
||
```
|
||
|
||
## 📚 相关文档
|
||
|
||
- [基础审查工作流](basic-review-workflow.md) - 快速代码审查
|
||
- [自动审查工作流](auto-review-pr.md) - AI 自动审查
|
||
- [代码质量检查](../references/code-review-quality.md) - 质量分析详解
|
||
- [安全性检查](../references/code-review-security.md) - 安全分析详解
|
||
|
||
---
|
||
|
||
*最后更新: 2026-06-12*
|