# 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*
