# Go-CodeCalendar-api

**Repository Path**: WuYiLingOps/go-code-calendar-api

## Basic Information

- **Project Name**: Go-CodeCalendar-api
- **Description**: 一个多平台的代码贡献日历应用，目前只支持 Gitee平台API接入
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-12-17
- **Last Updated**: 2026-03-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CodeCalendar（代码日历）


## 功能简介

- **后端（`api-go/main.go`）**
  - 使用 Go 爬取 `https://gitee.com/<user>` 的贡献日历页面
  - 解析出过去一年的每日贡献次数，按周（7 天一组）返回
  - 提供 RESTful API：`GET /api?user=<Gitee 用户名>`
  - 支持 CORS，允许跨域请求

- **前端（`web/index.html`）**
  - 使用 Vue3（CDN 引入）构建单页应用
  - 精美的 GitHub 风格热力图展示
  - 展示统计信息：
    - 过去一年总提交数
    - 最近一月提交数
    - 最近一周提交数
  - 支持鼠标悬停查看每天的具体提交次数
  - 响应式设计，适配移动端

---

## 快速开始

### 前置要求

- Go 1.18+ （用于运行后端服务）
- 现代浏览器（Chrome、Firefox、Edge 等）

### 启动步骤

#### 1. 启动 Go API 服务

```bash
cd api-go
go run main.go
```

默认监听端口：**8081**

服务启动后，可以在浏览器中测试 API：

```
http://localhost:8081/api?user=wylblog
```

或使用 `curl` 测试：

```bash
curl "http://localhost:8081/api?user=wylblog"
```

若返回类似以下 JSON，说明 API 正常工作：

```json
{
  "total": 1234,
  "contributions": [
    [
      {"date": "2024-01-01", "count": 0},
      {"date": "2024-01-02", "count": 3},
      ...
    ],
    ...
  ]
}
```

#### 2. 打开前端页面

前端是一个纯静态 HTML 文件，可以通过以下方式访问：

**方式一：直接打开文件**
- 用浏览器直接打开 `web/index.html` 文件

**方式二：使用静态文件服务器**

使用 Node.js（推荐）：
```bash
# 在项目根目录
npm install
npm run dev
```

使用 Python：
```bash
# Python 3
cd web
python -m http.server 3000
```

然后在浏览器中打开：
```
http://localhost:3000/index.html
```

> **注意**：前端默认调用 `http://localhost:8081/api`，请确保 Go 服务在 8081 端口运行。

参考页面如下：

![image-20251217144059828](https://hj-typora-images-1319512400.cos.ap-guangzhou.myqcloud.com/images/202512171440889.png)

---

## 使用说明

1. 确保 Go API 服务正在运行（`http://localhost:8081`）
2. 打开前端页面（`web/index.html`）
3. 在输入框中输入 Gitee 用户名（默认：`wylblog`）
4. 点击「加载日历」按钮或按 Enter 键
5. 查看热力图和统计数据：
   - 鼠标悬停在格子上可查看具体日期和提交次数
   - 底部显示三个统计卡片

---

## 项目结构

```
code-calendar/
├── api-go/
│   └── main.go          # Go 后端服务，提供 API 接口
├── web/
│   └── index.html       # Vue3 前端页面
├── examples/
│   └── GiteeCalendar.vue  # Vue3 组件示例（用于集成到其他项目）
├── package.json         # 前端开发依赖配置
└── README.md            # 项目文档
```

---

## API 接口说明

### 请求

```
GET /api?user=<Gitee用户名>
```

### 响应

```json
{
  "total": 1234,
  "contributions": [
    [
      {"date": "2024-01-01", "count": 0},
      {"date": "2024-01-02", "count": 3},
      {"date": "2024-01-03", "count": 5},
      ...
    ],
    [
      {"date": "2024-01-08", "count": 2},
      ...
    ],
    ...
  ]
}
```

**字段说明：**
- `total`: 过去一年的总提交数
- `contributions`: 二维数组，外层数组表示周，内层数组表示一周的 7 天
- `date`: 日期，格式为 `YYYY-MM-DD`
- `count`: 该日的提交次数

---

## 部署建议

### 开发环境

按照上述「快速开始」步骤即可。

### 生产环境

#### 方案一：分离部署

1. **后端部署**
   - 将 Go 服务部署到服务器（如使用 Docker、systemd 等）
   - 配置反向代理（Nginx）：
     ```nginx
     location /api {
         proxy_pass http://localhost:8081;
     }
     ```

2. **前端部署**
   - 将 `web/index.html` 部署到静态托管服务（如 Nginx、CDN、GitHub Pages 等）
   - 通过 URL 参数配置 API 地址：
     ```
     https://your-domain.com/index.html?api=https://your-api.com/api
     ```
   - 或修改 `web/index.html` 中的 `apiBase` 函数直接设置 API 地址

#### 方案二：Go 服务同时提供静态文件

可以修改 `api-go/main.go`，添加静态文件服务功能，让 Go 服务同时提供 API 和前端页面。

---

## 技术栈

- **后端**：Go 1.18+
  - `net/http` - HTTP 服务器
  - `regexp` - 正则表达式解析 HTML
  - `encoding/json` - JSON 编码/解码

- **前端**：Vue 3（CDN）
  - Composition API
  - CSS Grid / Flexbox
  - CSS 变量

---

## 注意事项

1. **API 限制**：由于是爬取 Gitee 页面，请合理使用，避免频繁请求
2. **CORS**：后端已设置 `Access-Control-Allow-Origin: *`，允许跨域请求
3. **端口配置**：默认端口为 8081，可通过环境变量 `PORT` 修改：
   ```bash
   PORT=3000 go run api-go/main.go
   ```
4. **IP 白名单**：支持通过 `.env-gitee-calendar-api` 文件配置 IP 白名单
   - 文件位置：项目根目录（与 `api-go` 目录同级）
   - 如果文件不存在，默认允许所有 IP 访问
   - 如果文件存在，只有白名单中的 IP 可以访问 API
   - 支持精确 IP 地址和 CIDR 网段格式
   - 示例配置请参考 `.env-gitee-calendar-api.example` 文件

---

### Vue3 组件集成

项目提供了可直接使用的 Vue3 组件示例：

**文件位置**：`examples/GiteeCalendar.vue`

**使用方法**：

1. 将 `examples/GiteeCalendar.vue` 复制到你的 Vue3 项目中
2. 在页面中引入并使用：

```vue
<template>
  <div>
    <GiteeCalendar 
      :default-user="'wylblog'" 
      :api-url="'http://localhost:8081/api'"
      :show-input="true"
    />
  </div>
</template>

<script setup>
import GiteeCalendar from '@/components/GiteeCalendar.vue'
</script>
```

**组件 Props**：
- `defaultUser` (String): 默认 Gitee 用户名
- `apiUrl` (String): API 服务地址，默认 `http://localhost:8081/api`
- `showInput` (Boolean): 是否显示输入框，默认 `true`



## 参考资料

> github对接：

- https://github.com/Barry-Flynn/python_github_calendar_api
- https://github.com/Zfour/hexo-github-calendar