forked from Gitlink/gitlink-cli
580 lines
12 KiB
Markdown
580 lines
12 KiB
Markdown
# gitlink-code-review API 参考文档
|
||
|
||
本文档提供 gitlink-code-review Skill 的详细 API 参考和参数说明。
|
||
|
||
## 📋 目录
|
||
|
||
- [PR 信息获取 API](#pr-信息获取-api)
|
||
- [代码分析 API](#代码分析-api)
|
||
- [审查报告生成 API](#审查报告生成-api)
|
||
- [评论集成 API](#评论集成-api)
|
||
- [错误处理](#错误处理)
|
||
- [数据格式](#数据格式)
|
||
|
||
---
|
||
|
||
## PR 信息获取 API
|
||
|
||
### 1. 获取 PR 详情
|
||
|
||
**命令**:
|
||
```bash
|
||
gitlink-cli pr +view --id <pr_id> --format json
|
||
```
|
||
|
||
**参数**:
|
||
- `--id` (必需): PR 编号
|
||
- `--owner`: 仓库所有者（可选，自动从 git remote 解析）
|
||
- `--repo`: 仓库名称（可选，自动从 git remote 解析）
|
||
- `--format`: 输出格式（json/table/yaml）
|
||
|
||
**返回格式**:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"id": 123,
|
||
"project_issues_index": 123,
|
||
"title": "Feature: Add user authentication",
|
||
"body": "This PR adds user authentication...",
|
||
"author": {
|
||
"login": "developer",
|
||
"user_id": 456
|
||
},
|
||
"status": "open",
|
||
"pull_request_status": 0,
|
||
"head": "feature/auth",
|
||
"base": "main",
|
||
"created_at": "2026-06-12T10:00:00Z",
|
||
"updated_at": "2026-06-12T10:30:00Z"
|
||
},
|
||
"meta": {
|
||
"identity": "user:developer"
|
||
}
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
- `id`: PR 数据库 ID
|
||
- `project_issues_index`: PR 编号（网页 URL 中显示）
|
||
- `pull_request_status`: PR 状态（0=open, 1=merged, 2=closed）
|
||
|
||
### 2. 获取变更文件列表
|
||
|
||
**命令**:
|
||
```bash
|
||
gitlink-cli pr +files --id <pr_id> --format json
|
||
```
|
||
|
||
**返回格式**:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"files": [
|
||
{
|
||
"filename": "src/auth/login.go",
|
||
"status": "modified",
|
||
"additions": 50,
|
||
"deletions": 20,
|
||
"changes": 70,
|
||
"patch": "@@ -1,10 +1,15 @@\n+func login() {"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
**字段说明**:
|
||
- `status`: 文件状态（added/modified/deleted/renamed）
|
||
- `additions`: 新增行数
|
||
- `deletions`: 删除行数
|
||
- `changes`: 总变更行数
|
||
- `patch`: diff 片段
|
||
|
||
### 3. 获取 diff 内容
|
||
|
||
**命令**:
|
||
```bash
|
||
gitlink-cli pr +diff --id <pr_id> --format json
|
||
```
|
||
|
||
**返回格式**:
|
||
```json
|
||
{
|
||
"ok": true,
|
||
"data": {
|
||
"diff": "diff --git a/src/auth/login.go b/src/auth/login.go\n@@ -1,10 +1,15 @@\n+func login() {",
|
||
"files_count": 5,
|
||
"additions": 150,
|
||
"deletions": 50
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 代码分析 API
|
||
|
||
代码分析由 AI Agent 执行，使用 Claude 的代码理解能力。
|
||
|
||
### 分析流程
|
||
|
||
1. **解析 diff 内容**
|
||
2. **识别变更的代码块**
|
||
3. **多维度分析代码**
|
||
4. **生成结构化报告**
|
||
|
||
### 分析维度
|
||
|
||
#### 1. 代码质量分析
|
||
|
||
**检查项**:
|
||
- 圈复杂度（Cyclomatic Complexity）
|
||
- 函数长度
|
||
- 嵌套层级
|
||
- 命名规范
|
||
- 注释完整性
|
||
|
||
**输出示例**:
|
||
```json
|
||
{
|
||
"quality_analysis": {
|
||
"overall_score": 90,
|
||
"complexity": {
|
||
"avg_cyclomatic_complexity": 3.5,
|
||
"max_function_length": 50,
|
||
"max_nesting_level": 3
|
||
},
|
||
"naming": {
|
||
"score": 95,
|
||
"issues": []
|
||
},
|
||
"comments": {
|
||
"score": 85,
|
||
"coverage": 75
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 2. 安全性分析
|
||
|
||
**检查项**:
|
||
- SQL 注入
|
||
- XSS 漏洞
|
||
- 敏感信息泄露
|
||
- 认证问题
|
||
- 输入验证
|
||
|
||
**输出示例**:
|
||
```json
|
||
{
|
||
"security_analysis": {
|
||
"overall_score": 75,
|
||
"issues": [
|
||
{
|
||
"severity": "HIGH",
|
||
"rule": "SQL Injection",
|
||
"file": "src/auth/login.go",
|
||
"line": 45,
|
||
"description": "直接拼接用户输入到 SQL 语句",
|
||
"code": "query := \"SELECT * FROM users WHERE username = '\" + username + \"'\"",
|
||
"suggestion": "使用参数化查询或 ORM"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 3. 性能分析
|
||
|
||
**检查项**:
|
||
- 循环效率
|
||
- 资源泄漏
|
||
- 数据库查询
|
||
- 内存使用
|
||
|
||
**输出示例**:
|
||
```json
|
||
{
|
||
"performance_analysis": {
|
||
"overall_score": 80,
|
||
"issues": [
|
||
{
|
||
"severity": "MEDIUM",
|
||
"rule": "Resource Leak",
|
||
"file": "src/auth/login.go",
|
||
"line": 78,
|
||
"description": "数据库连接未关闭",
|
||
"code": "db, _ := sql.Open(\"mysql\", dsn)",
|
||
"suggestion": "使用 defer db.Close()"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4. 可维护性分析
|
||
|
||
**检查项**:
|
||
- 代码重复
|
||
- 职责单一
|
||
- 依赖耦合
|
||
- 测试覆盖
|
||
|
||
**输出示例**:
|
||
```json
|
||
{
|
||
"maintainability_analysis": {
|
||
"overall_score": 85,
|
||
"duplicate_code_rate": 5,
|
||
"test_coverage": 60,
|
||
"recommendations": [
|
||
"建议添加单元测试覆盖登录逻辑"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 审查报告生成 API
|
||
|
||
### JSON 格式报告
|
||
|
||
**结构**:
|
||
```json
|
||
{
|
||
"pr_info": {
|
||
"id": 123,
|
||
"title": "Feature: Add user authentication",
|
||
"author": "developer",
|
||
"files_changed": 5,
|
||
"lines_added": 150,
|
||
"lines_removed": 50
|
||
},
|
||
"analysis_timestamp": "2026-06-12T10:30:00Z",
|
||
"overall_assessment": {
|
||
"total_score": 85,
|
||
"quality_score": 90,
|
||
"security_score": 75,
|
||
"performance_score": 80,
|
||
"maintainability_score": 85,
|
||
"status": "APPROVED_WITH_CHANGES"
|
||
},
|
||
"issues": [
|
||
{
|
||
"id": 1,
|
||
"file": "src/auth/login.go",
|
||
"line": 45,
|
||
"severity": "HIGH",
|
||
"category": "security",
|
||
"rule": "SQL Injection",
|
||
"description": "直接拼接用户输入到 SQL 语句",
|
||
"code_snippet": "query := \"SELECT * FROM users WHERE username = '\" + username + \"'\"",
|
||
"suggestion": "使用参数化查询或 ORM",
|
||
"references": [
|
||
"https://owasp.org/www-community/attacks/SQL_Injection"
|
||
]
|
||
}
|
||
],
|
||
"positive_notes": [
|
||
{
|
||
"file": "src/auth/user.go",
|
||
"line": 120,
|
||
"description": "优秀的错误处理",
|
||
"code_snippet": "if err != nil {\n log.Errorf(\"Failed to login: %v\", err)\n return err\n}"
|
||
}
|
||
],
|
||
"recommendations": [
|
||
"建议添加单元测试覆盖登录逻辑",
|
||
"建议使用参数化查询防止 SQL 注入",
|
||
"建议添加输入验证中间件"
|
||
],
|
||
"summary": "代码整体质量良好，但存在几个需要修复的安全问题。建议修复高优先级问题后合并。"
|
||
}
|
||
```
|
||
|
||
### Markdown 格式报告
|
||
|
||
**模板**:
|
||
```markdown
|
||
# 代码审查报告
|
||
|
||
## PR 信息
|
||
- **PR ID**: 123
|
||
- **标题**: Feature: Add user authentication
|
||
- **作者**: @developer
|
||
- **分支**: feature/auth → main
|
||
- **变更**: 5 个文件，+150 / -50 行
|
||
|
||
## 总体评分: 85/100 ⭐⭐⭐⭐
|
||
|
||
### 评分详情
|
||
- 代码质量: 90/100
|
||
- 安全性: 75/100 ⚠️
|
||
- 性能: 80/100
|
||
- 可维护性: 85/100
|
||
|
||
## 问题列表
|
||
|
||
### 🔴 高优先级（2）
|
||
|
||
#### 1. SQL 注入风险
|
||
- **文件**: `src/auth/login.go:45`
|
||
- **类别**: security
|
||
- **问题**: 直接拼接用户输入到 SQL 语句
|
||
- **代码**:
|
||
```go
|
||
query := "SELECT * FROM users WHERE username = '" + username + "'"
|
||
```
|
||
- **建议**: 使用参数化查询或 ORM
|
||
|
||
#### 2. 资源泄漏
|
||
- **文件**: `src/auth/login.go:78`
|
||
- **类别**: performance
|
||
- **问题**: 数据库连接未关闭
|
||
- **代码**:
|
||
```go
|
||
db, _ := sql.Open("mysql", dsn)
|
||
// 缺少 defer db.Close()
|
||
```
|
||
- **建议**: 使用 `defer db.Close()`
|
||
|
||
### ⚠️ 中优先级（1）
|
||
|
||
#### 1. 缺少输入验证
|
||
- **文件**: `src/auth/login.go:30`
|
||
- **类别**: security
|
||
- **问题**: 未验证用户名长度和格式
|
||
- **建议**: 添加输入验证中间件
|
||
|
||
## ⭐ 优秀实践（1）
|
||
|
||
### 1. 优秀的错误处理
|
||
- **文件**: `src/auth/user.go:120`
|
||
- **描述**: 完善的错误处理和日志记录
|
||
|
||
## 💡 改进建议
|
||
|
||
1. 建议添加单元测试覆盖登录逻辑
|
||
2. 建议使用参数化查询防止 SQL 注入
|
||
3. 建议添加输入验证中间件
|
||
4. 建议添加代码注释说明复杂逻辑
|
||
|
||
## 📊 文件详情
|
||
|
||
### src/auth/login.go
|
||
- **变更**: +50 / -20 行
|
||
- **问题**: 3 个（1 个高优先级，2 个中优先级）
|
||
- **建议**: 修复安全问题，添加输入验证
|
||
|
||
### src/auth/user.go
|
||
- **变更**: +80 / -10 行
|
||
- **问题**: 1 个中优先级
|
||
- **优秀实践**: 1 个
|
||
|
||
## 📝 总结
|
||
|
||
代码整体质量良好，结构清晰，命名规范。但存在几个需要修复的安全问题，特别是 SQL 注入风险。建议修复高优先级问题后合并。
|
||
|
||
**审查结果**: ✅ 建议修改后合并
|
||
|
||
---
|
||
*报告生成时间: 2026-06-12 10:30:00 UTC*
|
||
*审查工具: gitlink-code-review v1.0.0*
|
||
```
|
||
|
||
---
|
||
|
||
## 评论集成 API
|
||
|
||
### 添加总评
|
||
|
||
**命令**:
|
||
```bash
|
||
gitlink-cli api POST /:owner/:repo/pulls/:id/reviews --body '{
|
||
"body": "<审查报告内容>",
|
||
"event": "COMMENT"
|
||
}'
|
||
```
|
||
|
||
**参数**:
|
||
- `:owner`: 仓库所有者
|
||
- `:repo`: 仓库名称
|
||
- `:id`: PR 编号
|
||
- `body`: 评论内容（Markdown 格式）
|
||
- `event`: 事件类型（COMMENT/APPROVE/REQUEST_CHANGES）
|
||
|
||
**事件类型**:
|
||
- `COMMENT`: 普通评论
|
||
- `APPROVE`: 批准 PR
|
||
- `REQUEST_CHANGES`: 请求修改
|
||
|
||
### 添加行内评论
|
||
|
||
**命令**:
|
||
```bash
|
||
gitlink-cli api POST /:owner/:repo/pulls/:id/comments --body '{
|
||
"body": "建议使用参数化查询",
|
||
"commit_id": "<commit_sha>",
|
||
"path": "src/auth/login.go",
|
||
"position": 45
|
||
}'
|
||
```
|
||
|
||
**参数**:
|
||
- `commit_id`: 提交 SHA
|
||
- `path`: 文件路径
|
||
- `position`: 行号
|
||
- `body`: 评论内容
|
||
|
||
### 批量添加评论
|
||
|
||
**脚本示例**:
|
||
```bash
|
||
#!/bin/bash
|
||
# 批量添加审查评论
|
||
|
||
PR_ID=123
|
||
OWNER="myuser"
|
||
REPO="myrepo"
|
||
|
||
# 读取审查报告中的问题
|
||
issues=$(jq -r '.issues[]' review.json)
|
||
|
||
# 逐个添加评论
|
||
for issue in $issues; do
|
||
file=$(echo $issue | jq -r '.file')
|
||
line=$(echo $issue | jq -r '.line')
|
||
suggestion=$(echo $issue | jq -r '.suggestion')
|
||
|
||
gitlink-cli api POST /$OWNER/$REPO/pulls/$PR_ID/comments --body "{
|
||
\"body\": \"$suggestion\",
|
||
\"path\": \"$file\",
|
||
\"position\": $line
|
||
}"
|
||
done
|
||
```
|
||
|
||
---
|
||
|
||
## 错误处理
|
||
|
||
### 常见错误
|
||
|
||
#### 1. PR 不存在
|
||
|
||
**错误信息**:
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"error": {
|
||
"code": 404,
|
||
"message": "PR not found",
|
||
"suggestion": "检查 PR 编号是否正确"
|
||
}
|
||
}
|
||
```
|
||
|
||
**处理方法**:
|
||
- 检查 PR 编号是否正确
|
||
- 确认 PR 是否在正确的仓库中
|
||
- 使用 `gitlink-cli pr +list` 验证 PR 存在
|
||
|
||
#### 2. 权限不足
|
||
|
||
**错误信息**:
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"error": {
|
||
"code": 403,
|
||
"message": "Permission denied",
|
||
"suggestion": "确认账号有此仓库的访问权限"
|
||
}
|
||
}
|
||
```
|
||
|
||
**处理方法**:
|
||
- 确认账号有仓库访问权限
|
||
- 私有仓库需要先认证
|
||
- 运行 `gitlink-cli auth login` 重新登录
|
||
|
||
#### 3. 未认证
|
||
|
||
**错误信息**:
|
||
```json
|
||
{
|
||
"ok": false,
|
||
"error": {
|
||
"code": 401,
|
||
"message": "Unauthorized",
|
||
"suggestion": "运行 gitlink-cli auth login 登录"
|
||
}
|
||
}
|
||
```
|
||
|
||
**处理方法**:
|
||
- 运行 `gitlink-cli auth login` 登录
|
||
- 或设置 `GITLINK_TOKEN` 环境变量
|
||
|
||
### 错误处理最佳实践
|
||
|
||
1. **检查 PR 状态**: 在审查前确认 PR 存在且可访问
|
||
2. **验证权限**: 确认账号有仓库访问权限
|
||
3. **处理网络错误**: 重试失败的请求
|
||
4. **记录错误**: 记录错误日志以便调试
|
||
|
||
---
|
||
|
||
## 数据格式
|
||
|
||
### PR 状态映射
|
||
|
||
| 状态码 | 状态名称 | 说明 |
|
||
|--------|---------|------|
|
||
| 0 | open | 开放中 |
|
||
| 1 | merged | 已合并 |
|
||
| 2 | closed | 已关闭 |
|
||
|
||
### 严重性级别
|
||
|
||
| 级别 | 图标 | 说明 | 是否阻止合并 |
|
||
|------|------|------|--------------|
|
||
| CRITICAL | 🚨 | 严重问题，必须立即修复 | 是 |
|
||
| HIGH | 🔴 | 高优先级，建议尽快修复 | 是 |
|
||
| MEDIUM | ⚠️ | 中优先级，建议修复 | 建议 |
|
||
| LOW | ℹ️ | 低优先级，可选修复 | 否 |
|
||
| INFO | 💡 | 信息性建议 | 否 |
|
||
|
||
### 审查结果状态
|
||
|
||
| 状态 | 说明 | 是否可合并 |
|
||
|------|------|-----------|
|
||
| APPROVED | 批准，可直接合并 | 是 |
|
||
| APPROVED_WITH_CHANGES | 批准，但建议修改 | 是 |
|
||
| CHANGES_REQUESTED | 请求修改，需修复后重新审查 | 否 |
|
||
| COMMENTED | 仅评论，未给出审批意见 | 待定 |
|
||
|
||
---
|
||
|
||
## 🔗 相关资源
|
||
|
||
- [gitlink-pr/SKILL.md](../gitlink-pr/SKILL.md) - PR 操作指南
|
||
- [gitlink-shared/SKILL.md](../gitlink-shared/SKILL.md) - 认证和全局参数
|
||
- [GitLink API 文档](https://www.gitlink.org.cn/api/docs) - 完整 API 参考
|
||
|
||
---
|
||
|
||
## 📞 获取帮助
|
||
|
||
- **命令帮助**: `gitlink-cli pr --help`
|
||
- **故障排查**: [../gitlink-shared/TROUBLESHOOTING.md](../gitlink-shared/TROUBLESHOOTING.md)
|
||
- **API 参考**: [GitLink API 文档](https://www.gitlink.org.cn/api/docs)
|
||
|
||
---
|
||
|
||
*最后更新: 2026-06-12*
|