Uniapp Backend 项目开发文档

基于 Spring Boot 3.x 的即时通讯后端系统

Spring Boot JWT 认证 WebSocket MySQL 实时通讯

项目概述

Uniapp Backend 是一个基于 Spring Boot 3.x 的即时通讯后端系统，提供完整的用户管理、实时聊天、群组管理、联系人管理等核心功能。

核心特性

🔐 JWT 认证系统

完整的用户和管理员认证体系，支持 Token 刷新和验证

💬 实时 WebSocket 通讯

基于 STOMP 协议的实时消息传递，支持私聊和群聊

👥 用户与群组管理

完整的用户资料管理和群组创建、管理功能

📱 移动端友好 API

专为移动应用设计的 RESTful API 接口

技术栈

Spring Boot 3.x
JPA/Hibernate
MySQL 8.0+
WebSocket STOMP
JWT 认证
Maven 3.6+
Lombok

项目结构

更新: 新增联系人相关的实体、Repository、Service和Controller
  • uniapp_backend/
    • config/
      • CorsConfig.java
      • DiagnosticFilter.java
      • JwtAuthenticationFilter.java
      • JwtTokenUtil.java
      • WebConfig.java
      • WebSocketConfig.java
    • controller/
      • AuthController.java
      • UserController.java
      • AdminController.java
      • ConversationController.java
      • MessageController.java
      • GroupController.java
      • ContactController.java [新增]
      • WebSocketController.java
    • entity/
      • User.java
      • Admin.java
      • Conversation.java
      • Message.java
      • ChatGroup.java
      • GroupMember.java
      • Contact.java [新增]
      • FriendRequest.java [新增]
      • ContactGroup.java [新增]
      • ApiResponse.java
    • repository/
      • UserRepository.java
      • AdminRepository.java
      • ConversationRepository.java
      • MessageRepository.java
      • ChatGroupRepository.java
      • GroupMemberRepository.java
      • ContactRepository.java [新增]
      • FriendRequestRepository.java [新增]
      • ContactGroupRepository.java [新增]
    • service/
      • UserService.java
      • ConversationService.java
      • MessageService.java
      • ChatGroupService.java
      • WebSocketService.java
      • ContactService.java [新增]
    • dto/
      • WebSocketMessage.java
      • AddFriendRequest.java [新增]
      • HandleFriendRequest.java [新增]
      • SendMessageRequest.java [新增]
      • UpdateContactRequest.java [新增]
      • CreateGroupRequest.java [新增]
      • MoveContactRequest.java [新增]
    • handler/
      • ChatWebSocketHandler.java
    • vo/
    • utils/
    • websocket/

数据库设计

更新: 新增联系人相关的数据库表结构

核心表结构

users 用户表

CREATE TABLE `users` ( `id` bigint NOT NULL AUTO_INCREMENT, `username` varchar(50) NOT NULL UNIQUE, `password` varchar(255) NOT NULL, `nickname` varchar(100), `email` varchar(100), `avatar` varchar(500), `gender` varchar(10), `birthday` date, `balance` decimal(10,2) DEFAULT '0.00', `status` int DEFAULT '1', `last_online` datetime, `used_invite_code` varchar(50), `ip` varchar(45), `created_at` datetime DEFAULT CURRENT_TIMESTAMP, `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`) );

conversations 对话表

CREATE TABLE `conversations` ( `id` bigint NOT NULL AUTO_INCREMENT, `conversation_id` varchar(100) NOT NULL UNIQUE, `user_id` bigint NOT NULL, `type` enum('FRIEND','GROUP','FUNCTION') NOT NULL, `target_id` varchar(100), `name` varchar(100), `avatar` varchar(500), `last_message` text, `unread_count` int DEFAULT '0', `is_top` tinyint(1) DEFAULT '0', `last_message_time` datetime, `member_count` int, `create_time` datetime DEFAULT CURRENT_TIMESTAMP, `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_user_id` (`user_id`), KEY `idx_conversation_id` (`conversation_id`) );

contacts 联系人表 [新增]

CREATE TABLE `contacts` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `user_id` bigint(20) NOT NULL COMMENT '用户ID', `friend_id` bigint(20) NOT NULL COMMENT '好友ID', `remark_name` varchar(100) DEFAULT NULL COMMENT '备注名', `contact_group` varchar(50) DEFAULT '默认' COMMENT '分组', `status` tinyint(1) DEFAULT '1' COMMENT '状态：1-正常，2-拉黑，3-删除', `created_time` datetime DEFAULT CURRENT_TIMESTAMP, `updated_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`), UNIQUE KEY `uk_user_friend` (`user_id`,`friend_id`), KEY `idx_user_id` (`user_id`), KEY `idx_friend_id` (`friend_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='联系人表';

friend_requests 好友申请表 [新增]

CREATE TABLE `friend_requests` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `from_user_id` bigint(20) NOT NULL COMMENT '申请人ID', `to_user_id` bigint(20) NOT NULL COMMENT '被申请人ID', `message` varchar(500) DEFAULT NULL COMMENT '申请消息', `status` tinyint(1) DEFAULT '0' COMMENT '状态：0-待处理，1-同意，2-拒绝，3-过期', `created_time` datetime DEFAULT CURRENT_TIMESTAMP, `updated_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_from_user` (`from_user_id`), KEY `idx_to_user` (`to_user_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='好友申请表';

contact_groups 联系人分组表 [新增]

CREATE TABLE `contact_groups` ( `id` bigint(20) NOT NULL AUTO_INCREMENT, `user_id` bigint(20) NOT NULL COMMENT '用户ID', `group_name` varchar(50) NOT NULL COMMENT '分组名称', `sort_order` int(11) DEFAULT '0' COMMENT '排序', `created_time` datetime DEFAULT CURRENT_TIMESTAMP, PRIMARY KEY (`id`), KEY `idx_user_id` (`user_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='联系人分组表';

API 接口文档

更新: 新增联系人API接口，包含完整的联系人管理功能

🔐 认证接口 (AuthController)

方法 路径 功能 参数
POST /api/auth/login 用户登录 username, password
POST /api/auth/register 用户注册 User 对象
POST /api/auth/verify Token验证 Header: Authorization
POST /api/auth/refresh Token刷新 Header: Authorization

👤 用户接口 (UserController)

方法 路径 功能 认证
POST /api/user/register 用户注册 否
POST /api/user/login 用户登录 否
GET /api/user/info 获取用户信息 是
POST /api/user/update 更新用户信息 是

💬 对话接口 (ConversationController)

方法 路径 功能 认证
GET /api/conversations 对话列表 是
POST /api/conversations/{id}/read 标记已读 是
DELETE /api/conversations/{id} 删除对话 是
POST /api/conversations/{id}/top 置顶对话 是

👥 联系人接口 (ContactController) [新增]

方法 路径 功能 认证
GET /api/contacts 获取联系人列表 是
POST /api/contacts/friend-request 发送好友申请 是
POST /api/contacts/handle-friend-request 处理好友申请 是
GET /api/contacts/friend-requests 获取好友申请列表 是
PUT /api/contacts/update 更新联系人信息 是
DELETE /api/contacts/{contactId} 删除联系人 是
POST /api/contacts/{contactId}/block 拉黑联系人 是
GET /api/contacts/search 搜索用户 是
POST /api/contacts/send-message 发送消息给联系人 是
POST /api/contacts/groups 创建联系人分组 是
GET /api/contacts/groups 获取联系人分组列表 是
DELETE /api/contacts/groups/{groupId} 删除联系人分组 是
POST /api/contacts/move-to-group 移动联系人到其他分组 是
GET /api/contacts/friend-requests/count 获取待处理的好友申请数量 是
GET /api/contacts/group/{groupName} 根据分组获取联系人 是

代码开发规范

控制器开发模板

@RestController @RequestMapping("/api/模块名") public class XxxController { @Autowired private XxxService xxxService; @GetMapping("/功能") public ApiResponse<?> getFunction(HttpServletRequest request, @RequestParam(required = false) String param) { try { // 1. 获取用户信息 Long userId = (Long) request.getAttribute("userId"); if (userId == null) { return ApiResponse.error(401, "用户未登录"); } // 2. 参数验证 if (param == null || param.trim().isEmpty()) { return ApiResponse.error(400, "参数不能为空"); } // 3. 调用服务 Object result = xxxService.businessMethod(userId, param); // 4. 返回成功响应 return ApiResponse.success(result); } catch (Exception e) { // 5. 统一异常处理 return ApiResponse.error(500, "操作失败: " + e.getMessage()); } } }

服务层开发模板

@Service public class XxxService { @Autowired private XxxRepository xxxRepository; @Transactional public Object businessMethod(Long userId, Object param) { // 1. 参数验证 if (param == null) { throw new RuntimeException("参数不能为空"); } // 2. 业务逻辑处理 // 3. 数据持久化 // 4. 返回结果 return result; } }

WebSocket 实时通讯

连接配置

// WebSocket 端点 ws://localhost:8080/websocket ws://localhost:8080/ws // 消息目的地前缀 /app - 应用消息前缀 /topic - 广播消息 /queue - 点对点消息 /user - 用户专属消息

支持的消息类型

消息类型 处理器 功能
get_conversation_list ChatWebSocketHandler 获取对话列表
mark_as_read ChatWebSocketHandler 标记对话已读
set_top ChatWebSocketHandler 设置对话置顶
send_message ChatWebSocketHandler 发送消息
recall_message ChatWebSocketHandler 撤回消息
create_group ChatWebSocketHandler 创建群组
join_group ChatWebSocketHandler 加入群组

部署指南

环境要求

部署步骤

  1. 克隆项目: git clone {repository-url}
  2. 配置数据库: 创建数据库并修改配置文件
  3. 构建项目: mvn clean package
  4. 运行应用: java -jar target/uniapp-backend.jar
  5. 验证部署: 访问 http://localhost:8080/test