feature/websocket-unify-and-openapi-update #38

moyin · 2026-01-09T17:50:05+08:00

moyin commented

2026-01-09 17:50:05 +08:00

WebSocket 统一配置与 OpenAPI 文档更新

📋 合并请求概述

分支: feature/websocket-unify-and-openapi-update
目标分支: main
类型: 功能增强 + 文档更新
优先级: 中等

🎯 更改目标

本次合并请求旨在统一项目中的 WebSocket 配置，完善 OpenAPI 文档，并提供完整的测试工具，为开发者提供更好的 WebSocket 开发体验。

📝 更改摘要

核心更改

统一 WebSocket 网关: 使用 CleanWebSocketGateway 作为唯一的 WebSocket 网关
标准化路径: 所有 WebSocket 连接统一使用 /game 路径
完善文档: 全面更新 OpenAPI 文档和示例代码
测试工具: 新增交互式测试页面和 API 文档

技术改进

移除 Socket.IO 依赖，完全使用原生 WebSocket
统一端口配置（3001），支持环境变量配置
提供 Nginx 反向代理配置指南
增强错误处理和连接监控

🔧 详细更改列表

1. WebSocket 网关统一 (`websocket：统一WebSocket网关配置`)

文件: src/business/zulip/clean_websocket.gateway.ts, src/business/zulip/zulip.module.ts

更改内容:

✅ 为 CleanWebSocketGateway 添加 path: '/game' 配置
✅ 支持通过 WEBSOCKET_PORT 环境变量配置端口
✅ 移除 ZulipWebSocketGateway 的模块引用
✅ 更新模块注释，反映当前架构

影响:

统一了 WebSocket 入口点
简化了架构，减少了维护复杂度
提高了配置的灵活性

2. API 接口更新 (`api：更新WebSocket连接信息接口`)

文件: src/business/zulip/chat.controller.ts

更改内容:

✅ 更新 WebSocket URL 为 wss://whaletownend.xinghangee.icu/game
✅ 添加协议类型和路径信息
✅ 移除未使用的导入
✅ 完善 API 响应结构

影响:

API 文档更加准确
开发者能获得正确的连接信息

3. OpenAPI 主配置更新 (`docs：更新主应用OpenAPI配置`)

文件: src/main.ts

更改内容:

✅ 更新 WebSocket 连接地址说明
✅ 添加开发和生产环境服务器配置
✅ 完善 WebSocket 功能描述
✅ 统一文档中的连接信息

影响:

Swagger UI 显示正确的 WebSocket 信息
开发者能快速了解连接方式

4. 文档示例更新 (`docs：更新WebSocket文档示例代码`)

文件: src/business/zulip/websocket_docs.controller.ts

更改内容:

✅ 将 Socket.IO 示例替换为原生 WebSocket
✅ 更新 JavaScript 和 Godot 客户端示例
✅ 统一使用 /game 路径
✅ 简化示例代码，提高可读性

影响:

示例代码与实际实现一致
开发者能直接使用示例代码

5. 新增 WebSocket OpenAPI 控制器 (`feat：添加WebSocket OpenAPI文档控制器`)

文件: src/business/zulip/websocket_openapi.controller.ts (新增)

功能特性:

📋 详细的连接信息和配置说明
📋 完整的消息格式文档
📋 架构信息和性能指标
📋 多语言客户端示例（JavaScript, Python, Node.js）
📋 故障排除指南

API 端点:

GET /websocket-api/connection-info - 连接配置信息
GET /websocket-api/architecture - 架构详情
GET /websocket-api/testing-tools - 测试工具和示例
POST /websocket-api/login - 登录消息格式文档
POST /websocket-api/chat - 聊天消息格式文档
POST /websocket-api/position - 位置更新格式文档

6. 新增 WebSocket 测试页面 (`feat：添加WebSocket测试页面控制器`)

文件: src/business/zulip/websocket_test.controller.ts (新增)

功能特性:

🧪 交互式 WebSocket 连接测试
🧪 实时消息发送和接收
🧪 JWT Token 认证测试
🧪 聊天和位置更新功能测试
🧪 连接状态监控和日志记录

访问地址: /websocket-test

🔍 测试验证

自动化测试

✅ 所有现有测试通过
✅ 新增代码通过 TypeScript 编译
✅ 代码风格检查通过

手动测试

✅ WebSocket 连接测试成功
✅ 消息发送和接收正常
✅ 错误处理机制正常
✅ 文档页面正常显示

测试结果

🧪 WebSocket 连接测试工具
=====================================

📍 测试主地址: wss://whaletownend.xinghangee.icu/game
✅ WebSocket 连接成功建立
📊 连接信息正常
📨 消息收发正常
🎉 WebSocket 连接测试通过！

🚀 部署说明

1. Nginx 配置更新

需要更新 Nginx 配置以支持新的 WebSocket 路径：

location /game {
    proxy_pass http://127.0.0.1:3001;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    # ... 其他配置
}

2. 环境变量

可选的环境变量配置：

WEBSOCKET_PORT=3001          # WebSocket 端口（默认 3001）
WEBSOCKET_NAMESPACE=/game    # WebSocket 路径（默认 /game）

3. 服务重启

部署后需要重启应用服务器以应用新的 WebSocket 配置。

📚 文档更新

新增文档

WebSocket API 完整文档
多语言客户端示例
架构说明和性能指标
故障排除指南

更新文档

Swagger UI 中的 WebSocket 信息
连接示例和配置说明
开发者指南

🔒 安全考虑

✅ JWT Token 验证机制保持不变
✅ 消息格式验证正常
✅ 连接限制和速率限制有效
✅ 敏感信息不在日志中暴露

📊 性能影响

正面影响

🚀 移除 Socket.IO 依赖，减少内存占用
🚀 原生 WebSocket 性能更优
🚀 统一网关减少资源消耗

潜在影响

⚠️ 需要重新配置 Nginx 代理
⚠️ 客户端需要更新连接地址

🔄 向后兼容性

兼容性说明

❌ 不兼容: Socket.IO 客户端需要迁移到原生 WebSocket
✅ 兼容: REST API 接口保持不变
✅ 兼容: JWT 认证机制不变
✅ 兼容: 消息格式基本保持一致

迁移指南

客户端需要从：

// 旧的 Socket.IO 方式
const socket = io('wss://whaletownend.xinghangee.icu');

迁移到：

// 新的原生 WebSocket 方式
const ws = new WebSocket('wss://whaletownend.xinghangee.icu/game');

🎯 验收标准

功能验收

WebSocket 连接正常建立
消息发送和接收正常
JWT 认证机制正常
错误处理正确
文档页面正常显示

性能验收

连接延迟 < 100ms
消息传输延迟 < 50ms
内存使用无明显增加
CPU 使用正常

文档验收

Swagger UI 信息准确
示例代码可执行
测试页面功能完整
故障排除指南有效

🔗 相关链接

测试页面: /websocket-test
API 文档: /api-docs (WebSocket 标签)
架构信息: /websocket-api/architecture
连接信息: /websocket-api/connection-info

👥 审查要点

代码审查

架构设计: WebSocket 网关统一是否合理
代码质量: 新增代码是否符合项目规范
错误处理: 异常情况处理是否完善
性能影响: 是否有性能回归

文档审查

准确性: 文档内容是否与实现一致
完整性: 是否涵盖所有必要信息
可用性: 开发者是否能快速上手
示例代码: 是否可以直接运行

测试审查

覆盖率: 测试是否覆盖主要功能
边界条件: 是否测试了异常情况
集成测试: 是否验证了端到端流程
性能测试: 是否验证了性能指标

📅 合并时间表

代码审查: 1-2 个工作日
测试验证: 1 个工作日
部署准备: 1 个工作日
正式合并: 审查通过后

🚨 风险评估

高风险

无

中风险

Nginx 配置: 需要正确配置反向代理
客户端迁移: 现有客户端需要更新

低风险

文档更新: 可能需要后续微调
性能调优: 可能需要根据实际使用情况优化

📞 联系信息

如有问题或需要澄清，请联系：

开发者: [您的姓名]
审查者: [待指定]
测试负责人: [待指定]

合并请求创建时间: 2026-01-09
预计合并时间: 2026-01-12
影响范围: WebSocket 功能、API 文档、开发者工具

# WebSocket 统一配置与 OpenAPI 文档更新 ## 📋 合并请求概述 **分支**: `feature/websocket-unify-and-openapi-update` **目标分支**: `main` **类型**: 功能增强 + 文档更新 **优先级**: 中等 ## 🎯 更改目标本次合并请求旨在统一项目中的 WebSocket 配置，完善 OpenAPI 文档，并提供完整的测试工具，为开发者提供更好的 WebSocket 开发体验。 ## 📝 更改摘要 ### 核心更改 1. **统一 WebSocket 网关**: 使用 `CleanWebSocketGateway` 作为唯一的 WebSocket 网关 2. **标准化路径**: 所有 WebSocket 连接统一使用 `/game` 路径 3. **完善文档**: 全面更新 OpenAPI 文档和示例代码 4. **测试工具**: 新增交互式测试页面和 API 文档 ### 技术改进 - 移除 Socket.IO 依赖，完全使用原生 WebSocket - 统一端口配置（3001），支持环境变量配置 - 提供 Nginx 反向代理配置指南 - 增强错误处理和连接监控 ## 🔧 详细更改列表 ### 1. WebSocket 网关统一 (`websocket：统一WebSocket网关配置`) **文件**: `src/business/zulip/clean_websocket.gateway.ts`, `src/business/zulip/zulip.module.ts` **更改内容**: - ✅ 为 `CleanWebSocketGateway` 添加 `path: '/game'` 配置 - ✅ 支持通过 `WEBSOCKET_PORT` 环境变量配置端口 - ✅ 移除 `ZulipWebSocketGateway` 的模块引用 - ✅ 更新模块注释，反映当前架构 **影响**: - 统一了 WebSocket 入口点 - 简化了架构，减少了维护复杂度 - 提高了配置的灵活性 ### 2. API 接口更新 (`api：更新WebSocket连接信息接口`) **文件**: `src/business/zulip/chat.controller.ts` **更改内容**: - ✅ 更新 WebSocket URL 为 `wss://whaletownend.xinghangee.icu/game` - ✅ 添加协议类型和路径信息 - ✅ 移除未使用的导入 - ✅ 完善 API 响应结构 **影响**: - API 文档更加准确 - 开发者能获得正确的连接信息 ### 3. OpenAPI 主配置更新 (`docs：更新主应用OpenAPI配置`) **文件**: `src/main.ts` **更改内容**: - ✅ 更新 WebSocket 连接地址说明 - ✅ 添加开发和生产环境服务器配置 - ✅ 完善 WebSocket 功能描述 - ✅ 统一文档中的连接信息 **影响**: - Swagger UI 显示正确的 WebSocket 信息 - 开发者能快速了解连接方式 ### 4. 文档示例更新 (`docs：更新WebSocket文档示例代码`) **文件**: `src/business/zulip/websocket_docs.controller.ts` **更改内容**: - ✅ 将 Socket.IO 示例替换为原生 WebSocket - ✅ 更新 JavaScript 和 Godot 客户端示例 - ✅ 统一使用 `/game` 路径 - ✅ 简化示例代码，提高可读性 **影响**: - 示例代码与实际实现一致 - 开发者能直接使用示例代码 ### 5. 新增 WebSocket OpenAPI 控制器 (`feat：添加WebSocket OpenAPI文档控制器`) **文件**: `src/business/zulip/websocket_openapi.controller.ts` (新增) **功能特性**: - 📋 详细的连接信息和配置说明 - 📋 完整的消息格式文档 - 📋 架构信息和性能指标 - 📋 多语言客户端示例（JavaScript, Python, Node.js） - 📋 故障排除指南 **API 端点**: - `GET /websocket-api/connection-info` - 连接配置信息 - `GET /websocket-api/architecture` - 架构详情 - `GET /websocket-api/testing-tools` - 测试工具和示例 - `POST /websocket-api/login` - 登录消息格式文档 - `POST /websocket-api/chat` - 聊天消息格式文档 - `POST /websocket-api/position` - 位置更新格式文档 ### 6. 新增 WebSocket 测试页面 (`feat：添加WebSocket测试页面控制器`) **文件**: `src/business/zulip/websocket_test.controller.ts` (新增) **功能特性**: - 🧪 交互式 WebSocket 连接测试 - 🧪 实时消息发送和接收 - 🧪 JWT Token 认证测试 - 🧪 聊天和位置更新功能测试 - 🧪 连接状态监控和日志记录 **访问地址**: `/websocket-test` ## 🔍 测试验证 ### 自动化测试 - ✅ 所有现有测试通过 - ✅ 新增代码通过 TypeScript 编译 - ✅ 代码风格检查通过 ### 手动测试 - ✅ WebSocket 连接测试成功 - ✅ 消息发送和接收正常 - ✅ 错误处理机制正常 - ✅ 文档页面正常显示 ### 测试结果 ``` 🧪 WebSocket 连接测试工具 ===================================== 📍 测试主地址: wss://whaletownend.xinghangee.icu/game ✅ WebSocket 连接成功建立 📊 连接信息正常 📨 消息收发正常 🎉 WebSocket 连接测试通过！ ``` ## 🚀 部署说明 ### 1. Nginx 配置更新需要更新 Nginx 配置以支持新的 WebSocket 路径： ```nginx location /game { proxy_pass http://127.0.0.1:3001; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection $connection_upgrade; # ... 其他配置 } ``` ### 2. 环境变量可选的环境变量配置： ```bash WEBSOCKET_PORT=3001 # WebSocket 端口（默认 3001） WEBSOCKET_NAMESPACE=/game # WebSocket 路径（默认 /game） ``` ### 3. 服务重启部署后需要重启应用服务器以应用新的 WebSocket 配置。 ## 📚 文档更新 ### 新增文档 - WebSocket API 完整文档 - 多语言客户端示例 - 架构说明和性能指标 - 故障排除指南 ### 更新文档 - Swagger UI 中的 WebSocket 信息 - 连接示例和配置说明 - 开发者指南 ## 🔒 安全考虑 - ✅ JWT Token 验证机制保持不变 - ✅ 消息格式验证正常 - ✅ 连接限制和速率限制有效 - ✅ 敏感信息不在日志中暴露 ## 📊 性能影响 ### 正面影响 - 🚀 移除 Socket.IO 依赖，减少内存占用 - 🚀 原生 WebSocket 性能更优 - 🚀 统一网关减少资源消耗 ### 潜在影响 - ⚠️ 需要重新配置 Nginx 代理 - ⚠️ 客户端需要更新连接地址 ## 🔄 向后兼容性 ### 兼容性说明 - ❌ **不兼容**: Socket.IO 客户端需要迁移到原生 WebSocket - ✅ **兼容**: REST API 接口保持不变 - ✅ **兼容**: JWT 认证机制不变 - ✅ **兼容**: 消息格式基本保持一致 ### 迁移指南客户端需要从： ```javascript // 旧的 Socket.IO 方式 const socket = io('wss://whaletownend.xinghangee.icu'); ``` 迁移到： ```javascript // 新的原生 WebSocket 方式 const ws = new WebSocket('wss://whaletownend.xinghangee.icu/game'); ``` ## 🎯 验收标准 ### 功能验收 - [ ] WebSocket 连接正常建立 - [ ] 消息发送和接收正常 - [ ] JWT 认证机制正常 - [ ] 错误处理正确 - [ ] 文档页面正常显示 ### 性能验收 - [ ] 连接延迟 < 100ms - [ ] 消息传输延迟 < 50ms - [ ] 内存使用无明显增加 - [ ] CPU 使用正常 ### 文档验收 - [ ] Swagger UI 信息准确 - [ ] 示例代码可执行 - [ ] 测试页面功能完整 - [ ] 故障排除指南有效 ## 🔗 相关链接 - **测试页面**: `/websocket-test` - **API 文档**: `/api-docs` (WebSocket 标签) - **架构信息**: `/websocket-api/architecture` - **连接信息**: `/websocket-api/connection-info` ## 👥 审查要点 ### 代码审查 1. **架构设计**: WebSocket 网关统一是否合理 2. **代码质量**: 新增代码是否符合项目规范 3. **错误处理**: 异常情况处理是否完善 4. **性能影响**: 是否有性能回归 ### 文档审查 1. **准确性**: 文档内容是否与实现一致 2. **完整性**: 是否涵盖所有必要信息 3. **可用性**: 开发者是否能快速上手 4. **示例代码**: 是否可以直接运行 ### 测试审查 1. **覆盖率**: 测试是否覆盖主要功能 2. **边界条件**: 是否测试了异常情况 3. **集成测试**: 是否验证了端到端流程 4. **性能测试**: 是否验证了性能指标 ## 📅 合并时间表 - **代码审查**: 1-2 个工作日 - **测试验证**: 1 个工作日 - **部署准备**: 1 个工作日 - **正式合并**: 审查通过后 ## 🚨 风险评估 ### 高风险 - 无 ### 中风险 - **Nginx 配置**: 需要正确配置反向代理 - **客户端迁移**: 现有客户端需要更新 ### 低风险 - **文档更新**: 可能需要后续微调 - **性能调优**: 可能需要根据实际使用情况优化 ## 📞 联系信息如有问题或需要澄清，请联系： - **开发者**: [您的姓名] - **审查者**: [待指定] - **测试负责人**: [待指定] --- **合并请求创建时间**: 2026-01-09 **预计合并时间**: 2026-01-12 **影响范围**: WebSocket 功能、API 文档、开发者工具

moyin added 6 commits 2026-01-09 17:50:05 +08:00

websocket：统一WebSocket网关配置 75ac7ac0f8

- 为CleanWebSocketGateway添加/game路径配置
- 支持通过环境变量WEBSOCKET_PORT配置端口
- 移除ZulipWebSocketGateway的模块引用
- 统一使用CleanWebSocketGateway作为唯一WebSocket网关
- 更新模块注释，反映当前架构

api：更新WebSocket连接信息接口 3904a782c7

- 更新WebSocket URL为统一的/game路径
- 添加协议类型和路径信息
- 移除未使用的ZulipWebSocketGateway导入
- 完善WebSocket连接信息的API响应

docs：更新主应用OpenAPI配置 9e0e07b07c

- 更新WebSocket连接地址为/game路径
- 添加开发和生产环境的WebSocket服务器配置
- 完善WebSocket连接说明文档
- 统一API文档中的WebSocket信息

docs：更新WebSocket文档示例代码 ef618d5222

- 将Socket.IO示例替换为原生WebSocket代码
- 更新JavaScript和Godot客户端示例
- 统一使用/game路径的WebSocket连接
- 简化示例代码，移除复杂的Godot逻辑

feat：添加WebSocket OpenAPI文档控制器 f840d3e708

- 新增专门的WebSocket API文档控制器
- 提供详细的连接信息和配置说明
- 包含完整的消息格式文档和示例
- 添加架构信息和测试工具指南
- 支持多种编程语言的客户端示例

feat：添加WebSocket测试页面控制器 ca21982857

- 新增交互式WebSocket测试页面
- 提供完整的连接测试和消息发送功能
- 支持登录认证和聊天消息测试
- 包含位置更新和地图切换功能
- 提供实时消息日志和连接状态监控

moyin merged commit 5b56589dea into main

2026-01-09 17:50:13 +08:00

moyin deleted branch feature/websocket-unify-and-openapi-update

2026-01-09 17:50:14 +08:00

moyin referenced this issue from a commit

2026-01-09 17:50:14 +08:00

Merge pull request 'feature/websocket-unify-and-openapi-update' (#38) from feature/websocket-unify-and-openapi-update into main

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: datawhale/whale-town-end#38

feature/websocket-unify-and-openapi-update #38

WebSocket 统一配置与 OpenAPI 文档更新

📋 合并请求概述

🎯 更改目标

📝 更改摘要

核心更改

技术改进

🔧 详细更改列表

1. WebSocket 网关统一 (websocket：统一WebSocket网关配置)

2. API 接口更新 (api：更新WebSocket连接信息接口)

3. OpenAPI 主配置更新 (docs：更新主应用OpenAPI配置)

4. 文档示例更新 (docs：更新WebSocket文档示例代码)

5. 新增 WebSocket OpenAPI 控制器 (feat：添加WebSocket OpenAPI文档控制器)

6. 新增 WebSocket 测试页面 (feat：添加WebSocket测试页面控制器)

🔍 测试验证

自动化测试

手动测试

测试结果

🚀 部署说明

1. Nginx 配置更新

2. 环境变量

3. 服务重启

📚 文档更新

新增文档

更新文档

🔒 安全考虑

📊 性能影响

正面影响

潜在影响

🔄 向后兼容性

兼容性说明

迁移指南

🎯 验收标准

功能验收

性能验收

文档验收

🔗 相关链接

👥 审查要点

代码审查

文档审查

测试审查

📅 合并时间表

🚨 风险评估

高风险

中风险

低风险

📞 联系信息

1. WebSocket 网关统一 (`websocket：统一WebSocket网关配置`)

2. API 接口更新 (`api：更新WebSocket连接信息接口`)

3. OpenAPI 主配置更新 (`docs：更新主应用OpenAPI配置`)

4. 文档示例更新 (`docs：更新WebSocket文档示例代码`)

5. 新增 WebSocket OpenAPI 控制器 (`feat：添加WebSocket OpenAPI文档控制器`)

6. 新增 WebSocket 测试页面 (`feat：添加WebSocket测试页面控制器`)