# MusicRecommendation

**Repository Path**: zuokuanpeng/music-recommendation

## Basic Information

- **Project Name**: MusicRecommendation
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-22
- **Last Updated**: 2026-02-22

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 基于Web的音乐推荐系统

一个完整的B/S架构音乐推荐系统，采用协同过滤算法实现个性化推荐，前后端分离架构设计。

## 项目简介

本项目实现了一个功能完整的音乐推荐系统，包含以下核心功能：

- 用户管理：注册、登录、个人中心
- 音乐库管理：音乐浏览、搜索、分类查看
- 在线播放：音乐播放器、播放历史记录
- 个性化推荐：基于用户的协同过滤推荐算法
- 用户行为记录：播放、收藏等行为追踪

## 技术栈

### 后端
- Java 8+
- Spring Boot 2.7.14
- MyBatis 2.3.1
- MySQL 5.7+
- JWT（JSON Web Token）

### 前端
- Vue.js 2.6.14
- Vue Router 3.5.4
- Vuex 3.6.2
- Element UI 2.15.13
- Axios 0.27.2
- Webpack 5

### 推荐算法
- 基于用户的协同过滤（User-Based Collaborative Filtering）
- 皮尔逊相关系数相似度计算

## 项目结构

```
MusicRecommendation/
├── backend/                 # 后端Spring Boot项目
│   ├── src/
│   │   ├── main/
│   │   │   ├── java/
│   │   │   │   └── com/music/recommendation/
│   │   │   │       ├── controller/     # 控制器层
│   │   │   │       ├── service/        # 服务层
│   │   │   │       ├── dao/            # 数据访问层
│   │   │   │       ├── entity/         # 实体类
│   │   │   │       ├── dto/            # 数据传输对象
│   │   │   │       ├── config/         # 配置类
│   │   │   │       └── util/           # 工具类
│   │   │   └── resources/
│   │   │       ├── mapper/             # MyBatis映射文件
│   │   │       └── application.yml     # 应用配置
│   │   └── test/
│   └── pom.xml                         # Maven配置
├── frontend/                # 前端Vue项目
│   ├── src/
│   │   ├── api/            # API接口
│   │   ├── assets/         # 静态资源
│   │   ├── components/     # 组件
│   │   ├── router/         # 路由配置
│   │   ├── store/          # Vuex状态管理
│   │   ├── views/          # 页面组件
│   │   ├── App.vue         # 根组件
│   │   └── main.js         # 入口文件
│   ├── build/              # Webpack构建配置
│   ├── config/             # 项目配置
│   ├── index.html          # HTML模板
│   └── package.json        # npm配置
├── database/               # 数据库脚本
│   └── init.sql            # 数据库初始化脚本
├── docs/                   # 设计文档
└── README.md               # 项目说明
```

## 快速开始

### 环境要求

- JDK 1.8+
- Node.js 12+
- MySQL 5.7+
- Maven 3.6+

### 数据库初始化

1. 创建数据库：
```sql
CREATE DATABASE music_recommendation DEFAULT CHARACTER SET utf8mb4;
```

2. 执行初始化脚本：
```bash
mysql -u root -p music_recommendation < database/init.sql
```

3. 配置数据库连接（`backend/src/main/resources/application.yml`）：
```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/music_recommendation
    username: root
    password: your_password
```

### 后端启动

1. 进入后端目录：
```bash
cd backend
```

2. 使用Maven编译并运行：
```bash
mvn clean package
java -jar target/music-recommendation-1.0.0.jar
```

或在IDE中直接运行 `MusicRecommendationApplication.java`

后端服务启动成功后，访问：http://localhost:8080/api

### 前端启动

1. 进入前端目录：
```bash
cd frontend
```

2. 安装依赖：
```bash
npm install
```

3. 启动开发服务器：
```bash
npm run dev
```

前端服务启动成功后，访问：http://localhost:8081

### 生产环境部署

1. 构建前端项目：
```bash
cd frontend
npm run build
```

2. 将 `frontend/dist` 目录下的静态文件部署到Web服务器

3. 打包后端项目：
```bash
cd backend
mvn clean package
```

4. 运行后端JAR包：
```bash
java -jar target/music-recommendation-1.0.0.jar
```

## 测试账号

系统初始化后，可以使用以下测试账号登录：

| 用户类型 | 用户名 | 密码 | 权限 |
|---------|--------|------|------|
| 管理员 | admin | 123456 | 全部功能 |
| 普通用户 | user1 | 123456 | 基础功能 |
| 普通用户 | user2 | 123456 | 基础功能 |
| 普通用户 | user3 | 123456 | 基础功能 |
| 普通用户 | user4 | 123456 | 基础功能 |
| 普通用户 | user5 | 123456 | 基础功能 |

## 功能说明

### 1. 用户功能
- 用户注册/登录
- 查看个人信息
- 查看播放历史
- 音乐收藏（待完善）

### 2. 音乐功能
- 浏览所有音乐
- 搜索音乐（按标题/艺术家）
- 按类型分类浏览
- 在线播放音乐
- 查看热门音乐

### 3. 推荐功能
- 基于用户行为的个性化推荐
- 基于用户的协同过滤算法
- 推荐相似用户喜欢的音乐

### 4. 管理员功能
- 音乐管理（添加、编辑、删除）
- 用户管理（待完善）

## 推荐算法说明

### 基于用户的协同过滤（User-Based CF）

#### 算法原理

1. **数据收集**：收集用户-音乐评分矩阵（基于用户行为）
2. **相似度计算**：使用皮尔逊相关系数计算用户之间的相似度
3. **最近邻查找**：找到与目标用户最相似的K个用户
4. **推荐生成**：根据相似用户的喜好，预测目标用户对未听音乐的评分
5. **Top-N推荐**：返回预测评分最高的N首音乐

#### 行为评分规则

- 播放：1分
- 收藏：5分
- 分享：3分
- 下载：4分

#### 相似度计算

采用皮尔逊相关系数（Pearson Correlation Coefficient）：

```
sim(u,v) = Σ((r_ui - r_u_avg) * (r_vi - r_v_avg)) / (sqrt(Σ(r_ui - r_u_avg)²) * sqrt(Σ(r_vi - r_v_avg)²))
```

其中：
- u, v 表示两个用户
- r_ui 表示用户u对音乐i的评分
- r_u_avg 表示用户u的平均评分

## API接口文档

### 用户相关接口

| 接口 | 方法 | 说明 |
|-----|------|------|
| /api/user/register | POST | 用户注册 |
| /api/user/login | POST | 用户登录 |
| /api/user/info | GET | 获取用户信息 |
| /api/user/validate | GET | 验证Token |

### 音乐相关接口

| 接口 | 方法 | 说明 |
|-----|------|------|
| /api/music/list | GET | 获取所有音乐 |
| /api/music/page | GET | 分页获取音乐 |
| /api/music/{id} | GET | 获取音乐详情 |
| /api/music/search | GET | 搜索音乐 |
| /api/music/hot | GET | 获取热门音乐 |
| /api/music/genre/{genre} | GET | 按类型获取音乐 |
| /api/music/play/{id} | POST | 播放音乐 |
| /api/music/favorite/{id} | POST | 收藏音乐 |
| /api/music/history | GET | 获取播放历史 |
| /api/music/recommend | GET | 获取个性化推荐 |
| /api/music/add | POST | 添加音乐（管理员） |
| /api/music/update/{id} | PUT | 更新音乐（管理员） |
| /api/music/delete/{id} | DELETE | 删除音乐（管理员） |

## 配置说明

### 后端配置（application.yml）

```yaml
server:
  port: 8080                    # 服务端口

spring:
  datasource:
    url: jdbc:mysql://localhost:3306/music_recommendation
    username: root
    password: your_password

mybatis:
  mapper-locations: classpath:mapper/*.xml

jwt:
  secret: your-secret-key       # JWT密钥
  expiration: 86400000          # Token过期时间（24小时）

recommendation:
  user-cf:
    min-common-items: 3         # 最小共同物品数
    max-nearest-users: 20       # 最大最近邻用户数
    top-n: 10                   # 推荐Top N音乐
```

### 前端配置（config/index.js）

```javascript
module.exports = {
  dev: {
    port: 8081,                 // 开发服务器端口
    proxyTable: {
      '/api': {
        target: 'http://localhost:8080',  // 后端API地址
        changeOrigin: true
      }
    }
  }
}
```

## 注意事项

1. **密码安全**：当前版本使用MD5加密，生产环境建议使用BCrypt等更安全的加密方式
2. **音频资源**：示例中的音乐URL为占位符，实际使用需要替换为真实的音频资源
3. **图片资源**：封面图片使用SVG占位符，实际使用需要替换为真实图片
4. **Token过期**：默认24小时，可根据需求调整
5. **推荐效果**：需要积累足够的用户行为数据才能产生较好的推荐效果

## 开发规范

### 代码规范
- 遵循阿里巴巴Java开发规范
- 前端遵循Vue.js风格指南
- 使用ES6+语法特性

### Git提交规范
- feat: 新功能
- fix: 修复bug
- docs: 文档更新
- style: 代码格式调整
- refactor: 重构代码
- test: 测试相关
- chore: 构建/工具相关

## 常见问题

**Q: 启动后端时提示数据库连接失败？**
A: 检查MySQL服务是否启动，数据库是否创建，用户名密码是否正确。

**Q: 前端无法访问后端API？**
A: 检查后端是否正常启动，端口配置是否正确，跨域配置是否生效。

**Q: 推荐列表为空？**
A: 新用户或行为数据较少时推荐列表可能为空，需要积累用户行为数据。

**Q: 音频无法播放？**
A: 检查音乐URL是否正确，浏览器是否支持该音频格式。

## 贡献指南

欢迎提交Issue和Pull Request！

## 许可证

本项目仅用于学习交流。

## 作者

MusicRecommendation Team

## 致谢

感谢所有开源项目的贡献者！

---

**最后更新时间：2024-02-22**