Three F - 综合性Web应用平台

项目简介

Three F 是一个基于 Spring Boot 3.5.3 开发的综合性Web应用平台，集成了用户管理、实时聊天和文件传输三大核心功能模块。

Portfolio Context

这个仓库更像一个 综合后端能力展示项目，把认证、实时通信、文件处理三类常见业务模块放进同一个 Spring Boot 应用里。

它体现的能力

• Spring Boot 分层设计
• JWT + 权限控制
• WebSocket 实时通信
• 文件上传 / 分享 / 访问控制
• MySQL + Redis 组合式后端架构

核心功能

🔐 用户管理模块

• 用户注册：支持用户名、邮箱、密码验证
• 用户登录：JWT令牌认证 + 会话管理
• 权限控制：基于角色的访问控制（RBAC）
• 用户状态：在线/离线/忙碌/离开状态管理

💬 实时聊天模块

• 私聊功能：一对一实时消息传递
• 群组聊天：支持群组创建、管理和聊天
• 消息类型：文本、图片、文件、语音、视频消息
• 消息历史：完整的消息记录和搜索
• 已读状态：消息已读回执功能

📁 文件传输模块

• 文件上传：支持多种文件格式上传
• 文件下载：安全的文件下载机制
• 文件分享：私人分享、群组分享、公开分享
• 权限控制：基于用户和群组的文件访问控制
• 存储管理：文件去重、存储统计

技术架构

后端技术栈

• 框架：Spring Boot 3.5.3
• 安全：Spring Security + JWT
• 数据访问：Spring Data JPA
• 实时通信：Spring WebSocket + STOMP
• 数据库：MySQL 8.0
• 缓存：Redis
• 文件存储：本地存储（可扩展为MinIO/AWS S3）

项目结构

src/main/java/com/sakura/three_f/
├── config/              # 配置类
│   ├── SecurityConfig.java
│   └── WebSocketConfig.java
├── controller/          # 控制器层
│   ├── AuthController.java
│   ├── ChatController.java
│   └── FileController.java
├── dto/                 # 数据传输对象
│   ├── UserDTO.java
│   ├── MessageDTO.java
│   ├── ChatGroupDTO.java
│   └── FileInfoDTO.java
├── entity/              # 实体类
│   ├── User.java
│   ├── Message.java
│   ├── ChatGroup.java
│   ├── FileInfo.java
│   └── FileShare.java
├── repository/          # 数据访问层
│   ├── UserRepository.java
│   ├── MessageRepository.java
│   ├── ChatGroupRepository.java
│   └── FileInfoRepository.java
├── security/            # 安全相关
│   ├── JwtAuthenticationFilter.java
│   └── JwtAuthenticationEntryPoint.java
├── service/             # 服务层
│   ├── UserService.java
│   ├── MessageService.java
│   └── FileService.java
├── util/                # 工具类
│   └── JwtUtil.java
└── ThreeFApplication.java

数据库设计

主要数据表

• users: 用户信息表
• chat_groups: 聊天群组表
• group_members: 群组成员关联表
• messages: 消息表
• file_info: 文件信息表
• file_shares: 文件分享表

API接口文档

认证接口

• POST /api/auth/register - 用户注册
• POST /api/auth/login - 用户登录
• GET /api/auth/me - 获取当前用户信息
• POST /api/auth/logout - 用户登出

文件接口

• POST /api/files/upload - 文件上传
• GET /api/files/download/{id} - 文件下载
• GET /api/files/my - 获取用户文件列表
• GET /api/files/public - 获取公开文件列表
• DELETE /api/files/{id} - 删除文件

WebSocket接口

• /ws - WebSocket连接端点
• /app/chat.sendPrivateMessage - 发送私聊消息
• /app/chat.sendGroupMessage - 发送群组消息
• /topic/group/{groupId} - 群组消息订阅
• /user/queue/messages - 私人消息队列

快速开始

环境要求

• Java 17+
• MySQL 8.0+
• Redis 6.0+
• Maven 3.6+

安装步骤

1. 克隆项目

git clone <repository-url>
cd three_f

2. 配置数据库

CREATE DATABASE three_f CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

3. 修改配置文件 编辑 src/main/resources/application.properties：

spring.datasource.url=jdbc:mysql://localhost:3306/three_f
spring.datasource.username=your_username
spring.datasource.password=your_password

4. 启动Redis

redis-server

5. 运行应用

./gradlew bootRun

6. 访问应用

• 应用地址：http://localhost:8080
• API文档：http://localhost:8080/swagger-ui.html（如果集成了Swagger）

使用示例

用户注册

curl -X POST http://localhost:8080/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "testuser",
    "email": "test@example.com",
    "password": "password123",
    "nickName": "测试用户"
  }'

用户登录

curl -X POST http://localhost:8080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "usernameOrEmail": "testuser",
    "password": "password123"
  }'

文件上传

curl -X POST http://localhost:8080/api/files/upload \
  -H "Authorization: Bearer <your-jwt-token>" \
  -F "file=@/path/to/your/file.txt" \
  -F "description=测试文件" \
  -F "isPublic=false"

扩展功能

计划中的功能

• 语音/视频通话
• 消息加密
• 文件预览
• 移动端适配
• 国际化支持
• 插件系统

性能优化

• 数据库分库分表
• 消息队列集成
• CDN文件分发
• 缓存策略优化

贡献指南

1. Fork 项目
2. 创建功能分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证 - 查看 LICENSE 文件了解详情。

联系方式

• 项目维护者：Sakura
• 邮箱：sakura@example.com
• 项目地址：https://github.com/sakura/three_f