重构Api接口到Msg

server/.github/instructions/development-tasks.md

@@ -80,6 +80,14 @@ Roguelike 游戏服务端开发任务追踪
   - [x] 移动API实现 (ApiMove.ts)
   - [x] 位置验证和边界检查
   - [x] 登录时广播玩家加入
+- [x] **架构重构：从HTTP API到WebSocket消息** (2025-12-18)
+  - [x] 删除旧的API实现 (src/api目录)
+  - [x] 删除旧的API协议 (PtlLogin.ts, PtlMove.ts, PtlSend.ts)
+  - [x] 创建消息协议文件 (MsgReq*/MsgRes*)
+  - [x] 创建消息处理器 (src/msg目录)
+  - [x] 更新服务器配置为消息监听模式
+  - [x] 重新生成serviceProto.ts文件
+  - [x] 修复所有消息名称映射问题
 
 ### 进行中
 - 等待下一阶段开发...
@@ -87,6 +95,27 @@ Roguelike 游戏服务端开发任务追踪
 ### 待办事项
 - 按照上述规划顺序实施开发
 
+## 重要架构说明
+
+### 🚨 消息协议设计规范 (2025-12-18更新)
+**本项目使用WebSocket服务器，后续所有接口设计必须使用消息（Message）方式，而非API方式！**
+
+#### 消息命名规范：
+- 请求消息：`MsgReq{功能名}.ts` (如：MsgReqLogin.ts)
+- 响应消息：`MsgRes{功能名}.ts` (如：MsgResLogin.ts)
+- 广播消息：`Msg{事件名}.ts` (如：MsgPlayerMove.ts)
+
+#### 消息处理器位置：
+- 文件位置：`src/msg/MsgReq{功能名}.ts`
+- 处理函数：使用 `MsgCall<MsgReq{功能名}>` 参数
+- 响应方式：`call.conn.sendMsg('Res{功能名}', response)`
+- 注册方式：`server.listenMsg('Req{功能名}', handler)`
+
+#### 协议文件生成：
+- 使用 `npm run proto` 自动生成 `serviceProto.ts`
+- 禁止直接修改 `serviceProto.ts` 文件
+- 协议文件会自动去掉 "Msg" 前缀进行注册
+
 ## 技术栈
 - TSRPC 框架
 - TypeScript
@@ -94,5 +123,6 @@ Roguelike 游戏服务端开发任务追踪
 
 ## 备注
 - 本文档由 AI 助手维护
-- 更新日期: 2025-12-14
+- 更新日期: 2025-12-18
 - 开发过程中会根据实际情况调整任务优先级和细节
+- **重要**：项目已从HTTP API架构迁移到WebSocket消息架构，请严格按照消息协议规范开发

server/src/api/ApiSend.ts

@@ -1,26 +0,0 @@
-import { ApiCall } from "tsrpc";
-import { server } from "..";
-import { ReqSend, ResSend } from "../shared/protocols/PtlSend";
-
-// This is a demo code file
-// Feel free to delete it
-
-export default async function (call: ApiCall<ReqSend, ResSend>) {
-    // Error
-    if (call.req.content.length === 0) {
-        call.error('Content is empty')
-        return;
-    }
-
-    // Success
-    let time = new Date();
-    call.succ({
-        time: time
-    });
-
-    // Broadcast
-    server.broadcastMsg('Chat', {
-        content: call.req.content,
-        time: time
-    })
-}

server/src/index.ts

@@ -1,7 +1,6 @@
-import * as path from "path";
 import { WsServer } from "tsrpc";
-import { serviceProto } from './shared/protocols/serviceProto';
 import { worldManager } from './managers/WorldManager';
+import { serviceProto } from './shared/protocols/serviceProto';
 
 // Create the Server
 export const server = new WsServer(serviceProto, {
@@ -12,7 +11,11 @@ export const server = new WsServer(serviceProto, {
 
 // Initialize before server start
 async function init() {
-    await server.autoImplementApi(path.resolve(__dirname, 'api'));
+    // 不再使用API，改为消息监听
+    // await server.autoImplementApi(path.resolve(__dirname, 'api'));
+
+    // 注册消息监听器
+    await registerMessageHandlers();
 
     // 初始化游戏世界
     console.log('正在初始化游戏世界...');
@@ -20,6 +23,23 @@ async function init() {
     console.log('游戏世界初始化完成');
 };
 
+// 注册消息处理器
+async function registerMessageHandlers() {
+    // 登录请求消息
+    const LoginHandler = await import('./msg/MsgReqLogin');
+    server.listenMsg('ReqLogin', LoginHandler.default);
+
+    // 移动请求消息
+    const MoveHandler = await import('./msg/MsgReqMove');
+    server.listenMsg('ReqMove', MoveHandler.default);
+
+    // 发送消息请求
+    const SendHandler = await import('./msg/MsgReqSend');
+    server.listenMsg('ReqSend', SendHandler.default);
+
+    console.log('消息处理器注册完成');
+}
+
 // Entry function
 async function main() {
     await init();

server/src/msg/MsgReqLogin.ts

@@ -1,21 +1,25 @@
-import { ApiCall } from "tsrpc";
+import { MsgCall } from "tsrpc";
-import { ReqLogin, ResLogin, PlayerInfo } from "../shared/protocols/PtlLogin";
 import { playerManager } from "../managers/PlayerManager";
+import { MsgReqLogin } from "../shared/protocols/MsgReqLogin";
+import { MsgResLogin, PlayerInfo } from "../shared/protocols/MsgResLogin";
 
 /**
- * 登录API
+ * 登录消息处理器
  * 处理玩家登录流程：
  * 1. 查找已有角色
  * 2. 若无角色，自动注册并创建角色
  * 3. 分配出生点
  * 4. 返回角色信息
  */
-export default async function (call: ApiCall<ReqLogin, ResLogin>) {
+export default async function (call: MsgCall<MsgReqLogin>) {
-    const { playerId, playerName } = call.req;
+    const { playerId, playerName } = call.msg;
 
     // 验证玩家ID
     if (!playerId || playerId.trim().length === 0) {
-        call.error('玩家ID不能为空');
+        call.conn.sendMsg('ResLogin', {
+            success: false,
+            message: '玩家ID不能为空'
+        });
         return;
     }
 
@@ -29,7 +33,7 @@ export default async function (call: ApiCall<ReqLogin, ResLogin>) {
         // 设置玩家在线状态
         playerManager.setPlayerOnline(playerId, call.conn.id);
 
-        // 保存玩家ID到连接对象，供其他API使用
+        // 保存玩家ID到连接对象，供其他消息处理器使用
         (call.conn as any).playerId = playerId;
 
         // 转换为协议格式
@@ -57,18 +61,23 @@ export default async function (call: ApiCall<ReqLogin, ResLogin>) {
         }, call.conn.id);
 
         // 返回成功结果
-        call.succ({
+        const response: MsgResLogin = {
             success: true,
             message: isNewPlayer ? '创建角色成功，欢迎来到游戏世界！' : '登录成功，欢迎回来！',
             player: playerInfo,
             isNewPlayer
-        });
+        };
+
+        call.conn.sendMsg('ResLogin', response);
 
         console.log(`玩家 ${player.name} (${playerId}) ${isNewPlayer ? '首次登录' : '登录成功'}`);
         console.log(`  在线玩家数: ${playerManager.getOnlinePlayerCount()}`);
 
     } catch (error) {
         console.error('登录失败:', error);
-        call.error(`登录失败: ${error instanceof Error ? error.message : '未知错误'}`);
+        call.conn.sendMsg('ResLogin', {
+            success: false,
+            message: `登录失败: ${error instanceof Error ? error.message : '未知错误'}`
+        });
     }
 }

server/src/msg/MsgReqMove.ts

@@ -1,21 +1,24 @@
-import { ApiCall } from "tsrpc";
+import { MsgCall } from "tsrpc";
-import { ReqMove, ResMove } from "../shared/protocols/PtlMove";
 import { playerManager } from "../managers/PlayerManager";
-import { broadcastToAll } from "../utils/broadcast";
 import { MsgPlayerMove } from "../shared/protocols/MsgPlayerMove";
+import { MsgReqMove } from "../shared/protocols/MsgReqMove";
+import { broadcastToAll } from "../utils/broadcast";
 
 /**
- * 移动API
+ * 移动消息处理器
  * 处理玩家移动请求，验证位置合法性，更新玩家位置并广播给其他玩家
  */
-export default async function (call: ApiCall<ReqMove, ResMove>) {
+export default async function (call: MsgCall<MsgReqMove>) {
-    const { x, y } = call.req;
+    const { x, y } = call.msg;
 
     // 从连接中获取玩家ID（需要在登录时保存）
     const playerId = (call.conn as any).playerId;
 
     if (!playerId) {
-        call.error('未登录，请先登录');
+        call.conn.sendMsg('ResMove', {
+            success: false,
+            message: '未登录，请先登录'
+        });
         return;
     }
 
@@ -23,25 +26,37 @@ export default async function (call: ApiCall<ReqMove, ResMove>) {
     const player = playerManager.getPlayer(playerId);
 
     if (!player) {
-        call.error('玩家不存在');
+        call.conn.sendMsg('ResMove', {
+            success: false,
+            message: '玩家不存在'
+        });
         return;
     }
 
     // 检查玩家是否存活
     if (!player.isAlive) {
-        call.error('玩家已死亡，无法移动');
+        call.conn.sendMsg('ResMove', {
+            success: false,
+            message: '玩家已死亡，无法移动'
+        });
         return;
     }
 
     // 验证坐标是否为数字
     if (typeof x !== 'number' || typeof y !== 'number') {
-        call.error('坐标格式错误');
+        call.conn.sendMsg('ResMove', {
+            success: false,
+            message: '坐标格式错误'
+        });
         return;
     }
 
     // 验证坐标是否为整数
     if (!Number.isInteger(x) || !Number.isInteger(y)) {
-        call.error('坐标必须为整数');
+        call.conn.sendMsg('ResMove', {
+            success: false,
+            message: '坐标必须为整数'
+        });
         return;
     }
 
@@ -50,7 +65,7 @@ export default async function (call: ApiCall<ReqMove, ResMove>) {
         const success = playerManager.updatePlayerPosition(playerId, x, y);
 
         if (!success) {
-            call.succ({
+            call.conn.sendMsg('ResMove', {
                 success: false,
                 message: '移动失败，位置无效或超出世界边界'
             });
@@ -71,7 +86,7 @@ export default async function (call: ApiCall<ReqMove, ResMove>) {
         broadcastToAll('MsgPlayerMove', moveMsg, call.conn.id);
 
         // 返回成功结果
-        call.succ({
+        call.conn.sendMsg('ResMove', {
             success: true,
             message: '移动成功',
             position: newPosition
@@ -81,6 +96,9 @@ export default async function (call: ApiCall<ReqMove, ResMove>) {
 
     } catch (error) {
         console.error('移动失败:', error);
-        call.error(`移动失败: ${error instanceof Error ? error.message : '未知错误'}`);
+        call.conn.sendMsg('ResMove', {
+            success: false,
+            message: `移动失败: ${error instanceof Error ? error.message : '未知错误'}`
+        });
     }
 }

server/src/msg/MsgReqSend.ts

@@ -0,0 +1,28 @@
+import { MsgCall } from "tsrpc";
+import { server } from "..";
+import { MsgReqSend } from "../shared/protocols/MsgReqSend";
+
+/**
+ * 发送消息处理器
+ */
+export default async function (call: MsgCall<MsgReqSend>) {
+    // 验证消息内容
+    if (call.msg.content.length === 0) {
+        call.conn.sendMsg('ResSend', {
+            time: new Date()
+        });
+        return;
+    }
+
+    // 返回成功响应
+    let time = new Date();
+    call.conn.sendMsg('ResSend', {
+        time: time
+    });
+
+    // 广播消息
+    server.broadcastMsg('Chat', {
+        content: call.msg.content,
+        time: time
+    });
+}

server/src/shared/protocols/MsgReqLogin.ts

@@ -0,0 +1,11 @@
+
+/**
+ * 登录请求消息
+ */
+export interface MsgReqLogin {
+    /** 玩家ID（用于识别玩家） */
+    playerId: string;
+
+    /** 玩家昵称（可选，新玩家时使用） */
+    playerName?: string;
+}

server/src/shared/protocols/MsgReqMove.ts

@@ -0,0 +1,10 @@
+/**
+ * 移动请求消息
+ */
+export interface MsgReqMove {
+    /** X坐标 */
+    x: number;
+
+    /** Y坐标 */
+    y: number;
+}

server/src/shared/protocols/MsgReqSend.ts

@@ -0,0 +1,7 @@
+/**
+ * 发送消息请求
+ */
+export interface MsgReqSend {
+    /** 消息内容 */
+    content: string;
+}

server/src/shared/protocols/MsgResLogin.ts

@@ -1,16 +1,5 @@
 import { Position } from './base';
 
-/**
- * 登录请求
- */
-export interface ReqLogin {
-    /** 玩家ID（用于识别玩家） */
-    playerId: string;
-    
-    /** 玩家昵称（可选，新玩家时使用） */
-    playerName?: string;
-}
-
 /**
  * 玩家角色信息
  */
@@ -44,9 +33,9 @@ export interface PlayerInfo {
 }
 
 /**
- * 登录响应
+ * 登录响应消息
  */
-export interface ResLogin {
+export interface MsgResLogin {
     /** 是否成功 */
     success: boolean;
 

server/src/shared/protocols/MsgResMove.ts

@@ -0,0 +1,15 @@
+import { Position } from './base';
+
+/**
+ * 移动响应消息
+ */
+export interface MsgResMove {
+    /** 是否成功 */
+    success: boolean;
+
+    /** 消息 */
+    message: string;
+
+    /** 新位置（成功时返回） */
+    position?: Position;
+}

server/src/shared/protocols/MsgResSend.ts

@@ -0,0 +1,7 @@
+/**
+ * 发送消息响应
+ */
+export interface MsgResSend {
+    /** 发送时间 */
+    time: Date;
+}

server/src/shared/protocols/PtlMove.ts

@@ -1,26 +0,0 @@
-import { Position } from './base';
-
-/**
- * 移动请求
- */
-export interface ReqMove {
-    /** 目标位置 X 坐标 */
-    x: number;
-    
-    /** 目标位置 Y 坐标 */
-    y: number;
-}
-
-/**
- * 移动响应
- */
-export interface ResMove {
-    /** 是否成功 */
-    success: boolean;
-    
-    /** 消息 */
-    message?: string;
-    
-    /** 实际移动后的位置 */
-    position?: Position;
-}

server/src/shared/protocols/PtlSend.ts

@@ -1,10 +0,0 @@
-// This is a demo code file
-// Feel free to delete it
-
-export interface ReqSend {
-    content: string
-}
-
-export interface ResSend {
-    time: Date
-}

server/src/shared/protocols/serviceProto.ts

@@ -2,34 +2,32 @@ import { ServiceProto } from 'tsrpc-proto';
 import { MsgChat } from './MsgChat';
 import { MsgPlayerJoin } from './MsgPlayerJoin';
 import { MsgPlayerMove } from './MsgPlayerMove';
-import { ReqLogin, ResLogin } from './PtlLogin';
+import { MsgReqLogin } from './MsgReqLogin';
-import { ReqMove, ResMove } from './PtlMove';
+import { MsgReqMove } from './MsgReqMove';
-import { ReqSend, ResSend } from './PtlSend';
+import { MsgReqSend } from './MsgReqSend';
+import { MsgResLogin } from './MsgResLogin';
+import { MsgResMove } from './MsgResMove';
+import { MsgResSend } from './MsgResSend';
 
 export interface ServiceType {
     api: {
-        "Login": {
+
-            req: ReqLogin,
-            res: ResLogin
-        },
-        "Move": {
-            req: ReqMove,
-            res: ResMove
-        },
-        "Send": {
-            req: ReqSend,
-            res: ResSend
-        }
     },
     msg: {
         "Chat": MsgChat,
         "PlayerJoin": MsgPlayerJoin,
-        "PlayerMove": MsgPlayerMove
+        "PlayerMove": MsgPlayerMove,
+        "ReqLogin": MsgReqLogin,
+        "ReqMove": MsgReqMove,
+        "ReqSend": MsgReqSend,
+        "ResLogin": MsgResLogin,
+        "ResMove": MsgResMove,
+        "ResSend": MsgResSend
     }
 }
 
 export const serviceProto: ServiceProto<ServiceType> = {
-    "version": 3,
+    "version": 5,
     "services": [
         {
             "id": 0,
@@ -47,19 +45,34 @@ export const serviceProto: ServiceProto<ServiceType> = {
             "type": "msg"
         },
         {
-            "id": 2,
+            "id": 6,
-            "name": "Login",
+            "name": "ReqLogin",
-            "type": "api"
+            "type": "msg"
         },
         {
-            "id": 5,
+            "id": 7,
-            "name": "Move",
+            "name": "ReqMove",
-            "type": "api"
+            "type": "msg"
         },
         {
-            "id": 1,
+            "id": 8,
-            "name": "Send",
+            "name": "ReqSend",
-            "type": "api"
+            "type": "msg"
+        },
+        {
+            "id": 9,
+            "name": "ResLogin",
+            "type": "msg"
+        },
+        {
+            "id": 10,
+            "name": "ResMove",
+            "type": "msg"
+        },
+        {
+            "id": 11,
+            "name": "ResSend",
+            "type": "msg"
         }
     ],
     "types": {
@@ -176,18 +189,18 @@ export const serviceProto: ServiceProto<ServiceType> = {
                 }
             ]
         },
-        "PtlLogin/ReqLogin": {
+        "MsgReqLogin/MsgReqLogin": {
             "type": "Interface",
             "properties": [
                 {
-                    "id": 1,
+                    "id": 0,
                     "name": "playerId",
                     "type": {
                         "type": "String"
                     }
                 },
                 {
-                    "id": 2,
+                    "id": 1,
                     "name": "playerName",
                     "type": {
                         "type": "String"
@@ -196,7 +209,38 @@ export const serviceProto: ServiceProto<ServiceType> = {
                 }
             ]
         },
-        "PtlLogin/ResLogin": {
+        "MsgReqMove/MsgReqMove": {
+            "type": "Interface",
+            "properties": [
+                {
+                    "id": 0,
+                    "name": "x",
+                    "type": {
+                        "type": "Number"
+                    }
+                },
+                {
+                    "id": 1,
+                    "name": "y",
+                    "type": {
+                        "type": "Number"
+                    }
+                }
+            ]
+        },
+        "MsgReqSend/MsgReqSend": {
+            "type": "Interface",
+            "properties": [
+                {
+                    "id": 0,
+                    "name": "content",
+                    "type": {
+                        "type": "String"
+                    }
+                }
+            ]
+        },
+        "MsgResLogin/MsgResLogin": {
             "type": "Interface",
             "properties": [
                 {
@@ -214,16 +258,16 @@ export const serviceProto: ServiceProto<ServiceType> = {
                     }
                 },
                 {
-                    "id": 4,
+                    "id": 2,
                     "name": "player",
                     "type": {
                         "type": "Reference",
-                        "target": "PtlLogin/PlayerInfo"
+                        "target": "MsgResLogin/PlayerInfo"
                     },
                     "optional": true
                 },
                 {
-                    "id": 5,
+                    "id": 3,
                     "name": "isNewPlayer",
                     "type": {
                         "type": "Boolean"
@@ -232,7 +276,7 @@ export const serviceProto: ServiceProto<ServiceType> = {
                 }
             ]
         },
-        "PtlLogin/PlayerInfo": {
+        "MsgResLogin/PlayerInfo": {
             "type": "Interface",
             "properties": [
                 {
@@ -302,26 +346,7 @@ export const serviceProto: ServiceProto<ServiceType> = {
                 }
             ]
         },
-        "PtlMove/ReqMove": {
+        "MsgResMove/MsgResMove": {
-            "type": "Interface",
-            "properties": [
-                {
-                    "id": 0,
-                    "name": "x",
-                    "type": {
-                        "type": "Number"
-                    }
-                },
-                {
-                    "id": 1,
-                    "name": "y",
-                    "type": {
-                        "type": "Number"
-                    }
-                }
-            ]
-        },
-        "PtlMove/ResMove": {
             "type": "Interface",
             "properties": [
                 {
@@ -336,8 +361,7 @@ export const serviceProto: ServiceProto<ServiceType> = {
                     "name": "message",
                     "type": {
                         "type": "String"
-                    },
+                    }
-                    "optional": true
                 },
                 {
                     "id": 2,
@@ -350,19 +374,7 @@ export const serviceProto: ServiceProto<ServiceType> = {
                 }
             ]
         },
-        "PtlSend/ReqSend": {
+        "MsgResSend/MsgResSend": {
-            "type": "Interface",
-            "properties": [
-                {
-                    "id": 0,
-                    "name": "content",
-                    "type": {
-                        "type": "String"
-                    }
-                }
-            ]
-        },
-        "PtlSend/ResSend": {
             "type": "Interface",
             "properties": [
                 {