【C++ 在线五子棋对战】 - 项目介绍与环境搭建

大家好，我是Halcyon.平安

欢迎文末添加好友交流，共同进步！

---

一、项目介绍

本项目是实现一个网页版的五子棋对战游戏 ，玩家通过浏览器即可进行实时对弈。项目采用 C++ 后端 + HTML / JS 前端 的架构，后端使用 WebSocket 协议实现双向实时通信。

接下来让我们一起开始学习此项目！！！

核心功能

• 用户管理：用户注册、用户登录、获取用户信息、天梯分数记录、比赛场次记录
• 匹配对战：两个玩家根据天梯分数匹配对手，进行五子棋游戏对战
• 聊天功能：两个玩家在下棋的同时可以进行实时聊天

---

二、项目演示

2.1 用户界面（前端）

玩家通过浏览器进行注册登录、匹配对手、五子棋对战、实时聊天。

注册失败，登录失败，游戏完毕都会返回响应的注册页面，登录页面以及环境大厅页面。

---

2.2 后端界面（服务器）

服务器运行在 Linux 上，处理 WebSocket 连接、匹配、对局逻辑。

1. 服务端收到用户的注册请求后，对请求信息进行校验，校验通过后将用户的账号、密码等信息存储到用户数据库中进行统一管理，注册成功后数据库才会留存该用户的有效信息。
2. 服务端收到用户的登录请求后，在用户数据库中验证用户账号是否存在、密码是否正确；验证通过则登录成功，为该用户创建专属会话管理 ，会话管理作为用户的在线身份凭证与游戏通信桥梁，用于后续全流程的身份校验与连接绑定，登录成功后才会为用户分配客户端会话。
3. 用户进入游戏大厅页面后，向服务端发起WebSocket长连接请求 ；服务端收到请求后，通过会话管理对当前用户的登录状态进行校验，验证通过后完成长连接建立，将用户加入游戏大厅的在线用户列表中，在线用户管理维护所有长连接用户，包含用户与socket连接的对应关系。
4. 服务端维护在线用户管理模块，该模块分为两个核心部分：一是游戏大厅 ，用于承载所有登录成功、处于等待状态的在线用户；二是游戏房间，用于为匹配成功的两名对战用户创建专属的独立对战空间。
5. 用户在游戏大厅中发起游戏对战匹配请求，服务端收到请求后先进行会话验证，验证通过后根据用户的分数将其分配到对应等级的匹配队列中 ；当某一匹配队列内的用户数量≥2时，匹配成功，从队列中取出队首两名用户，为其创建专属对战房间，并将两名用户加入该房间。
6. 对战匹配成功后，用户跳转至游戏房间页面，向服务端发起房间内的WebSocket长连接请求 ；服务端收到请求后，先进行会话验证，再验证用户是否已有对应游戏房间，两项验证均通过 后，两名用户即可在房间内开始五子棋对战与实时聊天；对局结束或所有用户退出房间后，房间被销毁，用户断开连接并返回游戏大厅。
7. 后续所有用户通信均由服务端中转：服务端通过用户ID获取其所在房间ID，将请求广播给房间内的所有用户（同时完成棋局信息的逻辑处理），客户端仅在收到服务端推送的请求后，才会渲染对应落子或聊天信息。

---

三、项目架构总览

3.1 项目整体模块：

┌─────────────────────────────────────────────┐
│              gobang.cpp（主入口）            │
├─────────────────────────────────────────────┤
│             server.hpp（服务器主模块）        │
│     HTTP路由分发 + WebSocket连接管理          │
├────────┬────────┬────────┬──────────────────┤
│session │ online │ matcher│    room（房间）   │
│（会话） │（在线） │（匹配） │ 棋盘+胜负判定      │
├────────┴────────┴────────┼──────────────────┤
│         db.hpp（数据库）   │  util.hpp（工具） │
├──────────────────────────┼──────────────────┤
│       logger.hpp（日志）  │                  │
└──────────────────────────┴──────────────────┘
         后端 C++                    前端 HTML/JS

3.2 模块依赖关系

logger.hpp          ← 日志模块（最底层，无依赖）
  ↓
util.hpp            ← 工具类（MySQL/JSON/字符串/文件操作）
  ↓
db.hpp              ← 数据库用户表管理
session.hpp         ← 会话管理（Cookie/登录状态）
online.hpp          ← 在线用户管理（大厅/房间）
  ↓
room.hpp            ← 游戏房间（棋盘+胜负判定+房间管理）
  ↓
matcher.hpp         ← 匹配系统（三段位匹配队列）
  ↓
server.hpp          ← 服务器主模块（HTTP路由+WebSocket处理）
  ↓
gobang.cpp          ← 主入口

3.3 通信流程

客户端（浏览器）                    服务端（C++）
     │                                │
     │── HTTP POST /reg ───────────→  │  注册
     │←── JSON响应 ──────────────────  │
     │                                │
     │── HTTP POST /login ─────────→  │  登录（返回Cookie: SSID=xxx）
     │←── Set-Cookie: SSID=xxx ────── │
     │                                │
     │── WS连接 ws://host/hall ────→   │  进入游戏大厅（长连接）
     │←── hall_ready ──────────────── │
     │                                │
     │── WS消息: match_start ──────→   │  开始匹配
     │←── match_success ────────────  │  匹配成功
     │                                │
     │── WS连接 ws://host/room ────→   │  进入游戏房间
     │←── room_ready ──────────────── │
     │                                │
     │── WS消息: put_chess ────────→   │  下棋
     │←── 广播给双方 ────────────────   │

---

四、开发环境

工具	说明
操作系统	Linux（ Ubuntu-22.04）
编辑器	VSCode
编译器	g++（需支持 C++11）
调试器	gdb
构建工具	Makefile

---

五、核心技术

技术	用途
HTTP/WebSocket	HTTP 处理登录注册，WebSocket 处理实时游戏通信
WebSocket++	C++ 的 WebSocket 服务器库
JsonCpp	JSON 序列化/反序列化
MySQL	用户数据持久化存储
C++11	智能指针、线程、lambda、auto 等
BlockQueue	阻塞队列实现匹配系统
HTML/CSS/JS/AJAX	前端页面与交互

---

六、环境搭建

以下给出 Ubuntu 22.04 系统的环境搭建步骤。

6.1 更新软件源

sudo apt update

---

6.2 安装编译工具链（gcc/g++/gdb/make）

Ubuntu 22.04 自带的 gcc 已支持 C++11，直接通过 build-essential 一次性安装：

sudo apt install -y build-essential gdb cmake git

# 验证
g++ --version
gdb --version
git --version
cmake --version

---

6.3 安装 boost 库

WebSocket++ 依赖 boost 的 asio 组件：

sudo apt install -y libboost-all-dev

#验证
dpkg -l | grep libboost-all-dev

---

6.4 安装 JsonCpp 库

用于 JSON 数据的序列化与反序列化：

sudo apt install -y libjsoncpp-dev

# 验证头文件是否存在
ls /usr/include/jsoncpp/json/
# 应看到: assertions.h  json.h  reader.h  value.h  writer.h ...

---

6.5 安装 MySQL 数据库服务及开发包

6.5.1 安装 MySQL 服务端、客户端及开发包

sudo apt install -y mysql-server mysql-client libmysqlclient-dev

6.5.2 启动 MySQL 服务

sudo systemctl start mysql
sudo systemctl status mysql

6.5.3 设置 MySQL 密码

Ubuntu 22.04 的 MySQL 默认使用 auth_socket 认证，需要切换为密码认证：

sudo mysql

# 在 MySQL 命令行中执行（将 '你的密码' 替换为实际密码）
mysql> ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '你的密码';
mysql> FLUSH PRIVILEGES;
mysql> quit

6.5.4 验证登录及字符集

mysql -uroot -p
# 输入刚才设置的密码

mysql> show variables like '%chara%';
# 确认相关项为 utf8mb4（Ubuntu 22.04 MySQL 8.0 默认字符集）

6.6 安装 WebSocket++ 库

WebSocket++ 需要从源码编译安装：

# 克隆源码
git clone https://github.com/zaphoyd/websocketpp.git

# 编译安装
cd websocketpp
mkdir build && cd build
cmake -DCMAKE_INSTALL_PREFIX=/usr ..
sudo make install

验证安装是否成功：

cd ../examples/echo_server
g++ -std=c++11 echo_server.cpp -o echo_server -lpthread -lboost_system
# 编译成功即表示安装成功

6.7 依赖的第三方库总结

库	安装方式	用途
boost	apt 包管理器	asio 异步 IO（WebSocket++ 依赖）
JsonCpp	apt 包管理器	JSON 序列化与反序列化
MySQL	apt 包管理器	用户数据存储
WebSocket++	源码编译安装	搭建 HTTP + WebSocket 服务器

---