189 lines
4.6 KiB
Markdown
189 lines
4.6 KiB
Markdown
# GitCodeStatic - 快速启动指南
|
||
|
||
## 🚀 5分钟快速上手
|
||
|
||
### 1. 编译并运行
|
||
|
||
```bash
|
||
# 安装依赖
|
||
go mod tidy
|
||
|
||
# 运行服务
|
||
go run cmd/server/main.go
|
||
```
|
||
|
||
服务将在 `http://localhost:8080` 启动
|
||
|
||
### 2. 添加第一个仓库
|
||
|
||
```bash
|
||
curl -X POST http://localhost:8080/api/v1/repos/batch \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"urls": ["https://github.com/gin-gonic/gin.git"]
|
||
}'
|
||
```
|
||
|
||
响应示例：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {
|
||
"total": 1,
|
||
"succeeded": [{
|
||
"repo_id": 1,
|
||
"url": "https://github.com/gin-gonic/gin.git",
|
||
"task_id": 1
|
||
}],
|
||
"failed": []
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3. 等待克隆完成
|
||
|
||
```bash
|
||
# 查看仓库状态
|
||
curl http://localhost:8080/api/v1/repos/1
|
||
```
|
||
|
||
等待 `status` 变为 `"ready"`
|
||
|
||
### 4. 触发代码统计
|
||
|
||
```bash
|
||
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. 查询统计结果
|
||
|
||
```bash
|
||
curl "http://localhost:8080/api/v1/stats/result?repo_id=1&branch=master&constraint_type=commit_limit&limit=100"
|
||
```
|
||
|
||
你将看到：
|
||
- 总提交数
|
||
- 贡献者列表
|
||
- 每个贡献者的代码变更统计（新增/删除/修改/净增加）
|
||
|
||
## 📊 完整工作流示例
|
||
|
||
```bash
|
||
# 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是否正常启动，查看日志：
|
||
```bash
|
||
# 日志会显示worker pool启动信息
|
||
# 确认没有错误
|
||
```
|
||
|
||
### Q: 如何加速统计？
|
||
A:
|
||
1. 确保安装了git命令（比go-git快很多）
|
||
2. 增加stats_workers数量
|
||
3. 使用commit_limit而不是date_range（如果适用）
|
||
|
||
### Q: 缓存占用空间过大？
|
||
A: 修改配置：
|
||
```yaml
|
||
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 | 健康检查 |
|
||
|
||
## 📝 日志查看
|
||
|
||
```bash
|
||
# 开发模式：日志输出到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](README.md) 了解所有功能
|
||
- 查看 [ARCHITECTURE.md](ARCHITECTURE.md) 理解系统架构
|
||
- 查看单元测试示例学习如何测试：`test/unit/`
|
||
- 根据需求调整 `configs/config.yaml` 配置
|
||
|
||
Happy Coding! 🚀
|