轻棋局（一）：项目总览与架构设计

一句话定位

轻棋局（XiangqiArena） 是一个基于 Java 的在线棋类对弈平台，支持中国象棋、五子棋和围棋三种棋类，提供在线双人对战、人机对弈、残局练习与复盘分析功能。

线上地址：https://www.xiangqiarena.com/

技术选型：为什么是这些？

后端：Undertow（而非 Spring Boot）

Spring Boot 是 Java Web 开发的事实标准，但这个项目选择 Undertow 2.3.18，原因是：

对比项	Spring Boot	Undertow
启动速度	2-5 秒	< 1 秒
内存占用	200MB+	50MB 左右
JAR 体积	30-50MB	~4MB
依赖数量	20+	3（core + jackson + H2）
学习曲线	高（注解、IoC、自动配置）	低（直接写 Handler）

对于一个棋类游戏服务器，不需要 Spring 的 IoC 容器、自动配置、AOP 等重型特性。Undertow 的 RoutingHandler 足够处理所有路由，BlockingHandler 处理数据库操作，WebSocket 处理实时对战。

前端：原生 JavaScript（而非 React/Vue）

没有用任何前端框架，整个 SPA 由三个文件组成：

app.js --- 主逻辑（状态管理、路由、渲染）
board.js --- 棋盘绘制（Canvas API）
app.css --- 样式

选择原因：

零构建步骤 --- 不需要 npm、webpack、vite，保存即生效
部署简单 --- 后端直接作为静态文件 serve，不需要 CDN 或构建产物
棋盘游戏 UI 复杂度有限 --- 不需要复杂的表单、列表、状态管理库
加载速度快 --- 总 JS 代码量远小于任何一个 React 项目的 node_modules

数据库：H2（本地） + PostgreSQL（生产）

本地开发用 H2 嵌入式数据库 ，零配置启动。生产环境通过 XQ_DATABASE_URL 环境变量切换到 PostgreSQL ，由 HikariCP 连接池管理。

Schema 用纯 SQL DDL 定义，支持自动初始化，不依赖 ORM。

没有用 JWT 或 OAuth，而是经典的 BCrypt 密码哈希 + Cookie 会话 方案。对于一个棋类游戏平台，用户系统只需要注册、登录、保持会话，不需要 SSO 或第三方登录。

整体架构

复制代码

┌─────────────────────────────────────────────────────┐
│                    用户浏览器                         │
│              (Vanilla JS SPA)                       │
│         app.js + board.js + app.css                 │
└──────────────────────┬──────────────────────────────┘
                       │ HTTP / WebSocket
                       ▼
┌─────────────────────────────────────────────────────┐
│              Cloudflare Worker (前门)                │
│          DDoS 防护 + SSL 终止 + CDN 缓存            │
└──────────────────────┬──────────────────────────────┘
                       │ Proxy
                       ▼
┌─────────────────────────────────────────────────────┐
│           Java Origin Server (Undertow)             │
│                                                     │
│  ┌─────────────┐ ┌──────────────┐ ┌──────────────┐ │
│  │ OnlineSite  │ │ RoomService  │ │ PracticeGame │ │
│  │ Server      │ │              │ │ Hub          │ │
│  │ (HTTP API)  │ │ (房间管理)    │ │ (人机练习)    │ │
│  └──────┬──────┘ └──────┬───────┘ └──────┬───────┘ │
│         │               │                │         │
│  ┌──────┴───────────────┴────────────────┴───────┐ │
│  │              OnlineStore (数据层)              │ │
│  │    H2(本地) / PostgreSQL(生产) + HikariCP     │ │
│  └───────────────────────────────────────────────┘ │
│                                                     │
│  ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│  │ Xiangqi AI   │ │ Gomoku AI    │ │ Go Engine    │ │
│  │ (内置Minimax) │ │ (内置AlphaBeta)│ │ (外部进程)   │ │
│  └──────────────┘ └──────────────┘ └──────────────┘ │
│                                                     │
│  ┌──────────────┐ ┌──────────────┐                  │
│  │ AuthService  │ │ WsHub        │                  │
│  │ (BCrypt+Cookie)│ │ (WebSocket) │                  │
│  └──────────────┘ └──────────────┘                  │
└─────────────────────────────────────────────────────┘

核心数据流

用户请求 → Cloudflare Worker → Java Origin
API 调用 → OnlineSiteServer 路由 → 对应 Handler → Service/Store
实时对战 → WebSocket 连接 → WsHub 广播 → 双方浏览器更新
AI 计算 → PracticeGameHub → 对应引擎 → 返回最佳着法
数据库 → OnlineStore → H2/PostgreSQL（HikariCP 连接池）

项目目录结构

复制代码

Chinese-chess/
├── src/
│   ├── main/
│   │   ├── java/com/xiangqi/
│   │   │   ├── model/              # 棋盘模型层
│   │   │   │   ├── Board.java          # 象棋棋盘（10×9）
│   │   │   │   ├── Piece.java          # 棋子
│   │   │   │   ├── Move.java           # 着法
│   │   │   │   ├── PieceColor.java     # 红/黑
│   │   │   │   ├── PieceType.java      # 车马炮等
│   │   │   │   ├── Zobrist.java        # Zobrist 哈希
│   │   │   │   ├── TacticDetector.java # 战术检测
│   │   │   │   ├── gomoku/             # 五子棋模型
│   │   │   │   │   ├── GomokuBoard.java
│   │   │   │   │   ├── GomokuAI.java
│   │   │   │   │   └── GomokuEngine.java
│   │   │   │   └── go/                 # 围棋模型
│   │   │   │       ├── GoBoard.java
│   │   │   │       ├── GoEngine.java
│   │   │   │       └── GoScenario.java
│   │   │   ├── ai/                 # AI 引擎层
│   │   │   │   ├── MinimaxAI.java          # 核心搜索算法
│   │   │   │   ├── BuiltinXiangqiEngine.java  # 内置引擎
│   │   │   │   ├── ConfigurableXiangqiEngine.java  # 可配置引擎
│   │   │   │   ├── PikafishUciEngine.java   # Pikafish UCI 适配
│   │   │   │   ├── OpeningBook.java         # 开局库
│   │   │   │   ├── FenCodec.java            # FEN 编解码
│   │   │   │   ├── XiangqiEngine.java       # 引擎接口
│   │   │   │   ├── EndgameStudySet.java     # 残局学习集
│   │   │   │   └── EventLearnedSet.java     # 事件学习集
│   │   │   ├── online/             # 在线对战层
│   │   │   │   ├── server/             # 服务器
│   │   │   │   │   ├── OnlineSiteServer.java  # 主 HTTP 服务器
│   │   │   │   │   ├── OnlineStore.java       # 数据存储
│   │   │   │   │   ├── OnlineRoomHub.java     # 房间管理
│   │   │   │   │   └── RateLimiter.java       # 限流器
│   │   │   │   ├── game/               # 对局管理
│   │   │   │   │   ├── XiangqiMatch.java     # 象棋对局
│   │   │   │   │   ├── GomokuMatch.java      # 五子棋对局
│   │   │   │   │   ├── MatchPlayer.java      # 玩家状态
│   │   │   │   │   ├── GameClock.java        # 计时器
│   │   │   │   │   └── OnlineMatchEngine.java # 在线引擎
│   │   │   │   ├── auth/               # 认证
│   │   │   │   │   ├── AuthService.java
│   │   │   │   │   ├── PasswordHasher.java   # BCrypt
│   │   │   │   │   └── UserRepository.java
│   │   │   │   ├── room/               # 房间
│   │   │   │   │   ├── RoomService.java
│   │   │   │   │   └── RoomRepository.java
│   │   │   │   ├── practice/           # 人机练习
│   │   │   │   │   └── PracticeGameHub.java
│   │   │   │   └── learn/              # 学习系统
│   │   │   │       └── EndgameCatalog.java
│   │   │   └── web/                # Web 入口
│   │   │       ├── PublicWebMain.java   # 生产入口
│   │   │       ├── PublicSiteServer.java # 站点服务器
│   │   │       └── BrowserModeMain.java  # 本地调试入口
│   │   └── resources/
│   │       └── online/             # 前端静态文件
│   │           ├── index.html
│   │           ├── app.js            # SPA 主逻辑
│   │           ├── board.js          # 棋盘渲染
│   │           ├── app.css           # 样式
│   │           ├── schema.sql        # 数据库 DDL
│   │           └── endgames.json     # 残局数据
│   └── test/                     # 测试（34 个测试用例）
├── deploy/
│   └── cloudflare-java-proxy/    # Cloudflare Worker 部署
├── docs/                         # 文档
│   ├── deployment/               # 部署指南
│   └── superpowers/              # 设计文档
├── pom.xml                       # Maven 配置
├── run_web.bat                   # 本地启动脚本
└── README.md                     # 项目说明

核心 API 路由（30+ 个）

OnlineSiteServer 注册的路由一览：

方法	路径	功能
GET	`/api/site/bootstrap`	初始化数据（棋种、版本）
GET	`/api/auth/me`	当前用户信息
POST	`/api/auth/register`	注册
POST	`/api/auth/login`	登录
GET	`/api/lobby/overview`	大厅概览
GET	`/api/rooms/{roomId}`	房间详情
POST	`/api/rooms`	创建房间
POST	`/api/rooms/join-by-code`	通过邀请码加入
POST	`/api/rooms/{roomId}/join`	加入房间
POST	`/api/rooms/{roomId}/ready`	准备
GET	`/api/games/{gameId}`	对局详情
POST	`/api/games/{gameId}/move`	走棋
POST	`/api/games/{gameId}/resign`	认输
GET	`/api/games/{gameId}/analysis`	复盘分析
POST	`/api/learn/practice-games`	创建人机练习
POST	`/api/learn/practice-games/{gameId}/move`	人机走棋
GET	`/api/learn/content`	学习内容
GET	`/api/learn/progress`	学习进度
GET	`/api/watch/overview`	观战概览
GET	`/api/community/leaderboard`	排行榜
WS	`/ws`	WebSocket 实时通信

复刻这个项目，你需要什么？

前置知识

领域	需要掌握	深度
Java	集合框架、IO、并发基础	中等
Web 开发	HTTP 协议、REST API、Cookie/Session	中等
数据库	SQL 基础、DDL、连接池概念	入门
前端	HTML/CSS/JavaScript 基础	中等
AI 算法	搜索算法基础（可选，AI 可以后加）	入门

开发环境

bash 复制代码

# 1. 安装 Java 11+
java -version

# 2. 安装 Maven 3.9+
mvn -version

# 3. 克隆项目
git clone <repo-url>
cd Chinese-chess

# 4. 构建
mvn -q -DskipTests package

# 5. 启动
run_web.bat
# 或手动：
java -cp "target/classes;target/dependency/*" com.xiangqi.web.PublicWebMain

最小可行复刻路径

第一天：跑通 Board.java + 基本走棋规则
第二天：加上 Web UI（可以先只做象棋）
第三天：实现简单 AI（Alpha-Beta 剪枝）
第四天：加上用户系统和房间功能
第五天：部署上线

系列文章导航

（一）项目总览与架构设计 ← 本文
（二）后端核心架构
（三）AI 引擎设计与实现
（四）前端 SPA 实战
（五）多棋种统一架构
（六）部署上线与运维

下一篇：（二）后端核心架构 --- 深入 Undertow 服务器、WebSocket 实时对战、认证系统、房间管理。