# IMChat

**Repository Path**: hackerSnail/imchat

## Basic Information

- **Project Name**: IMChat
- **Description**: 聊天室demo
- **Primary Language**: Unknown
- **License**: AFL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-14
- **Last Updated**: 2026-08-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

即时聊天系统 — 项目结构与工具选型

![1786642458479](image/聊天系统设计大纲/1786642458479.png)
一、项目总体结构
本项目采用前后端分离的架构设计，后端提供 RESTful API 与 WebSocket 实时通信服务，前端负责界面交互、状态管理与实时消息渲染。系统支持单聊、群聊、离线消息、文件传输等核心功能，并基于 OAuth2 实现统一认证鉴权。

顶层目录结构如下：

im-chat-frontend/：前端 Vue3 + TypeScript 工程

im-chat-backend/：后端 Spring Boot 工程

docs/：架构设计文档、API 接口文档、数据库设计文档

scripts/：数据库初始化脚本、部署脚本

docker-compose.yml：本地开发环境服务编排（MySQL、Redis、MinIO）

二、前端项目结构

im-chat-frontend/
── public/                    # 静态资源（favicon、无需编译的第三方库）
── src/
│   ├── assets/               # 图片、字体等资源，由构建工具处理
│   ├── components/           # 通用 UI 组件（按钮、输入框、弹窗等）
│   │   ├── chat/             # 聊天相关组件（消息列表、输入框、会话列表）
│   │   ├── friend/           # 好友相关组件（好友列表、搜索添加）
│   │   └── group/            # 群组相关组件（群成员管理、群公告）
│   ├── views/                # 页面级组件（登录、主界面、会话窗口）
│   ├── stores/               # Pinia 状态管理（用户、会话、消息模块）
│   ├── services/             # 接口适配层（Axios REST 客户端 + STOMP WebSocket 客户端）
│   ├── utils/                # 工具函数（本地存储、日期格式化、消息校验）
│   ├── types/                # TypeScript 类型定义（API 响应、消息实体等）
│   ├── router/               # Vue Router 路由配置
│   ├── config/               # 全局配置（API 基础地址、WebSocket 端点）
│   ├── App.vue               # 根组件
│   └── main.ts               # 入口文件
── .env                       # 环境变量
── package.json               # 依赖与脚本
── tsconfig.json              # TypeScript 配置
── vite.config.ts             # Vite 构建配置
三、后端项目结构

im-chat-backend/
── src/main/java/com/imchat/
│   ├── config/                    # 配置类（WebSocket、Redis、跨域、OAuth2 资源服务器）
│   ├── controller/                # RESTful 控制器（会话、消息、文件、群组）
│   ├── websocket/                 # WebSocket 消息处理器（STOMP 端点、拦截器）
│   ├── service/                   # 业务逻辑接口
│   │   └── impl/                  # 业务逻辑实现（单聊、群聊、离线、文件传输、在线状态）
│   ├── mapper/                    # MyBatis Plus 数据访问层接口
│   ├── entity/                    # 数据库实体（用户、群组、会话、消息、文件元数据）
│   ├── dto/                       # 数据传输对象（请求/响应封装）
│   ├── security/                  # OAuth2 认证与权限组件
│   ├── util/                      # 工具类（JWT 操作、Redis 工具、雪花 ID 生成器）
│   └── ImChatApplication.java    # Spring Boot 启动类
── src/main/resources/
│   ├── application.yml            # 主配置文件
│   ├── application-dev.yml        # 开发环境配置
│   ├── application-prod.yml       # 生产环境配置
│   └── mapper/                    # MyBatis XML 映射文件（复杂 SQL）
── src/test/                       # 单元测试与集成测试
── Dockerfile                      # 容器化构建文件
── pom.xml                         # Maven 依赖管理
四、开发工具选型
工具类别	推荐工具	版本/说明	用途
前端 IDE	Visual Studio Code	最新稳定版	前端代码编写、调试及插件生态
后端 IDE	IntelliJ IDEA	最新稳定版	Java 开发，Spring 框架深度支持
版本控制	Git + GitHub	最新稳定版	代码管理与团队协作
前端构建工具	Vite + pnpm	Vite 5.x / pnpm 8.x	极速启动、热更新及依赖管理
后端构建工具	Maven	3.9.x	项目构建、依赖解析与生命周期管理
数据库	MySQL	8.0.x	业务数据持久化
缓存/状态存储	Redis	7.0.x	会话状态、在线状态、离线队列、热点缓存
对象存储	MinIO	最新稳定版	聊天文件（图片、视频、附件）存储
数据库管理工具	Navicat Premium / DBeaver	最新稳定版	MySQL 可视化操作与数据管理
Redis 管理工具	RedisInsight	最新稳定版	Redis 数据查看与监控
API 调试工具	Apifox / Postman	最新稳定版	接口测试、Mock 与文档生成
容器化与编排	Docker + Docker Compose	最新稳定版	开发环境一致性及快速部署
反向代理/服务器	Nginx	1.24.x	前端静态托管、后端接口反向代理（含 WebSocket）
测试工具	Vitest + JUnit 5	最新稳定版	前端单元测试、后端单元/集成测试
AI 辅助开发	Cursor / GitHub Copilot	最新稳定版	Vibe Coding 下的智能代码补全与生成
代码质量	ESLint + Prettier + SonarQube	最新稳定版	前端代码格式化、后端代码质量审查
日志与监控	SLF4J + Prometheus + Grafana	最新稳定版	后端日志记录、性能指标采集与可视化监控
五、工具选型说明

1. 前端构建工具选择 Vite
   Vite 基于原生 ES Modules，开发环境下无需打包即可启动，热更新极快。对于需要频繁调试实时通信和界面交互的聊天系统，Vite 能显著提升开发效率。
2. 后端框架选择 Spring Boot
   Spring Boot 生态系统成熟，自动配置简化了 WebSocket、MyBatis Plus、Redis、OAuth2 等组件的整合，使开发人员能专注于业务逻辑（消息路由、离线处理等）的实现。
3. 双协议通信设计
   WebSocket + STOMP：承载实时消息收发、状态同步，保证低延迟。

RESTful API：处理历史消息拉取、文件上传初始化等批量或非实时操作。

4. 存储架构
   MySQL 存储所有持久化数据（会话三表模型）。

Redis 管理在线状态、离线消息队列、会话摘要缓存及集群同步（Pub/Sub）。

MinIO 存储文件分片，与后端通过内网 192.168.25.50 通信，减轻后端 IO 压力。

5. Vibe Coding 场景下的 AI 辅助
   利用 Cursor 或 GitHub Copilot 可快速生成模板代码（如 CRUD 接口、WebSocket 事件处理、Redis 操作），减少重复劳动，让开发者将更多精力放在整体架构与交互体验设计上。
6. 开发与生产环境差异
   开发环境：使用 Vite devServer 代理解决跨域，多端口启动模拟多用户。

生产环境：Nginx 反向代理，后端集群部署，WebSocket 会话共享 Redis，通过负载均衡实现水平扩展。

即时聊天系统 — 后端架构设计（backend.md）
一、整体架构分层
后端采用五层架构，严格遵循“高内聚、低耦合”原则：

层级	包名	职责
接入适配层	controller	处理 RESTful API 请求及 WebSocket 消息收发，负责协议适配与路由
业务领域层	service	实现核心业务逻辑（单聊、群聊、离线、文件、会话、在线状态、已读回执）
数据访问层	mapper	通过 MyBatis Plus 操作 MySQL 数据库，提供 CRUD 及复杂查询
基础设施层	config/util	MySQL、Redis、MinIO、WebSocket 消息代理、本地会话池等配置与工具
安全控制层	security	OAuth2 认证、权限拦截、数据脱敏、安全审计日志
二、核心模块说明

1. 接入适配层（controller + websocket）
   REST Controllers：提供 /api/ 前缀的接口，如会话管理、历史消息分页、文件上传初始化、好友/群组操作。

WebSocket 处理器：

端点：/ws/chat（STOMP 协议）

鉴权：握手时通过 access_token 查询参数校验，并绑定用户身份。

路由：消息发送统一目的地 /app/im，根据业务类型分发至对应服务。

订阅：用户专属通道 /user/{userId}/queue/private（私聊）、/user/{userId}/queue/group（群聊）、/user/{userId}/queue/conversation（会话更新）。

2. 业务领域层（service/impl）
   核心服务及其职责：

单聊服务：校验好友关系 → 消息持久化 → 判断接收方在线状态 → 实时推送或存入离线队列。

群聊服务：校验成员身份 → 消息持久化 → 遍历所有群成员，分别推送或离线存储（异步多线程）。

会话管理服务：创建会话、拉取列表、更新摘要、处理置顶/免打扰、标记已读。

离线消息服务：使用 Redis List 存储离线消息，用户上线后批量拉取并按序推送，推送成功移除队列。

文件传输服务：接收分片存储至 MinIO，合并文件后生成元数据并入库，实时推送传输进度。

在线状态服务：管理用户 WebSocket 会话生命周期，存储于 Redis，并提供集群内跨节点路由。

已读回执服务：接收客户端已读事件，更新会话成员表中的未读数，并同步给消息发送方。

所有业务操作均包裹在数据库事务中，确保“先落库后推送”的可靠性原则。

3. 数据访问层（mapper）
   继承 MyBatis Plus 的 BaseMapper，提供基础 CRUD。

复杂查询（如历史消息分页）通过 XML 映射文件编写 SQL，利用 conversation_id 和 send_time 联合索引优化性能。

4. 基础设施层（config/util）
   MySQL：持久化存储，地址 192.168.25.50:3306。

Redis：存储在线状态、会话信息、离线队列、热点消息、OAuth2 令牌，并用作 Pub/Sub 集群消息广播，地址 192.168.25.50:6379。

MinIO：文件存储，地址 http://192.168.25.50:9000，生成临时预签名 URL 供前端直传/下载。

本地会话池：ConcurrentHashMap 维护当前节点活跃连接，与 Redis 中心会话共同支撑多端在线。

5. 安全控制层（security）
   OAuth2 资源服务器：基于 Spring Authorization Server，JWT 令牌，拦截所有请求校验。

WebSocket 拦截器：握手阶段校验令牌，并绑定连接与用户；消息收发阶段二次校验权限。

数据脱敏：BCrypt 加密密码，敏感字段传输时脱敏。

审计日志：记录登录、连接、消息收发、离线拉取等关键动作，存储至 MySQL。

三、关键交互流程（以发送单聊消息为例）
前端通过 WebSocket 发送 STOMP 帧到 /app/im。

WebSocket 拦截器校验令牌，提取用户 ID。

路由至单聊服务。

校验好友关系与发送权限。

调用消息 Mapper 持久化消息内容，更新会话摘要及接收方未读数（事务）。

查询 Redis 获取接收方在线状态。

若在线，通过接收方专属队列 /user/{receiverId}/queue/private 推送消息；若离线，则存入 Redis 离线队列。

返回“发送成功”回执给发送方。

安全日志记录本次消息动作。

即时聊天系统 — 前端架构设计（frontend.md）
一、整体分层
前端采用三层架构，通过事件驱动解耦：

层级	关键模块	职责
UI 组件层	components/、views/	可复用的 Vue3 组件，负责界面渲染与用户交互，触发业务事件
应用状态层	stores/	Pinia 状态管理，统一维护用户、会话、消息三大核心状态
接口适配层	services/	封装 Axios（REST）和 STOMP（WebSocket）客户端，处理通信与鉴权
二、核心模块说明

1. UI 组件层
   基础组件：登录/注册、会话列表、消息窗口、文件上传/下载（分片断点续传）。

单聊专属：好友搜索/添加、在线状态展示、单聊会话窗口。

群聊专属：群成员管理、群公告、群聊会话窗口。

组件通过自定义事件与上层通信，适配可视化编排（vibe coding）。

2. 应用状态层（Pinia stores）
   用户状态模块：当前登录用户信息、好友/群组列表、WebSocket 连接状态、OAuth2 令牌（含刷新逻辑）。

会话状态模块：会话列表、每个会话的最新消息预览、未读数量、最后更新时间。

消息状态模块：当前会话的消息列表、加载状态、发送状态、已读状态、文件传输进度。
所有状态更新均暴露为标准动作（如 updateReadCount、appendMessage），便于在可视化编排中调用。

3. 接口适配层（services/）
   REST API 客户端（Axios）：

统一请求/响应拦截，自动注入 Authorization 头。

令牌过期时自动使用 refresh_token 刷新。

网络异常重试与日志打印。

WebSocket 客户端（STOMP + SockJS）：

连接地址：/ws/chat?access_token=xxx。

支持心跳保活（PING/PONG）和断线重连（指数退避）。

内置发送等待队列和订阅维护，订阅用户专属通道。

降级支持：不兼容原生 WebSocket 时自动切换至 HTTP 轮询（SockJS）。

三、交互流程示例
发送消息流程
用户在消息输入框输入内容，点击发送。

UI 组件进行前端校验（非空、长度、非法字符）。

触发 sendMessage 事件，传递消息数据给 WebSocket 客户端。

WebSocket 客户端发送 STOMP 帧，并将该消息标记为 发送中，更新 Pinia 消息状态。

后端返回发送成功回执后，更新状态为 发送成功。

消息追加至当前会话列表，同时更新会话摘要（最新消息、时间）。

会话列表自动排序，未读角标更新。

接收消息流程
WebSocket 客户端接收到新消息 STOMP 帧。

解析后触发 newMessage 事件，交由消息状态模块处理。

新消息追加至对应会话，未读数 +1，会话列表置顶。

若当前窗口为该会话，自动渲染新消息并发送已读回执；否则展示桌面通知。

四、技术要点
状态持久化：用户令牌和部分设置使用 localStorage 持久化，刷新页面保持登录。

文件上传优化：采用分片（5MB）并行上传，支持断点续传，实时显示进度。

多端模拟：开发环境下通过修改 Vite devServer 端口（--port）启动多个前端实例，每个实例独立登录，模拟多用户。

跨域代理：Vite 配置 proxy 将 /api 和 /ws 代理到后端服务（如 http://localhost:8080）。