GitCodeStatic/QUICKSTART.md

GitCodeStatic - 快速启动指南

🚀 5分钟快速上手

1. 编译并运行

# 安装依赖
go mod tidy

# 运行服务
go run cmd/server/main.go

服务将在 http://localhost:8080 启动

2. 添加第一个仓库

curl -X POST http://localhost:8080/api/v1/repos/batch \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://github.com/gin-gonic/gin.git"]
  }'

响应示例：

{
  "code": 0,
  "message": "success",
  "data": {
    "total": 1,
    "succeeded": [{
      "repo_id": 1,
      "url": "https://github.com/gin-gonic/gin.git",
      "task_id": 1
    }],
    "failed": []
  }
}

3. 等待克隆完成

# 查看仓库状态
curl http://localhost:8080/api/v1/repos/1

等待 status 变为 "ready"

4. 触发代码统计

curl -X POST http://localhost:8080/api/v1/stats/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "repo_id": 1,
    "branch": "master",
    "constraint": {
      "type": "commit_limit",
      "limit": 100
    }
  }'

5. 查询统计结果

curl "http://localhost:8080/api/v1/stats/result?repo_id=1&branch=master&constraint_type=commit_limit&limit=100"

你将看到：

• 总提交数
• 贡献者列表
• 每个贡献者的代码变更统计（新增/删除/修改/净增加）

📊 完整工作流示例

# 1. 添加多个仓库
curl -X POST http://localhost:8080/api/v1/repos/batch \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://github.com/gin-gonic/gin.git",
      "https://github.com/go-chi/chi.git"
    ]
  }'

# 2. 查看所有ready状态的仓库
curl "http://localhost:8080/api/v1/repos?status=ready"

# 3. 先查询某个日期到现在有多少提交（辅助决策）
curl "http://localhost:8080/api/v1/stats/commit-count?repo_id=1&branch=master&from=2024-01-01"

# 4. 根据提交数选择合适的约束类型
# 如果提交数少（<1000），用日期范围
curl -X POST http://localhost:8080/api/v1/stats/calculate \
  -H "Content-Type: application/json" \
  -d '{
    "repo_id": 1,
    "branch": "master",
    "constraint": {
      "type": "date_range",
      "from": "2024-01-01",
      "to": "2024-12-31"
    }
  }'

# 5. 查询结果（会自动命中缓存）
curl "http://localhost:8080/api/v1/stats/result?repo_id=1&branch=master&constraint_type=date_range&from=2024-01-01&to=2024-12-31"

# 6. 切换分支
curl -X POST http://localhost:8080/api/v1/repos/1/switch-branch \
  -H "Content-Type: application/json" \
  -d '{"branch": "develop"}'

# 7. 更新仓库（获取最新代码）
curl -X POST http://localhost:8080/api/v1/repos/1/update

# 8. 重置仓库（清除缓存+重新克隆）
curl -X POST http://localhost:8080/api/v1/repos/1/reset

🔧 常见问题

Q: 如何处理私有仓库？

A: 暂不支持通过API设置凭据，需要手动在数据库中添加或使用https://username:token@github.com/repo.git格式

Q: 统计任务一直pending？

A: 检查worker是否正常启动，查看日志：

# 日志会显示worker pool启动信息
# 确认没有错误

Q: 如何加速统计？

A:

1. 确保安装了git命令（比go-git快很多）
2. 增加stats_workers数量
3. 使用commit_limit而不是date_range（如果适用）

Q: 缓存占用空间过大？

A: 修改配置：

cache:
  max_total_size: 5368709120  # 改为5GB
  retention_days: 7            # 只保留7天

🎯 API完整列表

端点	方法	说明
/api/v1/repos/batch	POST	批量添加仓库
/api/v1/repos	GET	获取仓库列表
/api/v1/repos/:id	GET	获取仓库详情
/api/v1/repos/:id/switch-branch	POST	切换分支
/api/v1/repos/:id/update	POST	更新仓库
/api/v1/repos/:id/reset	POST	重置仓库
/api/v1/repos/:id	DELETE	删除仓库
/api/v1/stats/calculate	POST	触发统计
/api/v1/stats/result	GET	查询统计结果
/api/v1/stats/commit-count	GET	查询提交次数
/health	GET	健康检查

📝 日志查看

# 开发模式：日志输出到stdout
go run cmd/server/main.go

# 查看结构化日志
# 示例：
{"level":"info","time":"2024-12-31T12:00:00+08:00","message":"worker started","worker_id":1}
{"level":"info","time":"2024-12-31T12:00:01+08:00","message":"task started","worker_id":1,"task_id":1,"task_type":"clone","repo_id":1}

🎉 下一步

• 阅读完整 README.md 了解所有功能
• 查看 ARCHITECTURE.md 理解系统架构
• 查看单元测试示例学习如何测试：test/unit/
• 根据需求调整 configs/config.yaml 配置

Happy Coding! 🚀