PHP Swoole 项目结构

本文目录导读：

1. 方案一：基于 Hyperf 框架（推荐生产环境）
2. 方案二：轻量级原生 Swoole 结构（适合小型项目或学习）
3. 关键目录与文件解析（基于 Hyperf）
4. 骨架安装命令
5. 重要注意事项

一个标准的 PHP Swoole 项目需要根据业务场景（HTTP 服务、WebSocket、TCP/UDP 服务、微服务等）来组织，这里提供一个面向生产环境、基于 Hyperf（最流行的 Swoole 框架）风格的目录结构，以及一个轻量级原生 Swoole 的参考结构。

基于 Hyperf 框架（推荐生产环境）

Hyperf 是目前最完善的 Swoole 框架，自带协程、依赖注入、注解等功能，结构清晰，适合中大型项目。

project-root/
├── app/                          # 应用核心目录（业务代码）
│   ├── Aspect/                   # 面向切面编程（AOP）类，如日志、缓存切面
│   ├── Command/                  # 自定义命令行脚本（php bin/hyperf.php test:demo）
│   ├── Constants/                # 常量定义类（如错误码）
│   ├── Controller/               # HTTP 控制器
│   │   ├── Admin/                # 后台模块
│   │   │   └── UserController.php
│   │   ├── Api/                  # 对外 API 或移动端接口
│   │   │   └── IndexController.php
│   │   └── WebSocket/            # WebSocket 控制器
│   │       └── ChatController.php
│   ├── Exception/                # 自定义异常及处理类
│   │   └── Handler/
│   ├── JsonRpc/                  # JSON-RPC 服务（微服务）控制器
│   ├── Listener/                 # 监听器（如 Swoole 事件监听）
│   ├── Middleware/               # HTTP 中间件（如用户鉴权、跨域）
│   ├── Model/                    # Eloquent ORM 模型
│   │   └── Entity/               # 数据表实体类
│   ├── Process/                  # 自定义自定义进程（Swoole Process）
│   ├── Service/                  # 服务层（处理核心业务逻辑）
│   │   └── UserService.php
│   └── Task/                     # 任务队列处理类（投递异步任务）
├── config/                       # 应用配置目录
│   ├── autoload/                 # Hyperf 自动扫描的配置文件
│   │   ├── dependencies.php      # 依赖注入映射
│   │   ├── exceptions.php        # 异常处理映射
│   │   ├── middlewares.php       # 全局、模块中间件
│   │   ├── processes.php         # 自定义进程注册
│   │   └── server.php            # Swoole Server 端口及协议配置
│   ├── config.php                # 基础配置（环境变量读取）
│   ├── container.php             # 依赖注入容器定义
│   └── routes.php                # 路由定义文件（HTTP 路由）
├── migrations/                   # 数据库迁移文件（如 Phinx）
├── storage/                      # 运行时文件
│   ├── logs/                     # 日志文件存储
│   ├── cache/                    # 缓存文件
│   └── upload/                   # 上传文件目录
├── test/                         # 单元测试和集成测试
├── bin/                          # 可执行脚本
│   └── hyperf.php                # 命令行启动脚本（启动：php bin/hyperf.php start）
├── composer.json                 # 依赖管理
├── .env                          # 环境配置文件
└── deploy/                       # Docker 及部署相关文件

特点：

• 强约定：路由、控制器、中间件有固定位置，团队协作成本低。
• 注解丰富：支持 @RequestMapping、@Inject 等，代码整洁。
• 协程安全：内置连接池（数据库、Redis）。

轻量级原生 Swoole 结构（适合小型项目或学习）

不引入重型框架,自行管理 Swoole 常驻内存及生命周期，适合对性能要求极高、只想用 Swoole 特性（异步任务、WebSocket）的项目。

project-root/
├── app/
│   ├── Controllers/              # 业务逻辑（控制器）
│   │   └── UserController.php
│   ├── Services/                 # 业务服务层
│   │   └── UserService.php
│   ├── Models/                   # 数据库模型（如 Medoo / Eloquent）
│   │   └── User.php
│   ├── Core/                     # 核心基础组件
│   │   ├── Application.php       # 应用主核心（解析路由、分发请求）
│   │   ├── Container.php         # 简易 依赖注入容器（辅助）
│   │   ├── Router.php            # 简单路由解析器
│   │   └── HttpServer.php        # 封装 Swoole HttpServer 启动类
├── config/                       # 配置目录
│   ├── server.php                # Swoole 配置（worker_num、监听端口、task_worker）
│   ├── database.php              # MySQL/Redis 配置
│   └── app.php                   # 应用配置
├── public/                       # Web 根目录（静态资源、入口）
│   └── index.php                 # （仅用于 PHP-FPM 模式调试，Swoole 模式可不经过）
├── runtime/                      # 运行时缓存与日志
│   ├── logs/
│   └── cache/
├── bin/
│   └── server.php                # CLI 入口（启动/停止 Swoole：php bin/server.php start）
├── vendor/                       # composer 依赖
└── composer.json

核心入口（bin/server.php）示例逻辑：

use Swoole\Http\Server;
// 加载配置...
$server = new Server('0.0.0.0', 9501);
$server->set([
    'worker_num' => 4,               // 业务进程
    'task_worker_num' => 2,          // 异步任务进程
    'enable_coroutine' => true,      // 开启协程
]);
$server->on('request', function ($request, $response) {
    // 简单的路由分发
    $router = new Router();
    $handler = $router->dispatch($request->server['request_uri']);
    // 调用控制器并输出
});
$server->on('task', ...);  // 处理异步任务
$server->start();

关键目录与文件解析（基于 Hyperf）

1. config/autoload/server.php：这里定义了 Swoole 的 Server 监听，你可以配置 HTTP 服务（端口 9501）和 WebSocket 服务（端口 9502），以及 mode、sock_type。
2. app/Controller：控制器直接接收 Psr\Http\Message\ServerRequestInterface。

   #[Controller(prefix: "/user")]
   class UserController {
       #[GetMapping("/info")] 
       public function info(int $id) {
           // Swoole 下，这里可以直接使用协程 MySQL 查询，不会阻塞。
           return $this->userService->getInfo($id);
       }
   }

3. app/Task：Swoole 传统的 task 投递逻辑，如果使用 Hyperf，通常使用 AsyncQueue 组件替代，但 Task 仍存在。
4. config/routes.php：如果不想用注解路由，可以在这里集中管理路由规则。

骨架安装命令

如果你从零开始,建议先装好骨架再修改：

# 安装 Hyperf 骨架（自动生成上述结构）
composer create-project hyperf/hyperf-skeleton my-project
cd my-project
cp .env.example .env
composer install
# 启动 Swoole 服务
php bin/hyperf.php start

重要注意事项

• 常驻内存：Swoole Worker 进程常驻，这意味着你需要避免使用全局变量存储请求数据（会串数据），项目结构中一定要有清晰的 Context（上下文）管理类，或使用协程安全容器。
• 连接池：数据库和 Redis 连接必须使用连接池（Hyperf 自带），否则在协程下会耗尽连接。
• 日志：使用 Writer 类或 Monolog 将日志写入 storage/logs/，不建议使用 echo 输出到终端。
• 进程管理：Swoole 的 Task 和 Process 需要单独配置，确保 config 中有对应定义，不能直接在控制器里 new Process，需要注册到 server.php 配置中。

• 如果是正式项目，建议使用 方案一（Hyperf 骨架），因为其组件化、协程安全和团队协作规范。
• 如果是快速原型或对体积极度敏感，可以使用 方案二（原生结构），但需要自己处理协程安全、路由和中间件逻辑。

直接把代码放入上述结构对应的目录,然后通过 Composer 的自动加载实现类映射即可。