# user-matching-system

**Repository Path**: RicheFactory/user-matching-system

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-20
- **Last Updated**: 2025-11-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 用户匹配系统 (User Matching System)

## 📋 项目简介

用户匹配系统是一个基于 Spring Boot + 前后端分离架构的社交团队协作平台。系统实现了用户注册、登录、个人信息管理、智能用户匹配、团队创建与管理等核心功能,旨在帮助用户快速找到志同道合的伙伴并组建团队。

### ✨ 核心功能

- **用户管理**
  - 用户注册与登录
  - 用户信息维护（头像、昵称、性别、联系方式等）
  - 基于标签的用户搜索
  - 智能用户推荐与匹配算法
  - Session 会话管理（基于 Redis）

- **团队管理**
  - 创建团队（支持公开/私有/加密三种状态）
  - 加入/退出团队
  - 解散团队
  - 团队信息编辑
  - 查看我的团队列表
  - 团队成员管理

- **系统特性**
  - Redis 缓存优化（用户推荐列表缓存）
  - Redisson 分布式锁（防止并发问题）
  - 定时任务（用户数据预缓存）
  - MyBatis-Plus 逻辑删除
  - 全局异常处理
  - 统一返回结果封装

---

## 🏗️ 技术架构

### 后端技术栈

| 技术 | 版本 | 说明 |
|------|------|------|
| Java | 8 | 编程语言 |
| Spring Boot | 2.6.4 | 应用框架 |
| MyBatis-Plus | 3.5.3.1 | ORM 框架 |
| MySQL | 8.0.33 | 关系型数据库 |
| Redis | - | 缓存中间件 |
| Redisson | 3.17.5 | 分布式锁 |
| Spring Session | 2.6.4 | Session 管理 |
| Lombok | 1.18.24 | 代码简化工具 |
| Gson | 2.10.1 | JSON 处理 |
| Apache Commons | 3.12.0 | 工具类库 |

---

## 📁 项目结构

### 后端项目结构 (contract-backend)

```
contract-backend/
├── src/
│   ├── main/
│   │   ├── java/com/riche/contractbackend/
│   │   │   ├── common/              # 公共类
│   │   │   │   ├── BaseResponse.java     # 统一响应封装
│   │   │   │   ├── ErrorCode.java        # 错误码枚举
│   │   │   │   ├── PageRequest.java      # 分页请求对象
│   │   │   │   └── ResultUtils.java      # 结果工具类
│   │   │   ├── config/              # 配置类
│   │   │   │   ├── CorsConfig.java       # 跨域配置
│   │   │   │   ├── MybatisPlusConfig.java
│   │   │   │   ├── RedisConfig.java
│   │   │   │   ├── RedisTemplateConfig.java
│   │   │   │   └── RedissonConfig.java
│   │   │   ├── contant/             # 常量类
│   │   │   │   └── UserConstant.java
│   │   │   ├── controller/          # 控制层
│   │   │   │   ├── TeamController.java   # 团队接口
│   │   │   │   └── UserController.java   # 用户接口
│   │   │   ├── exception/           # 异常处理
│   │   │   │   ├── BusinessException.java
│   │   │   │   └── GlobalExceptionHandler.java
│   │   │   ├── handler/             # 处理器
│   │   │   │   ├── JacksonConfig.java
│   │   │   │   └── MyMetaObjectHandler.java
│   │   │   ├── job/                 # 定时任务
│   │   │   │   └── PreCacheJob.java      # 用户缓存预热
│   │   │   ├── mapper/              # 数据访问层
│   │   │   │   ├── TeamMapper.java
│   │   │   │   ├── UserMapper.java
│   │   │   │   └── UserTeamMapper.java
│   │   │   ├── model/               # 数据模型
│   │   │   │   ├── domain/          # 实体类
│   │   │   │   │   ├── Team.java
│   │   │   │   │   ├── User.java
│   │   │   │   │   └── UserTeam.java
│   │   │   │   ├── dto/             # 数据传输对象
│   │   │   │   │   └── TeamQuery.java
│   │   │   │   ├── enums/           # 枚举类
│   │   │   │   │   └── TeamStatusEnum.java
│   │   │   │   ├── request/         # 请求对象
│   │   │   │   │   ├── TeamAddRequest.java
│   │   │   │   │   ├── TeamJoinRequest.java
│   │   │   │   │   ├── TeamQuiteRequest.java
│   │   │   │   │   ├── TeamUpdateRequest.java
│   │   │   │   │   ├── UserLoginRequest.java
│   │   │   │   │   └── UserRegisterRequest.java
│   │   │   │   └── vo/              # 视图对象
│   │   │   │       ├── TeamUserListVo.java
│   │   │   │       ├── TeamUserVO.java
│   │   │   │       └── UserVO.java
│   │   │   ├── once/                # 一次性任务
│   │   │   │   └── InsertUsers.java      # 批量插入用户
│   │   │   ├── service/             # 业务逻辑层
│   │   │   │   ├── impl/
│   │   │   │   │   ├── TeamServiceImpl.java
│   │   │   │   │   ├── UserServiceImpl.java
│   │   │   │   │   └── UserTeamServiceImpl.java
│   │   │   │   ├── TeamService.java
│   │   │   │   ├── UserService.java
│   │   │   │   └── UserTeamService.java
│   │   │   ├── utils/               # 工具类
│   │   │   │   └── AlgorithmUtils.java   # 匹配算法工具
│   │   │   └── ContractBackendApplication.java  # 启动类
│   │   └── resources/
│   │       ├── mapper/              # MyBatis XML 映射文件
│   │       │   ├── TeamMapper.xml
│   │       │   ├── UserMapper.xml
│   │       │   └── UserTeamMapper.xml
│   │       ├── application.yml      # 配置文件
│   │       └── application-prod.yml # 生产环境配置
│   └── test/                        # 测试代码
│       └── java/com/riche/contractbackend/
│           ├── service/
│           │   ├── AlgorithmUtilsTest.java
│           │   ├── RedissonTest.java
│           │   └── UserServiceTest.java
│           └── ContractBackendApplicationTests.java
├── sql/
│   └── tables.sql                   # 数据库建表脚本
├── Dockerfile                       # Docker 镜像构建文件
├── pom.xml                          # Maven 依赖配置
└── mvnw / mvnw.cmd                  # Maven Wrapper
```

---

## 🗄️ 数据库设计

### 用户表 (user)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| username | varchar(255) | 用户昵称 |
| userAccount | varchar(256) | 账号 |
| avatarUrl | varchar(255) | 头像地址 |
| gender | tinyint | 性别 |
| userPassword | varchar(512) | 密码（加密存储） |
| phone | varchar(20) | 电话 |
| email | varchar(512) | 邮箱 |
| userStatus | tinyint | 用户状态（0-无效 1-有效） |
| userRole | int | 角色（0-普通用户 1-管理员） |
| createTime | datetime | 创建时间 |
| updateTime | datetime | 更新时间 |
| isDelete | tinyint | 逻辑删除标记 |

### 团队表 (team)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| name | varchar(255) | 队伍名称 |
| description | varchar(1024) | 队伍描述 |
| maxNum | int | 最大人数 |
| expireTime | datetime | 过期时间 |
| status | tinyint | 状态（0-公开 1-私有 2-加密） |
| password | varchar(256) | 加密队伍密码 |
| userId | bigint | 创建人 ID |
| createTime | datetime | 创建时间 |
| updateTime | datetime | 更新时间 |
| isDelete | tinyint | 逻辑删除标记 |

### 用户-团队关联表 (user_team)

| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint | 主键 |
| userId | bigint | 用户 ID |
| teamId | bigint | 队伍 ID |
| joinTime | datetime | 加入时间 |
| createTime | datetime | 创建时间 |
| updateTime | datetime | 更新时间 |
| isDelete | tinyint | 逻辑删除标记 |

---

## 🚀 快速开始

### 环境要求

- JDK 8+
- Maven 3.5+
- MySQL 8.0+
- Redis 6.0+

### 后端启动步骤

#### 1. 克隆项目

```bash
git clone <项目地址>
cd user-matching-system/contract-backend
```

#### 2. 创建数据库

```bash
# 创建数据库
CREATE DATABASE yupi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

# 导入表结构
mysql -u root -p yupi < sql/tables.sql
```

#### 3. 修改配置文件

编辑 `src/main/resources/application.yml`：

```yaml
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/yupi?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai
    username: root
    password: 你的数据库密码
  redis:
    host: 127.0.0.1
    port: 6379
    database: 2
```

#### 4. 启动 Redis

```bash
redis-server
```

#### 5. 编译运行

```bash
# 使用 Maven 编译
mvn clean package -DskipTests

# 运行项目
java -jar target/contract-backend-0.0.1-SNAPSHOT.jar

# 或直接运行主类
mvn spring-boot:run
```

#### 6. 访问接口

服务启动后，默认访问地址：`http://localhost:8081/dev-api`

### Docker 部署

```bash
# 构建镜像
docker build -t contract-backend:latest .

# 运行容器
docker run -d -p 8081:8081 \
  -e SPRING_PROFILES_ACTIVE=prod \
  --name contract-backend \
  contract-backend:latest
```

---

## 📡 API 接口文档

### 用户相关接口

#### 用户注册
- **URL**: `POST /dev-api/user/register`
- **请求体**:
```json
{
  "userAccount": "testuser",
  "userPassword": "12345678",
  "checkPassword": "12345678"
}
```

#### 用户登录
- **URL**: `POST /dev-api/user/login`
- **请求体**:
```json
{
  "userAccount": "testuser",
  "userPassword": "12345678"
}
```

#### 获取当前用户
- **URL**: `GET /dev-api/user/current`
- **说明**: 需要登录状态

#### 更新用户信息
- **URL**: `POST /dev-api/user/update`
- **请求体**: User 对象

#### 推荐用户列表
- **URL**: `GET /dev-api/user/recommend?pageNum=1&pageSize=10`
- **说明**: 支持分页，结果会缓存 30 分钟

#### 标签搜索用户
- **URL**: `GET /dev-api/user/search/tags?tagNameList=Java,Python`

#### 匹配用户
- **URL**: `GET /dev-api/user/match?num=10`
- **说明**: 基于算法匹配最相似的用户

#### 用户登出
- **URL**: `POST /dev-api/user/logout`

### 团队相关接口

#### 创建团队
- **URL**: `POST /dev-api/team/add`
- **请求体**:
```json
{
  "name": "Java学习小组",
  "description": "一起学习Java技术",
  "maxNum": 10,
  "expireTime": "2025-12-31 23:59:59",
  "status": 0,
  "password": ""
}
```

#### 获取团队列表
- **URL**: `GET /dev-api/team/list`
- **参数**: TeamQuery 对象

#### 获取我的团队
- **URL**: `GET /dev-api/team/listMy`

#### 加入团队
- **URL**: `POST /dev-api/team/join`
- **请求体**:
```json
{
  "teamId": 1,
  "password": ""
}
```

#### 退出团队
- **URL**: `POST /dev-api/team/quit`
- **请求体**:
```json
{
  "teamId": 1
}
```

#### 更新团队信息
- **URL**: `POST /dev-api/team/update`
- **请求体**: TeamUpdateRequest 对象

#### 解散团队
- **URL**: `POST /dev-api/team/delete`
- **请求体**: teamId (long)

---

## 🔧 核心功能实现

### 1. 用户匹配算法

基于标签的用户相似度计算，使用编辑距离算法（详见 `AlgorithmUtils.java`）

### 2. Redis 缓存策略

- 用户推荐列表缓存（30 分钟过期）
- Session 会话存储
- 预缓存定时任务（`PreCacheJob.java`）

### 3. 分布式锁

使用 Redisson 实现分布式锁，防止用户重复加入同一队伍等并发问题

### 4. 全局异常处理

统一的异常处理机制（`GlobalExceptionHandler.java`），返回标准化错误信息

### 5. 逻辑删除

使用 MyBatis-Plus 的逻辑删除功能，所有删除操作仅更新 `isDelete` 字段

---

## 🛠️ 开发规范

### 代码分层

- **Controller 层**: 处理 HTTP 请求，参数校验
- **Service 层**: 业务逻辑实现
- **Mapper 层**: 数据访问操作
- **Model 层**: 数据模型定义

### 命名规范

- 实体类：`User.java`、`Team.java`
- 请求对象：`UserLoginRequest.java`
- 响应对象：`UserVO.java`、`TeamUserVO.java`
- DTO 对象：`TeamQuery.java`

### 返回结果统一封装

```java
BaseResponse<T> {
    code: 0,          // 0-成功，非0-失败
    data: T,          // 返回数据
    message: "成功",  // 提示信息
    description: ""   // 详细描述
}
```

---

## 📝 待优化事项

- [ ] 完善前端项目文档
- [ ] 添加单元测试覆盖率
- [ ] 接口文档自动生成（Swagger/Knife4j）
- [ ] 日志监控完善
- [ ] 性能优化与压测
- [ ] 消息队列集成（异步处理）
- [ ] 完善用户权限控制

---

## 👨‍💻 作者

- **开发者**: Gaoruiqi
- **邮箱**: 776409491@qq.com

---

## 📄 许可证

本项目采用 MIT 许可证。

---

## 🙏 致谢

感谢所有开源项目的贡献者，本项目使用了以下优秀的开源技术栈。