# WeTalk **Repository Path**: heruiheng/wetalk ## Basic Information - **Project Name**: WeTalk - **Description**: 基于netty + springboot + react的简易im系统 - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 2 - **Forks**: 0 - **Created**: 2026-02-04 - **Last Updated**: 2026-02-14 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # WeTalk ## 项目简介 WeTalk 是一个基于 React + Spring Boot + WebSocket 的实时聊天应用，提供了类似微信的聊天体验，支持私聊、群聊、联系人管理、群组管理等核心功能。 ![输入图片说明](wetalk-backend/src/main/resources/wetalk.png) ### 项目特点 - **实时通信**：基于 WebSocket 实现实时消息传递 - **多种消息类型**：支持文本、图片、语音、视频、文件等多媒体消息 - **联系人管理**：添加好友、处理好友请求、黑名单管理 - **群组功能**：创建群组、邀请成员、群组管理 - **文件上传**：支持头像上传、文件发送 - **未读消息**：智能未读消息计数和提醒 - **消息通知**：支持消息提示音和免打扰设置 - **隐私保护**：修改密码、账号安全设置 - **响应式设计**：适配不同屏幕尺寸 ## 技术栈 ### 前端 - **框架**：React 19.2.0 - **路由**：React Router DOM 7.13.0 - **HTTP 客户端**：Axios 1.13.4 - **语言**：TypeScript 5.9.3 - **构建工具**：Vite 7.2.4 - **样式**：Tailwind CSS 3.4.19 - **状态管理**：React Context + Hooks - **实时通信**：WebSocket ### 后端 - **框架**：Spring Boot 2.6.1 - **持久层**：MyBatis 2.2.0 - **数据库**：MySQL 8.0.23 - **缓存**：Redis - **实时通信**：Netty WebSocket - **认证**：JWT - **文件上传**：Spring Boot 文件上传 - **工具库**：Fastjson、Apache Commons ## 项目结构 ``` WeTalk/ ├── wetalk-frontend/ # 前端项目 │ ├── web/ # Web 前端 │ ├── public/ # 静态资源 │ ├── src/ # 源代码 │ ├── assets/ # 资源文件 │ ├── components/ # React 组件 │ ├── contexts/ # React Context │ ├── hooks/ # 自定义 Hooks │ ├── pages/ # 页面组件 │ ├── services/ # API 服务 │ ├── types/ # TypeScript 类型 │ ├── utils/ # 工具函数 │ ├── constants/ # 常量定义 │ ├── styles/ # 样式文件 │ ├── App.tsx # 应用入口 │ └── main.tsx # 主文件 │ ├── package.json # 依赖配置 │ └── vite.config.ts # Vite 配置 ├── wetalk-backend/ # 后端项目 │ ├── src/ # 源代码 │ ├── main/ # 主代码 │ ├── java/ # Java 代码 │ └── hrh/code/wetalkbackend/ # 后端代码 │ ├── common/ # 公共模块 │ ├── config/ # 配置 │ ├── dao/ # 数据访问 │ ├── domain/ # 领域模型 │ ├── provider/ # 控制器 │ ├── service/ # 服务 │ └── websocket/ # WebSocket │ ├── resources/ # 资源文件 │ ├── mapper/ # MyBatis 映射 │ └── application.yml # 应用配置 │ └── test/ # 测试代码 │ ├── pom.xml # Maven 配置 │ └── uploads/ # 上传文件存储 └── doc/ # 项目文档 ├── 前端项目架构文档.md └── 后端项目架构文档.md ``` ## 核心功能 ### 1. 认证系统 - 用户注册和登录 - JWT Token 认证 - 密码修改 - 登录状态管理 ### 2. 实时通信 - WebSocket 连接管理 - 心跳保活机制 - 消息实时传递 - 自动重连策略 ### 3. 消息系统 - 发送和接收文本消息 - 多媒体消息支持 - 消息历史记录 - 未读消息计数 - 消息状态管理（发送中、已发送、已读） ### 4. 联系人管理 - 搜索用户 - 添加好友 - 处理好友请求 - 联系人详情查看 - 黑名单管理 - 联系人分组 ### 5. 群组功能 - 创建群组 - 邀请成员加入群组 - 群组详情查看 - 群组成员管理 - 群组消息 - 群聊邀请处理 ### 6. 文件上传 - 头像上传 - 图片、语音、视频、文件上传 - 文件类型验证 - 上传进度显示 ### 7. 系统设置 - 消息通知声音设置 - 免打扰设置 - 隐私设置 - 账号安全 ## 快速开始 ### 前端环境搭建 1. **安装依赖** ```bash # 进入前端目录 cd wetalk-frontend/web # 安装依赖 npm install ``` 2. **配置环境变量** 在 `wetalk-frontend/web/.env` 文件中配置： ```env VITE_API_BASE_URL=http://localhost:8080/api VITE_WS_BASE_URL=ws://localhost:8081/ws ``` 3. **启动开发服务器** ```bash npm run dev ``` ### 后端环境搭建 1. **配置数据库** 创建 MySQL 数据库 `wetalk`，并执行 `wetalk-backend/src/main/resources/sql/full_database_schema.sql` 初始化表结构。 2. **配置 application.yml** 修改 `wetalk-backend/src/main/resources/application.yml` 中的数据库连接信息： ```yaml spring: datasource: url: jdbc:mysql://localhost:3306/wetalk?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai username: root password: 123456 ``` 3. **启动后端服务** ```bash # 进入后端目录 cd wetalk-backend # 启动服务 mvn spring-boot:run ``` ### 访问应用 前端服务启动后，访问 `http://localhost:5173` 即可进入 WeTalk 应用。 ## 详细功能说明 ### 1. 登录与注册 - **登录**：支持邮箱或用户ID登录 - **注册**：填写基本信息完成注册 - **忘记密码**：通过邮箱找回密码 ### 2. 消息功能 - **私聊**：与单个联系人的一对一聊天 - **群聊**：多人参与的群组聊天 - **消息历史**：加载历史消息，支持分页 - **消息状态**：显示消息发送状态和已读状态 - **多媒体消息**：发送和接收图片、语音、视频、文件 ### 3. 联系人管理 - **联系人列表**：显示所有联系人，支持按字母排序 - **添加好友**：通过用户ID或邮箱搜索并添加好友 - **好友请求**：处理收到的好友请求 - **联系人详情**：查看联系人详细信息 - **黑名单**：管理黑名单用户 ### 4. 群组功能 - **群组列表**：显示所有加入的群组 - **创建群组**：创建新群组并邀请成员 - **群组详情**：查看群组信息和成员列表 - **群组成员管理**：添加、移除成员，设置管理员 - **群组设置**：修改群组名称、头像、公告等 ### 5. 个人设置 - **个人资料**：修改昵称、头像、个性签名 - **账号安全**：修改密码、绑定邮箱 - **消息通知**：设置消息提示音和免打扰 - **隐私设置**：设置好友验证方式、陌生人消息 ## API 接口 ### 认证接口 - `POST /api/auth/login` - 用户登录 - `POST /api/auth/register` - 用户注册 - `POST /api/auth/change-password` - 修改密码 - `GET /api/auth/validate` - 验证 Token ### 消息接口 - `POST /api/message/send` - 发送消息 - `GET /api/message/history` - 获取消息历史 - `GET /api/message/unread/count` - 获取未读消息计数 - `POST /api/message/read` - 标记消息已读 ### 联系人接口 - `GET /api/contact/list` - 获取联系人列表 - `GET /api/contact/search` - 搜索用户 - `POST /api/contact/add` - 添加好友 - `GET /api/contact/request/list` - 获取好友申请列表 - `POST /api/contact/request/handle` - 处理好友申请 - `GET /api/contact/blacklist` - 获取黑名单 - `POST /api/contact/unblacklist` - 取消拉黑 ### 群组接口 - `POST /api/group/create` - 创建群组 - `GET /api/group/list` - 获取群组列表 - `GET /api/group/detail/{groupId}` - 获取群组详情 - `GET /api/group/members/{groupId}` - 获取群组成员列表 - `POST /api/group/dismiss` - 解散群组 - `POST /api/group/quit` - 退出群组 - `POST /api/group/removeMember` - 移除成员 - `POST /api/group/invite` - 邀请加入群聊 - `GET /api/group/invite` - 获取群聊邀请列表 - `PUT /api/group/invite/{inviteId}` - 处理群聊邀请 ### 文件接口 - `POST /api/file/upload` - 文件上传 - `POST /api/file/avatar` - 头像上传 ## 配置说明 ### 前端配置 #### 环境变量 - `VITE_API_BASE_URL`：后端 API 基础地址 - `VITE_WS_BASE_URL`：WebSocket 连接地址 #### 路由配置 前端路由配置位于 `src/constants/routes.ts`： ```typescript export const ROUTES = { HOME: "/", LOGIN: "/login", REGISTER: "/register", CHAT: "/chat/:chatType/:chatId", CONTACTS: "/contacts", GROUP_LIST: "/group/list", GROUP_DETAIL: "/group/detail/:groupId", GROUP_CREATE: "/group/create", SEARCH_USER: "/search-user", FRIEND_REQUEST: "/friend-request", BLACKLIST: "/blacklist", }; ``` ### 后端配置 #### 数据库配置 ```yaml spring: datasource: url: jdbc:mysql://localhost:3306/wetalk?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai username: root password: 123456 ``` #### WebSocket 配置 ```yaml websocket: port: 8081 path: /ws heartbeat-interval: 30000 max-frame-size: 10485760 ``` #### 文件上传配置 ```yaml file: upload-dir: uploads/ max-file-size: 10485760 max-request-size: 10485760 ``` ## 开发规范 ### 代码风格 - **前端**：使用 ESLint + Prettier 保持代码风格一致 - **后端**：遵循 Java 编码规范，使用 IDE 格式化 ### 命名规范 - **组件**：PascalCase（如 `WebChatPanel`） - **文件**：PascalCase（如 `LoginPage.tsx`） - **变量**：camelCase（如 `userInfo`） - **常量**：UPPER_SNAKE_CASE（如 `STORAGE_KEYS`） - **类型**：PascalCase（如 `UserInfo`） ### 注释规范 - 文件头部添加文件说明 - 复杂逻辑添加注释 - 公共函数添加 JSDoc - 类型定义添加说明 ### 提交规范 - 提交信息清晰明了 - 功能修改和 bug 修复分开提交 - 大型功能拆分为多个小提交 ## 部署说明 ### 前端部署 1. **构建生产版本** ```bash cd wetalk-frontend/web npm run build ``` 2. **部署到服务器** 将 `dist` 目录下的文件部署到 Nginx 或其他静态文件服务器。 ### 后端部署 1. **打包应用** ```bash cd wetalk-backend mvn clean package ``` 2. **部署到服务器** 将生成的 `wetalk-backend-0.0.1-SNAPSHOT.jar` 部署到服务器，使用 `java -jar` 命令启动。 ### 环境要求 - **前端**：Node.js >= 16.x - **后端**：JDK 1.8+, Maven 3.6+ - **数据库**：MySQL 8.0+ - **缓存**：Redis 6.0+ ## 常见问题 ### 1. WebSocket 连接失败 **解决方案**： - 检查后端 WebSocket 服务是否启动 - 确认 WebSocket 地址配置正确 - 检查网络连接是否正常 ### 2. 消息发送失败 **解决方案**： - 检查网络连接 - 确认用户是否在线 - 检查消息内容是否符合要求 ### 3. 文件上传失败 **解决方案**： - 检查文件大小是否超过限制 - 确认文件类型是否支持 - 检查网络连接 ### 4. 登录失败 **解决方案**： - 确认用户名和密码是否正确 - 检查网络连接 - 确认后端服务是否正常运行 ## 技术债务 ### 待优化项 1 . **单元测试**：添加前端和后端单元测试 2. **E2E 测试**：实现端到端测试 3. **消息撤回**：实现消息撤回功能 4. **消息转发**：支持消息转发 5. **国际化**：添加多语言支持 6. **首屏优化**：提高首屏加载速度 7. **离线消息**：实现离线消息缓存 8. **性能监控**：添加应用性能监控 9. **消息搜索**：实现消息内容搜索 10. **大文件上传**：优化大文件上传体验 ### 已知问题 - 在弱网络环境下，WebSocket 连接可能不稳定 - 大文件上传速度较慢 - 消息历史加载过多时可能影响性能 ## 参考资料 ### 技术文档 - [React 官方文档](https://react.dev/) - [TypeScript 官方文档](https://www.typescriptlang.org/) - [Spring Boot 官方文档](https://spring.io/projects/spring-boot) - [WebSocket MDN](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket) - [MyBatis 官方文档](https://mybatis.org/mybatis-3/) ### 设计规范 - [微信设计规范](https://weixin.qq.com/design) - [Material Design](https://material.io/design) - [Ant Design](https://ant.design/) ## 联系方式 ### 项目维护 - **项目负责人**：[待填写] - **技术支持**：[待填写] - **问题反馈**：[待填写] ### 开发团队 - **前端开发**：[待填写] - **后端开发**：[待填写] - **UI/UX 设计**：[待填写] ## 许可证 [MIT](LICENSE) ## 更新日志 ### v1.0.0 (2026-02-10) - 初始项目搭建 - 实现核心功能模块 - WebSocket 实时通信 - RESTful API 集成 ### v1.1.0 (2026-02-10) - 优化项目架构 - 完善前端组件 - 增强后端服务 - 提高系统稳定性 ### v1.2.0 (2026-02-10) - 新增联系人详情功能 - 优化群组管理 - 改进消息通知 - 增强隐私保护