# Gomoku

**Repository Path**: zhang-zhang78/gomoku

## Basic Information

- **Project Name**: Gomoku
- **Description**: No description available
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-30
- **Last Updated**: 2025-10-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🎮 微信小程序五子棋实时对战游戏

[![Go Version](https://img.shields.io/badge/Go-1.21+-blue.svg)](https://golang.org)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## 📘 项目简介

本项目是一个基于 **微信小程序前端 + Go 后端 + WebSocket 实时通信** 的五子棋在线对战游戏。

**核心功能：**
- ✅ 实时匹配两名玩家
- ✅ 棋盘同步显示
- ✅ 五子连珠胜负判断
- ✅ 游戏记录存储
- ✅ 排行榜系统

**技术特色：**
- 🎨 小程序 Canvas 绘图
- 🔌 WebSocket 实时通信
- ⚡ Go 高性能并发处理
- 💾 Redis 实时状态缓存
- 🗄️ MySQL 数据持久化
- ⚙️ Viper 配置管理
- 📦 GORM 数据库 ORM

## 🚀 快速开始

### 环境要求

- Go 1.21+
- MySQL 5.7+
- Redis 5.0+
- 微信开发者工具

### 一键启动

```bash
# 1. 克隆项目
git clone https://github.com/yourusername/gomoku.git
cd gomoku

# 2. 配置数据库
# 编辑 config/config.yaml

# 3. 创建数据库
mysql -u root -p -e "CREATE DATABASE gomoku CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"

# 4. 启动后端
cd backend
go mod tidy
go run main.go

# 5. 打开微信开发者工具，导入 miniprogram 目录
```

详细启动说明请查看 [启动说明.md](启动说明.md)

---

## 🧩 系统架构

### 架构图

```
┌─────────────────┐
│  微信小程序前端   │
│   (Canvas UI)   │
└────────┬────────┘
         │ WebSocket
         │ (实时通信)
         ▼
┌─────────────────┐
│   Go 后端服务    │
│  Gin + WebSocket│
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌───────┐ ┌────────┐
│ Redis │ │ MySQL  │
│(缓存) │ │(持久化)│
└───────┘ └────────┘
```

### 技术栈

| 层级 | 技术 | 说明 |
|------|------|------|
| **前端** | 微信小程序 + Canvas | 棋盘渲染、用户交互 |
| **通信** | WebSocket | 实时双向通信 |
| **后端** | Go + Gin + Gorilla/WebSocket | HTTP API 和 WebSocket 服务 |
| **缓存** | Redis | 房间状态、匹配队列 |
| **数据库** | MySQL + GORM | 玩家数据、对局历史 |
| **配置** | Viper | YAML 配置管理 |

---

## 📁 项目结构

```
gomoku/
├── backend/                  # Go 后端服务
│   ├── main.go              # 主程序入口
│   ├── handler/             # 请求处理器
│   │   ├── websocket.go    # WebSocket 处理
│   │   └── api.go          # HTTP API
│   ├── logic/               # 业务逻辑
│   │   ├── game.go         # 游戏逻辑（胜负判断）
│   │   ├── match.go        # 匹配系统
│   │   └── room.go         # 房间管理
│   ├── model/               # 数据模型
│   │   ├── player.go       # 玩家模型
│   │   ├── game.go         # 对局模型
│   │   └── room.go         # 房间模型
│   ├── pkg/                 # 基础包
│   │   ├── config.go       # 配置管理
│   │   ├── mysql.go        # MySQL 连接
│   │   └── redis.go        # Redis 连接
│   ├── go.mod               # Go 依赖
│   └── README.md            # 后端文档
│
├── miniprogram/             # 微信小程序前端
│   ├── pages/               # 页面
│   │   ├── index/          # 首页（匹配）
│   │   ├── game/           # 游戏页
│   │   ├── rank/           # 排行榜
│   │   └── history/        # 历史记录
│   ├── utils/               # 工具类
│   │   ├── socket.js       # WebSocket 封装
│   │   └── api.js          # API 封装
│   ├── app.js               # 小程序入口
│   ├── app.json             # 小程序配置
│   └── README.md            # 前端文档
│
├── config/                  # 配置文件
│   └── config.yaml         # 数据库配置
│
├── README.md                # 项目总览（本文件）
├── 启动说明.md              # 快速启动指南
└── 部署文档.md              # 生产部署指南
```

---

## 🎯 核心功能

### 1. 匹配系统

- 玩家加入匹配队列
- 自动配对两名玩家
- 随机分配黑白方
- 创建游戏房间

### 2. 游戏逻辑

- 15×15 标准五子棋棋盘
- 黑方先手，轮流落子
- 四方向（横、竖、左斜、右斜）五子连珠判定
- 支持投降功能
- 平局判断

### 3. 实时通信

- WebSocket 双向通信
- 实时同步棋盘状态
- 断线重连机制
- 消息队列处理

### 4. 数据管理

**Redis 缓存：**
- 房间实时状态
- 匹配队列
- 玩家连接信息

**MySQL 持久化：**
- 玩家信息
- 对局历史
- 积分排行

### 5. 前端界面

- Canvas 绘制棋盘
- 精美的 UI 设计
- 流畅的交互体验
- 排行榜与历史记录

---

## 📡 API 接口

### HTTP API

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/health` | GET | 健康检查 |
| `/api/rank` | GET | 获取排行榜 |
| `/api/player?open_id=xxx` | GET | 获取玩家信息 |
| `/api/history?open_id=xxx` | GET | 获取对局历史 |

### WebSocket 消息

**客户端 → 服务器：**
- `match`: 匹配请求
- `move`: 落子
- `surrender`: 投降
- `cancel_match`: 取消匹配

**服务器 → 客户端：**
- `matching`: 匹配中
- `game_start`: 游戏开始
- `opponent_move`: 对方落子
- `game_over`: 游戏结束
- `error`: 错误消息

详细协议请查看 [backend/README.md](backend/README.md)

---

## 🎮 游戏流程

1. **玩家进入** → 点击「开始匹配」
2. **建立连接** → WebSocket 连接到服务器
3. **匹配对手** → 加入匹配队列，等待对手
4. **游戏开始** → 随机分配黑白方，黑方先手
5. **轮流落子** → 点击棋盘落子，实时同步
6. **胜负判断** → 五子连珠获胜
7. **结果保存** → 更新积分和胜率
8. **再来一局** → 返回大厅继续匹配

---

## 🛠️ 开发指南

### 后端开发

```bash
cd backend

# 安装依赖
go mod tidy

# 运行
go run main.go

# 热重载（需安装 air）
air
```

### 前端开发

1. 使用微信开发者工具打开 `miniprogram` 目录
2. 配置不校验合法域名（开发环境）
3. 点击编译运行

### 数据库设计

**players 表：**
- 玩家基本信息
- 战绩统计
- 积分排名

**games 表：**
- 对局记录
- 玩家信息
- 胜负结果

---

## 📚 文档索引

- 📖 [启动说明.md](启动说明.md) - 快速启动指南
- 🚀 [部署文档.md](部署文档.md) - 生产环境部署
- 🔧 [backend/README.md](backend/README.md) - 后端详细文档
- 📱 [miniprogram/README.md](miniprogram/README.md) - 前端详细文档

---

## 🎨 截图展示

（此处可添加游戏截图）

---

## 🔮 后续计划

- [ ] 观战模式
- [ ] 悔棋功能
- [ ] AI 对弈
- [ ] 好友系统
- [ ] 聊天功能
- [ ] 表情互动
- [ ] 房间密码
- [ ] 排位赛系统

---

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

---

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件

---

## 👨‍💻 作者

- 开发者：[Your Name]
- 邮箱：[your.email@example.com]
- GitHub：[@yourusername](https://github.com/yourusername)

---

## ⭐ Star History

如果这个项目对你有帮助，请给它一个 Star ⭐

---

**Happy Gaming! 🎉**