# springboot_chat_api

**Repository Path**: zhh7457/springboot_chat_api

## Basic Information

- **Project Name**: springboot_chat_api
- **Description**: springboot+websocket实现的后端服务api
- **Primary Language**: Java
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-30
- **Last Updated**: 2026-10-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Spring Boot Chat API

这是一个基于 Spring Boot 2.7.18 研发的即时通讯与小程序二楼聊天服务端项目（支持 Java 8 / 17 编译及运行）。

---

## 🌐 核心访问网址速查

* **🎨 小程序可视化管理后台**:  
  👉 **[http://localhost:8080/applet-admin.html](http://localhost:8080/applet-admin.html)** （支持创建、编辑、删除小程序，一键启停与首页推荐）
* **🚀 应用版本规划中心**:  
  👉 **[http://localhost:8080/version-admin.html](http://localhost:8080/version-admin.html)** （版本全生命周期规划 · APK/WGT整包与热更分发 · 强制更新控制与多端即时下发）
* **📑 Knife4j 交互式接口文档**:  
  👉 **[http://localhost:8080/doc.html](http://localhost:8080/doc.html)** （全量 API 调试、参数模型与在线接口测试）
* **⚡ WebSocket 实时通信地址**:  
  👉 `ws://localhost:8080/ws/chat`

> [!TIP]
> **关于登录与接口调试**：
> 1. 打开 Knife4j 页面（`http://localhost:8080/doc.html`）后，先在左侧“认证模块”中调用 `/api/chat/login` 接口进行登录，复制返回的 `access_token`。
> 2. 点击 Knife4j 顶部的 **“Authorize”** 或 **“个性化设置 - 离线缓存”**，或者直接在文档主页上方输入框配置 `Authorization` 的请求头密钥。
> 3. 设置后调用受保护的业务接口时，都会自动在 Header 中发送 `Authorization: Bearer <your_token>`，方便可视化调试。
> 4. 小程序管理后台及接口（`/api/chat/applet/manage/**`）、版本管理中心及接口（`/api/chat/version/**`）已默认配置免 Token 拦截放行，可在后台随时直接调用。

---

## 项目架构与特点

1. **框架版本**：Java 8 / Java 17 兼容，Spring Boot 2.7.18, Spring Data JPA, Web, WebSocket, Knife4j Swagger 2.
2. **性能优化 (解决 N+1 问题)**：重构了好友列表、分组、申请列表及历史消息查询，全量使用 `findAllById` 进行**批量查询 + 内存 HashMap 映射**，消除循环查库瓶颈，提升数十倍并发加载性能。
3. **认证机制 (Token)**：使用 JWT (`jjwt` 0.12.5) 来进行身份认证。支持从 `Authorization` 请求头 (`Bearer <token>`)、Cookie `token` 或 URL 参数 `token` 中提取和校验 Token。
4. **异常集中管控**：引入 `@RestControllerAdvice` 实现 `GlobalExceptionHandler` 全局异常统一捕获，规范返回结构。
5. **密码哈希**：支持 MD5 哈希校验，与原有密码加密方式兼容。
6. **拼音首字母检索**：实现了基于 **GBK 汉字编码边界判定算法** 的拼音首字母提取（位于 `ChatUtil.java`），在修改昵称或设置好友备注时自动提取首字母支持客户端拼音排序，无需额外依赖。
7. **WebSocket 核心模块**：
   - 映射在 `/ws/chat` 地址上。
   - 建立连接时会自动向客户端发送专属 `client_id` 并支持绑定房间在线状态。
   - 发送消息时直接调 HTTP API 存库并通过 WebSocket 毫秒级广播给房间成员。
8. **文件服务**：
   - 上传文件自动保存在本地配置的 `./uploads` 目录。
   - 上传图片会自动采用 AWT 动态缩放生成 `100x100` 的缩略图。
   - 可通过映射路径 `http://localhost:8080/uploads/...` 直接访问静态资源。

---

## 目录结构

```
springboot_chat_api/
├── pom.xml
└── src/
    └── main/
        ├── java/com/chat/api/
        │   ├── SpringbootChatApiApplication.java (启动类)
        │   ├── common/       (包含结果包装、JWT工具、拼音工具、上下文ThreadLocal)
        │   ├── config/       (MVC配置、异常处理器、Knife4j配置、拦截器、CORS、WebSocket配置)
        │   ├── controller/   (登录注册控制器、聊天业务控制器、通用上传、小程序控制器)
        │   ├── dto/          (前端请求传输对象)
        │   ├── entity/       (JPA 实体，映射数据库表)
        │   ├── enums/        (好友申请、好友关系、消息状态等枚举)
        │   ├── repository/   (JPA 数据仓库，包含自定义查询语句)
        │   ├── service/      (核心业务逻辑，已实现批量查询优化)
        │   └── websocket/    (WebSocket 核心处理器)
        └── resources/
            ├── static/         (包含 applet-admin.html 与 version-admin.html 管理控制台单页)
            ├── schema.sql      (包含本地数据库一键导入的建表 DDL)
            └── application.yml (数据库连接、端口、文件上传大小与JWT Key等配置)
```

---

## 构建与运行

### 1. 环境依赖
* **JDK 8** 或 **JDK 17+**
* **Maven 3.x**
* **MySQL 5.7+**

### 2. 数据库与表初始化
1. 在本地 MySQL 创建名为 `springboot_chat` 的数据库：
   ```sql
   CREATE DATABASE springboot_chat CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
   ```
2. 导入 `src/main/resources/init.sql` 脚本初始化所有的关联表结构。

### 3. 配置文件修改
编辑 `src/main/resources/application.yml`：
* 更改 `spring.datasource.url`、`username`、`password` 为您本地的 MySQL 连接配置。
* 修改 `app.upload.path` 为存放上传图片/文件的本地物理目录路径。

### 4. 构建并运行项目
在项目根目录下执行：
```bash
# 编译并打包
mvn clean package -Dmaven.test.skip=true

# 运行 jar 包
java -jar target/springboot_chat_api-0.0.1-SNAPSHOT.jar
```