12 KiB
12 KiB
Server-v3 开发规划(决策与建议)
目标:以 FunGame.Core v3(master)为基础,在
C:\milimoe\FunGame.Server-v3重新构建服务器。 本文基于01-v2-功能总结.md与02-v3-Core-变更分析.md,列出必须做的决策、建议架构与开发路线,供确定 v3 开发内容。
1. 先决决策(需要你拍板的 5 个问题)
决策 A:服务器形态
| 选项 | 说明 | 建议 |
|---|---|---|
| A1. 单一 WebAPI 程序(推荐) | 一个 ASP.NET Core 进程同时提供:WebSocket 游戏协议 + RESTful API + 回合记录回放端点。与 v3 的 DefaultRoundRecordSink(POST) 设计意图吻合,与 Testing-v3 一脉相承 |
✅ 推荐:维护面小、天然支持记录外发与回放、Linux 部署友好 |
| A2. 控制台 + WebAPI 双程序 | 沿用 v2:FunGameServer(控制台) + FunGameWebAPI 双进程 | 保留 v2 习惯,但两套入口重复维护 |
| A3. 控制台单程序 | 只有 Socket/WS 游戏服务 | 无法直接对接 v3 的 POST 外发/回放生态 |
决策 B:客户端传输协议
| 选项 | 说明 |
|---|---|
| B1. WebSocket + JSON(推荐) | 与 v3 回放/记录 JSON 体系一致;浏览器/Web/桌面端都能连;/ws 单端点 |
| B2. WebSocket + 二进制协议 | 性能更高,但需要重新设计序列化(v3 已无 SocketObject) |
| B3. TCP Socket 二进制 | v2 传统;客户端(FunGame.Desktop 等)需同步改造 |
| B4. 纯 REST + 轮询/SSE | 放弃实时长连接,最简但体验差 |
注意:v3 已无
SocketObject/SocketMessageType,协议要自己定。建议最小集: 连接握手(协议版本/模组清单/版本校验)→ 登录/注册 → 大厅/房间/匹配 → 局内指令(决策点/技能/移动)→ 心跳/断线重连。数据格式直接复用 v3 实体 JSON(JsonService 转换器已就绪)。
决策 C:数据层
| 选项 | 说明 |
|---|---|
| C1. EF Core + SQLite/MySQL(推荐) | 现代、迁移方便;v2 的 users/rooms/inventory 等表结构可迁移为 EF 模型 |
| C2. 保留 v2 的 SQLHelper 思路自研 | 可从 v2 Server 移植 MySQLHelper/SQLiteHelper + SQLQueryExtension(注意该包依赖 v2 Core 命名空间,需改) |
| C3. Dapper/ADO 手写 | 轻量但开发量大 |
v3 需要的持久化比 v2 简单:对局记录(RoundRecord)可以用 JSON 归档(Testing-v3 已有 rounds_archive.zip 模式),数据库只存账号/房间/经济等"服务器业务数据"。
决策 D:模组加载方式
| 选项 | 说明 |
|---|---|
| D1. 编译期进程内引用(推荐,跟随 v3 设计) | 模组 = 代码类 + EntityModuleConfig 配置;CharacterModule.Load() 后 Factory.GetGameModuleInstances<T> 实例化。参考 Testing-v3 的 OshimaGameModules |
| D2. DLL 插件加载器自研 | 保留 v2 的 plugins/modules 热插拔体验,但 Core v3 不再提供任何加载器,需要完整自研(隔离上下文、依赖解析、热卸载) |
| D3. 混合 | 核心模组编译期引用,扩展模组走 DLL |
决策 E:回合记录外发(v3 特色能力,强烈建议纳入)
| 选项 | 说明 |
|---|---|
| E1. 自收自发(推荐) | 服务器自身实现 IRoundRecordSink,把 RoundRecord 写入自己的存储(JSON 归档/数据库),并提供回放 REST 端点(参考 Testing-v3 的 ArchiveStore + /api/rounds 系列) |
E2. 使用 DefaultRoundRecordSink |
直接 POST 到外部数据服务(如独立的回放服务器),Server 只当生产者 |
| E3. 两者结合 | 本地归档 + 转发远端(最完整,实现也最简单:自定义 sink 内包一个 DefaultRoundRecordSink) |
2. 建议架构(以 A1 + B1 + C1 + D1 + E1 为例)
FunGame.Server-v3/ (解决方案:FunGame.Server-v3.slnx)
├── docs/ # 本文档目录
├── Server/ # ASP.NET Core Web API(宿主)
│ ├── Program.cs # 入口:模块加载 + 服务注册 + 管道
│ ├── Networking/ # 协议层(自研,替代 v2 的 Core 网络)
│ │ ├── WebSocketHandler.cs # /ws 长连接接入
│ │ ├── Protocol/ # 消息帧/信封、消息类型枚举(替代 SocketObject)
│ │ └── ClientSession.cs # 会话模型(替代 ServerModel<T>)
│ ├── Controllers/ # RESTful:账号/房间/商店/回放……
│ ├── Services/ # 业务层
│ │ ├── UserService.cs # 注册/登录/签到/找回密码(迁移 v2 逻辑)
│ │ ├── RoomService.cs # 房间/匹配/Elo(迁移 v2 逻辑)
│ │ ├── EconomyService.cs # 商店/市场/报价(迁移 v2 逻辑)
│ │ ├── GameHostService.cs # 对局宿主:GamingQueue 生命周期管理
│ │ └── MatchService.cs # 匹配队列
│ ├── Data/ # EF Core:DbContext + 迁移(users/rooms/inventory…)
│ ├── Records/ # 回合记录
│ │ ├── RoundRecordSink.cs # 实现 IRoundRecordSink → 归档 + 可选转发
│ │ ├── ArchiveStore.cs # 存档读写(参考 Testing-v3,可改数据库存储)
│ │ └── ReplayController.cs # /api/replay 系列回放端点
│ ├── Modules/ # 模组(编译期引用,如 OshimaGameModules)
│ │ ├── CharacterModule.cs / SkillModule.cs / ItemModule.cs
│ │ └── GameMapModule.cs # 地图(Framework.GameMap)
│ ├── Console/ # 管理控制台(ILogger + 指令解析,迁移 v2 ConsoleModel)
│ └── appsettings.json # JWT/CORS/数据库/SMTP/回放存储配置
├── FunGame.Core (项目引用) # C:\milimoe\FunGame.Core 或 NuGet
└── WebUI/ (可选) # 管理后台/回放台(React,参考 Testing-v3 webui)
核心运行时流程(一局对局)
玩家进房/匹配成功
→ GameHostService 创建 GamingQueue(角色列表, map)
→ queue.RoundRecordSink = RoundRecordSink(本服务实现)
→ 局内:玩家决策点指令 → queue.ProcessTurn / GamingMessageHandler 等价物
└── GamingQueue 内部自动:写 RoundRecord → 调 Sink(即时存档/转发)
→ 游戏结束 → 结算(RankingEntry/CharacterStatistics)→ 归档 → 通知客户端
→ 回放:ReplayController 读取归档;BattleStatePredictor 支撑"任意回合状态还原"
3. v3 Server 必须重建的基础设施(对照 v2 清单)
| # | 模块 | v2 位置 | v3 方案 |
|---|---|---|---|
| 1 | 网络监听与 WebSocket 会话 | Core 提供 | ASP.NET Core UseWebSockets + 自研会话模型 |
| 2 | 消息协议(信封/序列化) | SocketObject | 自研(推荐 JSON + 类型标记,复用 v3 JsonService) |
| 3 | 数据库访问 | SQLHelper + SQLQueryExtension | EF Core(或移植 v2 SQLHelper) |
| 4 | 配置系统 | INIHelper(Core) | Microsoft.Extensions.Configuration(JSON/appsettings) |
| 5 | 日志 | ServerHelper/TXTHelper(Server + Core) | ILogger + Serilog 等 |
| 6 | 邮件 | MailSender(Core) | 自研 SMTP 封装或 MailKit |
| 7 | 认证 | JWT + APIBearer(v2 WebAPI 已有) | 迁移 v2 WebAPI 认证架构 |
| 8 | 任务调度 | TaskScheduler(Core) | BackgroundService / System.Threading.Timer |
| 9 | 插件体系 | ServerPluginLoader/WebAPIPluginLoader(Core) | 按决策 D:模块化替代或自研加载器 |
| 10 | 控制台指令 | 迁移 v2 ConsoleModel | 指令字典 + ILogger(保留 ban/kick/logout/show/reload) |
4. 可从 v2 直接迁移的业务代码(高复用)
以下逻辑与 Core 运行时解耦程度高,迁移成本低(主要是改命名空间 + 换数据访问 + 换传输参数):
- ✅
ConnectController握手逻辑(人数/黑名单/参数校验)→ 适配新协议 - ✅
DataRequestController的业务方法:房间创建/进入/退出/房主移交/设置、准备、开始游戏流程、聊天 - ✅ 匹配算法
MatchingRoom(Elo 扩圈) - ✅
DataRequestService:注册流程、登录流程(含 autokey、check-login key 思路)、找回密码 - ✅ 每日签到、游戏时长统计、重复登录踢下线
- ✅ 商店/市场/报价/物品使用全套经济逻辑(事务化)
- ✅
ConsoleModel指令解析与常用指令 - ✅ WebAPI 的 JWT/CORS/认证处理器架构、
PayloadModel包装
需要重写/放弃的 v2 部分:
- 所有
Milimoe.FunGame.Core.*网络/传输引用(协议层) - SQLHelper 调用点(改为 EF/新数据层)
- 插件事件链(v3 无 ServerPlugin)——如果保留插件需求,事件点要么自建事件总线,要么砍掉
- GameModuleServer 机制(v3 无此基类)——对局宿主改为直接驱动 GamingQueue
5. 建议开发路线(里程碑)
M0:地基(0.5~1 周)
- Server-v3 解决方案骨架(slnx + WebAPI 项目 + 项目引用 v3 Core)
- appsettings 配置体系、ILogger、统一响应模型
PayloadModel(迁移) - 模块加载骨架:CharacterModule/SkillModule/ItemModule/地图模块 +
Factory.GetGameModuleInstances - 用 Testing-v3 的 OshimaGameModules(或精简示例模组)跑通:进程内 GamingQueue 一局模拟 → RoundRecord → 归档 → 回放端点(这是 v3 的核心价值验证)
M1:网络与账号(1~2 周)
- WebSocket
/ws会话层 + 自研消息协议(握手/心跳/分发) - EF Core + SQLite:users/profiles/rooms 迁移脚本
- 注册(邮箱验证码可选)、登录(密码加密 + 登录 key/autokey)、JWT
- 管理控制台指令框架(kick/logout/show/ban/reload)
M2:房间与匹配(1~2 周)
- 房间 CRUD/进入退出/房主移交/设置/准备/开始流程(迁移 v2)
- 匹配队列 + Elo 扩圈匹配(迁移)
- 对局启动:GameHostService 创建 GamingQueue、绑定 IRoundRecordSink、局内指令转发
M3:局内体验与回放(1~2 周)
- 局内指令协议:决策点(攻击/技能/物品/移动)、广播(Actions 实时推送,可基于 sink 事件)
- 断线重连(对局内重连,参考 v2 ReconnectToGame 思路)
- 回放台:
/api/replay/*+ 可选 React webui(可直接复用 Testing-v3 webui 改造)
M4:经济与扩展(1~2 周)
- 商店/市场/报价/签到迁移(EF 数据层)
- SMTP 找回密码、每日签到、游戏时长统计
- 排位统计(Rating 计算可参考 Testing-v3 的
CalculateRating)
M5:加固与发布(持续)
- 并发与事务正确性、压力测试
- Linux 自包含发布脚本(参考 Testing-v3 publish-linux.sh)
- 单元测试:迁移 Testing-v3 的 Tests(EffectAutoRecordTest / RoundRecordSinkTest)
6. 开放问题(建议尽早确认)
- 客户端是谁? FunGame.Desktop(v2 客户端)是否同步升级协议?若保留 v2 客户端,Server-v3 需要兼容 v2 的 SocketObject 协议——那网络层改动会大很多。
- 回放数据存哪? JSON 归档(简单、Testing-v3 模式)vs 数据库(可查询/统计)vs 远端 POST(DefaultRoundRecordSink)。
- 要不要账号系统? 如果 v3 服务器定位为"对战/回放服务",可以砍掉注册/邮箱,仅保留昵称 + JWT 匿名身份(大幅缩短开发)。
- 插件生态是否保留? 如果 Oshima 社区依赖 v2 的 ServerPlugin/WebAPIPlugin 插件,需要自研加载器;否则用"模块 + 服务内扩展点"替代。
- 核心业务与 Testing-v3 的关系:Testing-v3 的对战模拟/回放功能是直接并入 Server-v3(作为测试与演示能力),还是独立保留?
- Core v3 还在迭代(3.0.0-dev):建议以 ProjectReference 或本地 NuGet 引用 master,跟随提交更新,并关注 nuget 自动发布工作流(正式版发布后可切 NuGet)。
7. 一句话总结
v2 是"Core 给的服务器",v3 是"自己搭的服务器 + Core 给的战斗/回放引擎"。 Server-v3 的核心价值 = v3 战斗引擎(GamingQueue)+ 回合记录/即时外发(IRoundRecordSink)+ 回放(BattleStatePredictor/ArchiveStore),叠加自研的网络/账号/房间/经济层;v2 的成熟业务代码可迁移复用,但底层基础设施(网络、数据库、配置、日志)需要在新项目里重建。