本文目录导读：
一个标准的 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）
config/autoload/server.php：这里定义了 Swoole 的Server监听，你可以配置 HTTP 服务（端口 9501）和 WebSocket 服务（端口 9502），以及mode、sock_type。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); } }app/Task：Swoole 传统的task投递逻辑，如果使用 Hyperf，通常使用AsyncQueue组件替代，但 Task 仍存在。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 的自动加载实现类映射即可。
