# 基于 WebMan 的即时通信应用后端开发指南 ## 目录结构 ``` webman/ ├── app/ # 应用目录 │ ├── controller/ # 控制器目录 │ │ ├── v1/ # API版本管理 │ │ └── websocket/ # WebSocket控制器 │ ├── dto/ # 数据传输对象 │ ├── enum/ # 枚举定义 │ ├── exception/ # 自定义异常处理 │ ├── extends/ # 扩展功能 │ ├── middleware/ # 中间件 │ ├── model/ # 数据模型 │ │ ├── user/ # 用户相关模型 │ │ ├── message/ # 消息相关模型 │ │ └── group/ # 群组相关模型 │ ├── process/ # 自定义进程 │ ├── route/ # 路由配置 │ ├── service/ # 业务服务层 │ │ ├── user/ # 用户服务 │ │ ├── message/ # 消息服务 │ │ └── group/ # 群组服务 │ ├── utils/ # 工具类 │ ├── view/ # 视图文件 (如有需要) │ ├── websocket/ # WebSocket处理 │ │ ├── handler/ # 消息处理器 │ │ └── protocol/ # 自定义协议 │ ├── events/ # 事件定义 │ ├── listeners/ # 事件监听器 │ ├── queue/ # 队列处理 │ ├── cache/ # 缓存处理 │ ├── push/ # 推送服务 │ └── functions.php # 自定义函数 ├── config/ # 配置文件目录 ├── public/ # 静态资源目录 ├── runtime/ # 运行时目录 (日志、缓存) ├── support/ # 支持类库 ├── vendor/ # Composer 依赖 ├── generateModels/ # 模型生成工具 ├── composer.json # Composer 配置 ├── start.php # 启动文件 └── windows.php # Windows 环境启动文件 ``` ## 代码规范 ### 1. 命名规范 - **命名空间**: 使用 PSR-4 规范, 与目录结构保持一致 - **类名**: 使用 PascalCase (大驼峰命名), 例如 `UserController` - **方法名**: 使用 camelCase (小驼峰命名), 例如 `getUserInfo()` - **变量名**: 使用 camelCase 命名 - **常量**: 使用大写下划线命名, 例如 `MAX_CONNECTION_COUNT` - **控制器** 使用控制器名称 + Controller 例如：`IndexController` - **模型** 使用模型名称 + Model 例如：`UserModel` - **服务类** 使用服务类名称 + Service 例如：`LoginService` ### 2. 注释规范 - 类注释应包含类的作用、作者、创建日期 - 每个模型应在模型名称上包含该模型对应的数据表字段注释 `@property` - 方法注释应包含功能说明、参数说明、返回值说明 - 复杂逻辑应添加适当行内注释 ### 3. 接口规范 - RESTful API 设计 - 统一响应格式: 使用 自定义 `buildSuccess` 和 `buildFailed` 函数统一响应数据 ```php [ 'code' => 0, 'message' => 'success', 'data' => [] ] ``` - 版本控制: 在 URI 中使用版本号, 例如 `/api/v1/user` ### 4. 数据库规范 - 表名使用小写下划线命名法, 如 `user_message` - 主键统一命名为 `id` - 字段命名使用小写下划线命名法 - 每个表必须包含 `created_at` 和 `updated_at` 字段 - 软删除使用 `deleted_at` 字段 ## 其他规范 - 每个功能必须编写测试用例 - 每个功能必须编写API文档 ## 异常管理 - 自定义异常 - 通过日志记录致命异常 ## 技术栈 - model层 使用 `\support\Model` 底部由Eloquent ORM支持 - redis使用 使用 `\support\Redis` 底部由illuminate/redis支持 - JWT 使用 `\Tinywan\Jwt` - 日志 使用 `support\Log` 底部由monolog/monolog支持 ## 即时通信功能实现要点 ### 1. 用户认证 - JWT 认证 - 在线状态管理 - 多终端登录处理 ### 2. 消息处理 - 消息推送使用 WebSocket - 消息持久化 - 已读回执 - 离线消息处理 ### 3. 群组消息 - 群成员管理 - 群消息广播 - 群事件通知 ### 4. 实时连接管理 - 心跳检测 - 连接复用 - 连接监控与统计 ### 5. 性能优化 - 消息队列解耦 - Redis 缓存热点数据 - 分布式部署配置 ## 启动服务 - 开发环境：`php start.php start` - 生产环境：`php start.php start -d` (守护进程模式) - Windows环境：`windows.bat` 或 `php windows.php` ## 扩展建议 - 使用 Redis 存储用户状态 - 消息队列选择 RabbitMQ 或 Kafka - 使用 ELK 进行日志分析 - 实现分布式架构时考虑使用 Gateway Worker 进程模型 ## 项目优先级 # WebMan 即时通信应用后端开发优先级 ## 一、核心基础层（最高优先级） 1. **基础架构搭建** ✅ 已完成 - WebMan 框架配置与初始化 ✅ 已完成 - 数据库连接配置 ✅ 已完成 - Redis 连接配置 ✅ 已完成 - 日志系统配置 ✅ 已完成 - 异常处理机制 ✅ 已完成 2. **用户认证系统** ✅ 已完成 - 用户注册/登录接口 ✅ 已完成 - JWT 认证实现 ✅ 已完成 - 会话管理 ✅ 已完成 - 多端登录支持 ✅ 已完成 3. **WebSocket 核心** ✅ 已完成 - WebSocket 连接管理 ✅ 已完成 - 基础消息协议定义 ✅ 已完成 - 连接鉴权 ✅ 已完成 - 心跳机制 ✅ 已完成 ## 二、通信核心层（高优先级） 1. **单聊消息** ✅ 已完成 - 消息发送与接收 ✅ 已完成 - 消息持久化 ✅ 已完成 - 已读回执 ✅ 已完成 - 离线消息处理 ✅ 已完成 2. **连接状态管理** ✅ 已完成 - 用户在线状态维护 ✅ 已完成 - 断线重连机制 ✅ 已完成 - 状态同步 ✅ 已完成 3. **消息队列** ⚠️ 部分完成 - 消息异步处理 ✅ 已完成 - 消息投递保障 ⏳ 进行中 - 高并发消息处理 ⏳ 进行中 ## 三、功能扩展层（中等优先级） 1. **群聊功能** ✅ 已完成 - 群组创建与管理 ✅ 已完成 - 群成员管理 ✅ 已完成 - 群消息广播 ✅ 已完成 - 群事件通知 ✅ 已完成 2. **消息类型扩展** ✅ 已完成 - 文本消息 ✅ 已完成 - 图片消息 ✅ 已完成 - 语音消息 ✅ 已完成 - 文件传输 ✅ 已完成 3. **好友关系** ✅ 已完成 - 好友添加与删除 ✅ 已完成 - 好友分组 ✅ 已完成 - 好友状态 ✅ 已完成 ## 四、性能与监控层（中等优先级） 1. **性能优化** ⚠️ 部分完成 - 连接池管理 ⏳ 进行中 - 数据库查询优化 ✅ 已完成 - 缓存策略实现 ⏳ 进行中 2. **监控系统** ⏳ 进行中 - 连接数监控 ⏳ 进行中 - 消息吞吐量监控 ⏳ 进行中 - 系统资源监控 ⏳ 进行中 - 异常监控与告警 ⏳ 进行中 ## 五、高级功能层（较低优先级） 1. **多媒体处理** ⏳ 进行中 - 图片处理与缩略图 ⏳ 进行中 - 语音转文字 ⏳ 进行中 - 视频压缩与处理 ⏳ 进行中 2. **消息扩展功能** ✅ 已完成 - 消息撤回 ✅ 已完成 - 消息转发 ✅ 已完成 - @功能实现 ✅ 已完成 - 消息搜索 ✅ 已完成 3. **通知系统** ⏳ 进行中 - 系统通知 ⏳ 进行中 - 自定义通知 ⏳ 进行中 - 推送服务集成 ⏳ 进行中 ## 六、安全与运维层（持续进行） 1. **安全措施** ⚠️ 部分完成 - 消息加密 ✅ 已完成 - 内容过滤 ⏳ 进行中 - 防护 XSS、CSRF ✅ 已完成 - 速率限制 ⏳ 进行中 2. **运维支持** ⏳ 进行中 - 分布式部署支持 ⏳ 进行中 - 平滑重启机制 ⏳ 进行中 - 备份与恢复策略 ⏳ 进行中 - 部署自动化 ⏳ 进行中 ## 七、扩展与集成层（最低优先级） 1. **第三方集成** ⏳ 进行中 - 第三方登录 ⏳ 进行中 - 外部存储服务 ⏳ 进行中 - 第三方推送 ⏳ 进行中 2. **业务扩展** ⏳ 进行中 - 红包功能 ⏳ 进行中 - 位置共享 ⏳ 进行中 - 实时音视频通话集成 ⏳ 进行中 ## 开发建议 1. **阶段性开发**： - 第一阶段：完成核心基础层和通信核心层，实现基本的单聊功能 ✅ 已完成 - 第二阶段：实现功能扩展层和性能与监控层 ⚠️ 部分完成 - 第三阶段：开发高级功能和集成扩展 ⏳ 进行中 2. **持续优化**： - 安全与运维层应贯穿整个开发过程 - 每完成一个模块及时进行性能测试和优化 3. **测试策略**： - 核心功能需编写单元测试 ✅ 已完成 - 关键模块进行压力测试 ⏳ 进行中 - 实现端到端的集成测试 ⏳ 进行中 ## 最近完成的工作 - ✅ 好友关系服务与单元测试实现 (2024-03-21) - ✅ 群组服务实现与单元测试 (2024-03-21) - ✅ 消息API响应格式修复与统一 (2024-03-21) - ✅ JwtAuthMiddleware中间件完善 (2024-03-21) - ✅ 消息接口测试用例编写 (2024-03-21) - ✅ 消息相关API文档编写 (2024-03-21) ## 项目进度 - [x] 用户管理 - 已完成 - [x] 注册/登录/登出 - [x] JWT认证 - [x] 用户信息管理 - [x] 在线状态 - [x] 好友关系 - 已完成 - [x] 添加/删除好友 - [x] 好友分组 - [x] 好友列表 - [x] 好友状态 - [x] 私信功能 - 已完成 - [x] 发送/接收消息 - [x] 消息状态(已读/未读) - [x] 历史消息 - [x] 多媒体消息(图片/语音/视频) - [x] 群聊功能 - 已完成 - [x] 创建/加入/退出群组 - [x] 群组管理 - [x] 群组消息 - [x] 成员权限