GitHub Trending Explorer

一个现代化的 GitHub 热门开源项目探索工具，提供动态分页查询、收藏管理和 AI 智能总结功能。

📋 项目简介

GitHub Trending Explorer 是一个全栈 Web 应用，帮助开发者发现和探索 GitHub 上最热门的开源项目。通过直观的界面和强大的筛选功能，用户可以轻松浏览每天、每周、每月或每年的热门项目，并使用 AI 技术快速了解项目亮点。

核心特性

🔍 动态查询 - 支持按时间范围（日/周/月/年）和编程语言筛选热门项目
📄 分页浏览 - 高效的分页机制，支持大量数据浏览
❤️ 收藏管理 - 一键收藏感兴趣的项目，支持本地持久化存储
🤖 AI 智能总结 - 基于 LLM 的项目简介、亮点和适用场景分析
📊 数据可视化 - 收藏项目的语言分布统计图表
📥 数据导出 - 支持将收藏列表导出为 JSON 格式
🎨 现代化 UI - 响应式设计，支持深色主题，流畅的动画效果

🏗️ 技术架构

前端技术栈

技术	版本	用途
React	19.2.1	UI 框架
TypeScript	5.9.3	类型安全
Vite	7.1.7	构建工具
Tailwind CSS	4.1.14	样式框架
tRPC	11.6.0	类型安全的 API 调用
React Query	5.90.2	数据获取和缓存
Framer Motion	12.23.22	动画库
Recharts	2.15.2	数据可视化

后端技术栈

技术	版本	用途
Spring Boot	3.2.0	Java Web 框架
MySQL	8.0+	关系型数据库
JPA/Hibernate	-	ORM 框架
Spring WebFlux	-	响应式 HTTP 客户端
JWT	-	用户认证

数据流向

graph TB
    A[用户浏览器] -->|HTTP 请求| B[React 前端]
    B -->|GitHub API| C[GitHub 服务器]
    B -->|REST API| D[Spring Boot 后端]
    D -->|LLM API| E[AI 服务]
    D -->|SQL 查询| F[MySQL 数据库]
    B -->|localStorage| G[本地存储]
    
    style A fill:#4a90e2
    style B fill:#61dafb
    style D fill:#6db33f
    style E fill:#ff6b6b
    style F fill:#4479a1

📁 项目结构

github-trending-full-source/
├── client/                    # React 前端应用
│   ├── src/
│   │   ├── pages/            # 页面组件
│   │   │   ├── Home.tsx      # 主页（项目浏览）
│   │   │   └── Favorites.tsx # 收藏页面
│   │   ├── components/       # UI 组件
│   │   │   ├── RepoCard.tsx      # 项目卡片
│   │   │   ├── FilterPanel.tsx   # 筛选面板
│   │   │   ├── SummaryDialog.tsx # AI 总结对话框
│   │   │   ├── LanguageStats.tsx # 语言统计图表
│   │   │   └── ui/           # shadcn/ui 组件库
│   │   ├── hooks/            # 自定义 Hooks
│   │   │   └── useFavorites.ts   # 收藏管理 Hook
│   │   └── lib/              # 工具库
│   │       ├── github.ts     # GitHub API 封装
│   │       └── api.ts        # 后端 API 调用
│   └── package.json
│
├── backend/                  # Spring Boot 后端
│   ├── src/main/java/com/githubtrendings/
│   │   ├── controller/       # REST 控制器
│   │   │   ├── AuthController.java
│   │   │   └── RepositoryController.java
│   │   ├── service/          # 业务逻辑层
│   │   │   └── LLMService.java
│   │   ├── entity/           # JPA 实体
│   │   │   └── User.java
│   │   ├── repository/       # 数据访问层
│   │   │   └── UserRepository.java
│   │   └── dto/              # 数据传输对象
│   └── pom.xml
│
├── server/                   # Node.js 后端（已弃用，保留用于参考）
└── README.md                 # 本文件

🚀 快速开始

前置条件

Node.js: 22.13.0 或更高版本
pnpm: 10.4.1 或更高版本
Java: 17 或更高版本
Maven: 3.8.0 或更高版本
MySQL: 8.0 或更高版本

1. 克隆项目

git clone <repository-url>
cd github-trending-full-source

2. 启动后端

cd backend

# 配置数据库（编辑 src/main/resources/application.yml）
# 修改数据库连接信息

# 安装依赖并启动
mvn clean install
mvn spring-boot:run

后端将在 http://localhost:8080 启动。

3. 启动前端

cd client

# 安装依赖
pnpm install

# 启动开发服务器
pnpm dev

前端将在 http://localhost:5173 启动。

4. 配置环境变量

后端配置 (`backend/src/main/resources/application.yml`)

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/github_trending?useSSL=false&serverTimezone=UTC
    username: root
    password: your_password

# LLM 配置（用于 AI 总结）
llm:
  api-url: https://api.openai.com/v1
  api-key: your-openai-api-key

前端配置 (`client/.env`)

VITE_API_URL=http://localhost:8080/api

🎯 功能说明

1. 项目浏览

功能描述：浏览 GitHub 热门项目，支持按时间范围和编程语言筛选。

实现原理：

前端调用 GitHub Search API，根据时间范围和语言构建查询
使用分页机制，每页显示 20 个项目
实时统计当前页面的总星标数、Fork 数等数据

使用流程：

sequenceDiagram
    participant U as 用户
    participant F as 前端
    participant G as GitHub API
    
    U->>F: 选择时间范围/语言
    F->>G: 构建查询请求
    G->>F: 返回项目列表
    F->>U: 渲染项目卡片
    U->>F: 翻页
    F->>G: 请求下一页数据

关键代码：

client/src/pages/Home.tsx - 主页组件
client/src/lib/github.ts - GitHub API 封装

2. 收藏功能

功能描述：收藏感兴趣的项目，支持本地持久化存储。

实现原理：

使用 localStorage 存储收藏列表
通过 useFavorites Hook 统一管理收藏状态
收藏状态在主页和收藏页面间实时同步

数据结构：

interface GitHubRepository {
  id: number;
  name: string;
  full_name: string;
  description: string | null;
  html_url: string;
  stargazers_count: number;
  forks_count: number;
  language: string | null;
  owner: {
    login: string;
    avatar_url: string;
  };
  topics: string[];
}

关键代码：

client/src/hooks/useFavorites.ts - 收藏管理 Hook
client/src/components/RepoCard.tsx - 项目卡片（包含收藏按钮）

3. AI 智能总结

功能描述：基于 LLM 生成项目的简介、亮点和适用场景分析。

实现原理：

用户点击"AI 总结"按钮
前端收集项目信息（名称、描述、语言、主题、星标数等）
调用后端 API /api/repo/summarize
后端构建 Prompt，调用 LLM API
返回格式化的 Markdown 总结
前端使用 Streamdown 渲染 Markdown

Prompt 示例：

请用中文为以下 GitHub 项目生成一份简洁的项目总结报告。

项目名称: react
项目描述: A JavaScript library for building user interfaces
编程语言: JavaScript
主题标签: react, frontend, ui
星标数: 200000
Fork 数: 40000

请按以下格式生成总结（使用 Markdown）：
## 📌 项目简介
[用 1-2 句话简洁描述这个项目是干什么的]

## ✨ 核心亮点
- [亮点 1]
- [亮点 2]
- [亮点 3]

## 🎯 适用场景
[描述这个项目适合什么场景使用]

关键代码：

client/src/components/SummaryDialog.tsx - 总结对话框组件
backend/src/main/java/com/githubtrendings/controller/RepositoryController.java - 总结 API
backend/src/main/java/com/githubtrendings/service/LLMService.java - LLM 服务

4. 数据可视化

功能描述：在收藏页面显示收藏项目的编程语言分布统计。

实现原理：

统计收藏项目中各编程语言的数量
使用 Recharts 绘制饼图和柱状图
支持交互式图表展示

关键代码：

client/src/components/LanguageStats.tsx - 语言统计组件

5. 数据导出

功能描述：将收藏列表导出为 JSON 文件。

实现原理：

将收藏列表序列化为 JSON
添加元数据（导出时间、版本、数量等）
使用 Blob API 创建下载链接

导出格式：

{
  "exportDate": "2024-01-01T00:00:00.000Z",
  "version": "1.0",
  "count": 10,
  "repositories": [
    {
      "id": 123456,
      "name": "react",
      "url": "https://github.com/facebook/react",
      "owner": "facebook",
      "description": "A JavaScript library...",
      "stars": 200000,
      "forks": 40000,
      "language": "JavaScript",
      "topics": ["react", "frontend"]
    }
  ]
}

📚 API 文档

认证相关

获取当前用户信息

GET /api/auth/me

响应：

{
  "id": 1,
  "openId": "user-open-id",
  "name": "User Name",
  "email": "user@example.com"
}

用户登录

POST /api/auth/login
Content-Type: application/json

{
  "openId": "user-open-id",
  "name": "User Name",
  "email": "user@example.com",
  "loginMethod": "oauth"
}

用户登出

POST /api/auth/logout

项目相关

生成项目 AI 总结

POST /api/repo/summarize
Content-Type: application/json

{
  "repoName": "react",
  "owner": "facebook",
  "description": "A JavaScript library for building user interfaces"
}

响应：

{
  "repositoryName": "react",
  "owner": "facebook",
  "url": "https://github.com/facebook/react",
  "summary": "项目简介...",
  "highlights": "核心亮点...",
  "useCases": "适用场景..."
}

🔧 开发指南

前端开发

cd client

# 开发模式（热重载）
pnpm dev

# 类型检查
pnpm check

# 代码格式化
pnpm format

# 运行测试
pnpm test

# 构建生产版本
pnpm build

后端开发

cd backend

# 开发模式（自动重启）
mvn spring-boot:run

# 运行测试
mvn test

# 构建 JAR
mvn clean package

代码规范

前端：使用 ESLint + Prettier，遵循 React Hooks 最佳实践
后端：遵循 Spring Boot 编码规范，使用 JPA 注解
提交信息：使用 Conventional Commits 格式

🚀 部署

后端部署

使用 JAR 文件

cd backend
mvn clean package
java -jar target/github-trending-backend-1.0.0.jar

使用 Docker

docker build -t github-trending-backend ./backend
docker run -p 8080:8080 github-trending-backend

前端部署

cd client
pnpm build

# 输出目录：dist/
# 部署 dist 目录到 CDN 或 Web 服务器（如 Nginx）

环境变量配置

生产环境后端配置

spring:
  datasource:
    url: ${DB_URL}
    username: ${DB_USERNAME}
    password: ${DB_PASSWORD}
  
llm:
  api-url: ${LLM_API_URL}
  api-key: ${LLM_API_KEY}

生产环境前端配置

VITE_API_URL=https://api.yourdomain.com/api

🧪 测试

测试清单

常见问题

后端启动失败

数据库连接失败：检查 MySQL 是否运行，确认用户名和密码正确
端口被占用：修改 application.yml 中的 server.port 配置
找不到 Java 编译器：确保安装了 JDK（不是 JRE），并配置了 JAVA_HOME

前端启动失败

依赖安装失败：删除 node_modules 和 pnpm-lock.yaml，重新安装
端口被占用：修改 vite.config.ts 中的端口配置

API 调用失败

CORS 错误：后端已配置 CORS，检查前端 API URL 是否正确
404 错误：确保后端已启动，检查 API 路径是否正确

📊 性能优化

前端优化

代码分割：Vite 自动分割，按需加载
图表懒加载：Recharts 按需渲染
缓存策略：React Query 自动缓存 API 响应
本地存储：localStorage 缓存收藏列表

后端优化

数据库连接池：使用 HikariCP 连接池
查询优化：使用 JPA 索引优化查询性能
缓存策略：可集成 Redis 缓存热门查询结果

🔐 安全性

所有 API 端点在生产环境中应启用 HTTPS
使用强密钥配置 JWT_SECRET
定期更新依赖包，修复安全漏洞
使用数据库用户权限最小化原则
对用户输入进行验证和清理

📝 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

📞 支持

如有问题，请查看相关文档或提交 Issue。

祝你使用愉快！ 🚀

Name		Name	Last commit message	Last commit date
Latest commit History 2 Commits
backend		backend
client		client
drizzle		drizzle
patches		patches
server		server
shared		shared
.gitignore		.gitignore
.gitkeep		.gitkeep
.prettierignore		.prettierignore
.prettierrc		.prettierrc
QUICK_START.md		QUICK_START.md
README.md		README.md
TECHNICAL_EXPLANATION.md		TECHNICAL_EXPLANATION.md
components.json		components.json
drizzle.config.ts		drizzle.config.ts
ideas.md		ideas.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
tsconfig.json		tsconfig.json
tsconfig.node.json		tsconfig.node.json
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts

xy-ygz/github-trending-full-source

Folders and files

Latest commit

History

Repository files navigation

GitHub Trending Explorer

📋 项目简介

核心特性

🏗️ 技术架构

前端技术栈

后端技术栈

数据流向

📁 项目结构

🚀 快速开始

前置条件

1. 克隆项目

2. 启动后端

3. 启动前端

4. 配置环境变量

后端配置 (backend/src/main/resources/application.yml)

前端配置 (client/.env)

🎯 功能说明

1. 项目浏览

2. 收藏功能

3. AI 智能总结

4. 数据可视化

5. 数据导出

📚 API 文档

认证相关

获取当前用户信息

用户登录

用户登出

项目相关

生成项目 AI 总结

🔧 开发指南

前端开发

后端开发

代码规范

🚀 部署

后端部署

使用 JAR 文件

使用 Docker

前端部署

环境变量配置

生产环境后端配置

生产环境前端配置

🧪 测试

测试清单

常见问题

后端启动失败

前端启动失败

API 调用失败

📊 性能优化

前端优化

后端优化

🔐 安全性

📝 许可证

🤝 贡献

📞 支持

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

后端配置 (`backend/src/main/resources/application.yml`)

前端配置 (`client/.env`)

Packages