12 KiB

Raw Blame History

gitlink-code-review API 参考文档

本文档提供 gitlink-code-review Skill 的详细 API 参考和参数说明。

📋 目录

PR 信息获取 API
代码分析 API
审查报告生成 API
评论集成 API
错误处理
数据格式

PR 信息获取 API

1. 获取 PR 详情

命令:

gitlink-cli pr +view --id <pr_id> --format json

参数:

--id (必需): PR 编号
--owner: 仓库所有者（可选，自动从 git remote 解析）
--repo: 仓库名称（可选，自动从 git remote 解析）
--format: 输出格式（json/table/yaml）

返回格式:

{
  "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. 获取变更文件列表

命令:

gitlink-cli pr +files --id <pr_id> --format 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 内容

命令:

gitlink-cli pr +diff --id <pr_id> --format 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 的代码理解能力。

分析流程

解析 diff 内容
识别变更的代码块
多维度分析代码
生成结构化报告

分析维度

1. 代码质量分析

检查项:

圈复杂度（Cyclomatic Complexity）
函数长度
嵌套层级
命名规范
注释完整性

输出示例:

{
  "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 漏洞
敏感信息泄露
认证问题
输入验证

输出示例:

{
  "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. 性能分析

检查项:

循环效率
资源泄漏
数据库查询
内存使用

输出示例:

{
  "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. 可维护性分析

检查项:

代码重复
职责单一
依赖耦合
测试覆盖

输出示例:

{
  "maintainability_analysis": {
    "overall_score": 85,
    "duplicate_code_rate": 5,
    "test_coverage": 60,
    "recommendations": [
      "建议添加单元测试覆盖登录逻辑"
    ]
  }
}

审查报告生成 API

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 格式报告

模板:

# 代码审查报告

## 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
问题: 数据库连接未关闭

代码:

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
描述: 完善的错误处理和日志记录

💡 改进建议

建议添加单元测试覆盖登录逻辑
建议使用参数化查询防止 SQL 注入
建议添加输入验证中间件
建议添加代码注释说明复杂逻辑

📊 文件详情

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: 请求修改

添加行内评论

命令:

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: 评论内容

批量添加评论

脚本示例:

#!/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 不存在

错误信息:

{
  "ok": false,
  "error": {
    "code": 404,
    "message": "PR not found",
    "suggestion": "检查 PR 编号是否正确"
  }
}

处理方法:

检查 PR 编号是否正确
确认 PR 是否在正确的仓库中
使用 gitlink-cli pr +list 验证 PR 存在

2. 权限不足

错误信息:

{
  "ok": false,
  "error": {
    "code": 403,
    "message": "Permission denied",
    "suggestion": "确认账号有此仓库的访问权限"
  }
}

处理方法:

确认账号有仓库访问权限
私有仓库需要先认证
运行 gitlink-cli auth login 重新登录

3. 未认证

错误信息:

{
  "ok": false,
  "error": {
    "code": 401,
    "message": "Unauthorized",
    "suggestion": "运行 gitlink-cli auth login 登录"
  }
}

处理方法:

运行 gitlink-cli auth login 登录
或设置 GITLINK_TOKEN 环境变量

错误处理最佳实践

检查 PR 状态: 在审查前确认 PR 存在且可访问
验证权限: 确认账号有仓库访问权限
处理网络错误: 重试失败的请求
记录错误: 记录错误日志以便调试

数据格式

PR 状态映射

状态码	状态名称	说明
0	open	开放中
1	merged	已合并
2	closed	已关闭

严重性级别

级别	图标	说明	是否阻止合并
CRITICAL	🚨	严重问题，必须立即修复	是
HIGH	🔴	高优先级，建议尽快修复	是
MEDIUM	⚠️	中优先级，建议修复	建议
LOW	ℹ️	低优先级，可选修复	否
INFO	💡	信息性建议	否

审查结果状态

状态	说明	是否可合并
APPROVED	批准，可直接合并	是
APPROVED_WITH_CHANGES	批准，但建议修改	是
CHANGES_REQUESTED	请求修改，需修复后重新审查	否
COMMENTED	仅评论，未给出审批意见	待定

🔗 相关资源

gitlink-pr/SKILL.md - PR 操作指南
gitlink-shared/SKILL.md - 认证和全局参数
GitLink API 文档 - 完整 API 参考

📞 获取帮助

命令帮助: gitlink-cli pr --help
故障排查: ../gitlink-shared/TROUBLESHOOTING.md
API 参考: GitLink API 文档

最后更新: 2026-06-12

12 KiB Raw Blame History Unescape Escape

gitlink-code-review API 参考文档

📋 目录

PR 信息获取 API

1. 获取 PR 详情

2. 获取变更文件列表

3. 获取 diff 内容

代码分析 API

分析流程

分析维度

1. 代码质量分析

2. 安全性分析

3. 性能分析

4. 可维护性分析

审查报告生成 API

JSON 格式报告

Markdown 格式报告

2. 资源泄漏

⚠️ 中优先级（1）

1. 缺少输入验证

⭐ 优秀实践（1）

1. 优秀的错误处理

💡 改进建议

📊 文件详情

src/auth/login.go

src/auth/user.go

📝 总结

添加行内评论

批量添加评论

错误处理

常见错误

1. PR 不存在

2. 权限不足

3. 未认证

错误处理最佳实践

数据格式

PR 状态映射

严重性级别

审查结果状态

🔗 相关资源

📞 获取帮助

12 KiB

Raw Blame History