{"id":28961909,"url":"https://github.com/hyperf-plus/actor","last_synced_at":"2025-06-24T02:32:49.369Z","repository":{"id":300780401,"uuid":"1007150761","full_name":"hyperf-plus/actor","owner":"hyperf-plus","description":"高性能、多进程、高稳定性的Actor系统，专为游戏场景优化。","archived":false,"fork":false,"pushed_at":"2025-06-23T14:48:33.000Z","size":73,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-23T15:45:12.852Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hyperf-plus.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-23T14:37:35.000Z","updated_at":"2025-06-23T14:48:36.000Z","dependencies_parsed_at":"2025-06-23T15:55:58.196Z","dependency_job_id":null,"html_url":"https://github.com/hyperf-plus/actor","commit_stats":null,"previous_names":["hyperf-plus/actor"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hyperf-plus/actor","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Factor","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Factor/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Factor/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Factor/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hyperf-plus","download_url":"https://codeload.github.com/hyperf-plus/actor/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hyperf-plus%2Factor/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261591681,"owners_count":23181773,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-24T02:31:22.391Z","updated_at":"2025-06-24T02:32:49.362Z","avatar_url":"https://github.com/hyperf-plus.png","language":"PHP","readme":"# HPlus Actor 模型组件\n\n高性能、多进程、高稳定性的Actor系统，专为游戏场景优化。\n\n## 特性\n\n- 🚀 **高性能**: 基于Swoole协程，支持大并发\n- 🔄 **多进程**: 多工作进程并行处理消息\n- 🛡️ **高稳定性**: 完善的错误处理和Actor重启机制\n- 🎮 **游戏优化**: 专门为游戏场景设计的Actor类型\n- 📊 **监控统计**: 实时监控Actor系统状态\n- 🔧 **易于扩展**: 灵活的Actor继承和消息系统\n\n## 安装\n\n```bash\ncomposer require hyperf-plus/actor\n```\n\n## 配置\n\n发布配置文件：\n\n```bash\nphp bin/hyperf.php vendor:publish hyperf-plus/actor\n```\n\n配置文件位于 `config/autoload/actor.php`\n\n## 快速开始\n\n### 1. 创建自定义Actor\n\n```php\n\u003c?php\nuse HPlus\\Actor\\AbstractActor;\nuse HPlus\\Actor\\Message\\MessageInterface;\n\nclass MyGameActor extends AbstractActor\n{\n    public function receive(MessageInterface $message): mixed\n    {\n        $type = $message-\u003egetType();\n        $payload = $message-\u003egetPayload();\n\n        return match ($type) {\n            'hello' =\u003e $this-\u003ehandleHello($payload),\n            'ping' =\u003e ['pong' =\u003e time()],\n            default =\u003e ['error' =\u003e 'Unknown message type'],\n        };\n    }\n\n    private function handleHello(array $payload): array\n    {\n        $name = $payload['name'] ?? 'World';\n        return ['message' =\u003e \"Hello, {$name}!\"];\n    }\n}\n```\n\n### 2. 创建和使用Actor\n\n```php\n\u003c?php\nuse HPlus\\Actor\\System\\ActorSystem;\nuse HPlus\\Actor\\Message\\Message;\n\n// 获取Actor系统\n$actorSystem = $container-\u003eget(ActorSystem::class);\n\n// 创建Actor\n$actorPath = $actorSystem-\u003eactorOf(MyGameActor::class, 'my-actor');\n\n// 发送消息\n$message = new Message('hello', ['name' =\u003e 'HPlus']);\n$router = $actorSystem-\u003egetRouter();\n$router-\u003eroute($message);\n```\n\n### 3. 游戏场景示例\n\n```php\n\u003c?php\nuse HPlus\\Actor\\Game\\PlayerActor;\nuse HPlus\\Actor\\Game\\RoomActor;\n\n// 创建游戏房间\n$roomPath = $actorSystem-\u003eactorOf(RoomActor::class, 'game-room-1', [\n    'max_players' =\u003e 4,\n    'min_players' =\u003e 2,\n]);\n\n// 创建玩家\n$playerPath = $actorSystem-\u003eactorOf(PlayerActor::class, 'player-1');\n\n// 玩家加入房间\n$joinMessage = new Message('player.join_room', [\n    'room_path' =\u003e $roomPath,\n]);\n```\n\n## 核心概念\n\n### Actor模型\n\nActor是系统中的基本计算单元，具有以下特点：\n\n- **独立性**: 每个Actor都有自己的状态和行为\n- **消息传递**: Actor之间通过异步消息通信\n- **顺序处理**: 每个Actor按顺序处理消息\n- **容错性**: Actor失败不会影响其他Actor\n\n### 消息系统\n\n消息是Actor之间通信的载体：\n\n```php\n$message = new Message(\n    'message_type',     // 消息类型\n    ['key' =\u003e 'value'], // 消息载荷\n    '/user/target',     // 接收者路径\n    '/user/sender',     // 发送者路径\n    1,                  // 优先级\n    true,               // 是否需要回复\n    'reply_id'          // 回复ID\n);\n```\n\n### 邮箱系统\n\n每个Actor都有一个邮箱来接收和缓存消息：\n\n- **容量控制**: 防止内存溢出\n- **优先级**: 支持消息优先级\n- **批处理**: 提高处理效率\n\n## 游戏专用组件\n\n### PlayerActor\n\n处理玩家相关逻辑：\n\n```php\n// 玩家登录\n$loginMsg = new Message('player.login', [\n    'username' =\u003e 'player1',\n    'level' =\u003e 10,\n]);\n\n// 玩家游戏动作\n$actionMsg = new Message('player.game_action', [\n    'action_type' =\u003e 'move',\n    'x' =\u003e 100,\n    'y' =\u003e 200,\n]);\n```\n\n### RoomActor\n\n管理游戏房间：\n\n```php\n// 开始游戏\n$startMsg = new Message('room.start_game', [\n    'game_mode' =\u003e 'classic',\n    'duration' =\u003e 300,\n]);\n\n// 广播消息\n$broadcastMsg = new Message('room.broadcast', [\n    'message' =\u003e 'Game will start in 10 seconds',\n]);\n```\n\n## 监控和管理\n\n### 查看系统状态\n\n```bash\nphp bin/hyperf.php actor:stats\n```\n\n### 实时监控\n\n```bash\nphp bin/hyperf.php actor:stats --watch\n```\n\n### 获取详细统计\n\n```php\n$status = $actorSystem-\u003egetStatus();\n// 返回：\n// [\n//     'started' =\u003e true,\n//     'actors' =\u003e 10,\n//     'worker_processes' =\u003e 4,\n//     'memory_usage' =\u003e 52428800,\n//     'peak_memory' =\u003e 67108864,\n// ]\n```\n\n## 性能优化\n\n### 配置优化\n\n```php\n// config/autoload/actor.php\nreturn [\n    'worker_processes' =\u003e 8,        // 增加工作进程\n    'batch_size' =\u003e 200,           // 提高批处理大小\n    'mailbox' =\u003e [\n        'capacity' =\u003e 2000,        // 增加邮箱容量\n    ],\n];\n```\n\n### 内存管理\n\n```php\n// 设置内存限制\n'memory' =\u003e [\n    'max_memory' =\u003e 1024 * 1024 * 1024,  // 1GB\n    'max_system_memory' =\u003e 2048 * 1024 * 1024,  // 2GB\n],\n```\n\n### 批处理优化\n\n```php\n// 批量发送消息\n$messages = [\n    new Message('type1', $data1),\n    new Message('type2', $data2),\n    // ...\n];\n$router-\u003erouteBatch($messages);\n```\n\n## 故障处理\n\n### 重启策略\n\n```php\n'supervision' =\u003e [\n    'restart_strategy' =\u003e 'one_for_one',  // 重启策略\n    'max_restarts' =\u003e 3,                  // 最大重启次数\n    'restart_window' =\u003e 60,               // 重启时间窗口\n],\n```\n\n### 错误处理\n\n```php\nclass MyActor extends AbstractActor\n{\n    public function receive(MessageInterface $message): mixed\n    {\n        try {\n            // 处理消息\n            return $this-\u003eprocessMessage($message);\n        } catch (\\Throwable $e) {\n            $this-\u003elogger-\u003eerror(\"Error processing message: \" . $e-\u003egetMessage());\n            return ['error' =\u003e 'Processing failed'];\n        }\n    }\n}\n```\n\n## 扩展开发\n\n### 自定义邮箱\n\n```php\nclass CustomMailbox implements MailboxInterface\n{\n    // 实现接口方法\n}\n```\n\n### 自定义消息路由\n\n```php\nclass CustomRouter extends MessageRouter\n{\n    public function route(MessageInterface $message): void\n    {\n        // 自定义路由逻辑\n        parent::route($message);\n    }\n}\n```\n\n## 最佳实践\n\n### 1. Actor设计原则\n\n- **单一职责**: 每个Actor只负责一个明确的功能\n- **无状态共享**: 避免Actor间直接共享状态\n- **异步通信**: 使用消息传递而非直接调用\n\n### 2. 消息设计\n\n- **幂等性**: 重复处理相同消息应该产生相同结果\n- **版本控制**: 为消息类型添加版本信息\n- **错误处理**: 总是处理消息处理失败的情况\n\n### 3. 性能优化\n\n- **批处理**: 尽可能批量处理消息\n- **连接池**: 重用数据库连接等资源\n- **缓存**: 合理使用缓存减少计算\n\n### 4. 监控告警\n\n- **关键指标**: 监控Actor数量、消息处理速度、内存使用\n- **告警阈值**: 设置合理的告警阈值\n- **日志记录**: 记录关键操作和错误信息\n\n## 故障排除\n\n### 常见问题\n\n1. **内存泄漏**\n   - 检查Actor状态是否正确清理\n   - 确认消息处理完成后资源释放\n\n2. **消息堆积**\n   - 增加工作进程数量\n   - 优化消息处理逻辑\n   - 检查邮箱容量设置\n\n3. **Actor崩溃**\n   - 查看错误日志\n   - 检查重启策略配置\n   - 确认消息格式正确\n\n### 调试技巧\n\n```php\n// 启用详细日志\n'logging' =\u003e [\n    'level' =\u003e 'debug',\n    'verbose' =\u003e true,\n],\n\n// 启用消息追踪\n'performance' =\u003e [\n    'message_tracing' =\u003e true,\n],\n```\n\n## 贡献\n\n欢迎提交问题和改进建议到 [GitHub Issues](https://github.com/lphkxd/hyperf-plus/issues)\n\n## 许可证\n\nMIT License ","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperf-plus%2Factor","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhyperf-plus%2Factor","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhyperf-plus%2Factor/lists"}