项目结构介绍
本文档详细解析 Viswoole 项目的目录结构，帮助开发者理解各模块的职责与边界。
目录总览
text
viswoole/
├── app/ # 应用层 — 业务代码存放目录
├── config/ # 配置层 — 所有配置文件
│ └── route/ # 路由注册文件
├── framework/ # 框架层 — Viswoole 核心源码（独立 Composer 包）
│ └── src/ # 框架源码入口
├── public/ # 公共资源 — 可公开访问的静态文件
├── runtime/ # 运行时 — 日志、缓存等动态生成文件
├── composer.json # 项目依赖声明
├── viswoole # CLI 入口文件
└── watch # 文件监控热重载脚本应用层 (app/)
应用层是开发者编写业务代码的主要区域，遵循 PSR-4 自动加载规范（命名空间前缀为 App\）。
text
app/
├── Controller/ # 控制器目录
│ └── Example.php # 示例控制器
├── Interface/ # 数据传输对象接口（DTO）
│ ├── UserInfo.php # 用户信息接口
│ └── Gender.php # 枚举/常量定义
├── Request.php # 自定义请求对象（可选）
└── Response.php # 自定义响应对象（可选）Controller（控制器）
控制器负责处理 HTTP 请求并返回响应。Viswoole 支持通过 注解驱动 的方式自动注册路由：
php
<?php
declare (strict_types=1);
namespace App\Controller;
use Viswoole\Router\Annotation\{AutoController, RouteMapping};
use Viswoole\HttpServer\AutoInject\InjectGet;
#[AutoController]
class Example
{
#[RouteMapping(method: 'GET', paths: '/hello')]
public function hello(#[InjectGet] string $name = 'Viswoole'): string
{
return "Hello, {$name}!";
}
}Interface（数据传输对象）
Interface 目录用于定义数据传输对象的接口或枚举，可与参数注入配合使用，实现请求体的自动反序列化与校验：
php
<?php
declare (strict_types=1);
namespace App\Interface;
enum Gender
{
case MAN;
case WOMAN;
}
class UserInfo
{
public string $name;
public Gender $gender;
}配置层 (config/)
配置层集中管理所有应用和框架的配置项，采用 PHP 返回数组的方式组织：
text
config/
├── app.php # 应用基础配置（时区、调试模式、服务注册）
├── server.php # Swoole 服务配置（端口、进程数、协程设置）
├── router.php # 路由全局配置
├── database.php # 数据库连接配置
├── cache.php # 缓存驱动配置
├── log.php # 日志系统配置
├── listens.php # 事件监听配置
├── lazy/ # 延迟加载配置
│ └── middleware.php # 中间件延迟加载
└── route/
└── route.php # 路由注册文件关键配置说明
server.php — 服务配置
定义 Swoole Server 的核心参数，包括监听地址、端口、进程数、协程设置等：
php
return [
'default_start_server' => env('default_start_server', 'http'),
'servers' => [
'http' => [
'type' => \Swoole\Http\Server::class,
'construct' => [
'host' => '0.0.0.0',
'port' => 9501,
// ... 更多构造参数
],
'options' => [
// 上传文件大小限制、HTTP2 支持等
],
'events' => [
// 事件回调绑定
]
]
],
// 全局选项（worker 数量、最大协程数、日志级别等）
'options' => [...],
];app.php — 应用配置
管理应用级的基础设置，包括时区、调试模式、服务提供者和自定义命令的注册：
php
return [
'default_timezone' => env('default_timezone', 'Asia/Shanghai'),
'debug' => env('app_debug', true),
'services' => [
\Viswoole\Core\Service\TaskService::class, // 异步任务服务
],
'commands' => [] // 自定义命令注册
];route/route.php — 路由注册
所有路由在此文件中集中定义，支持闭包和控制器两种方式：
php
use Viswoole\HttpServer\Facade\Request;
use Viswoole\HttpServer\Facade\Response;
use Viswoole\Router\Facade\Router;
// 闭包路由
Router::get('/', function (Request $request, Response $response) {
return $response->html('<h1>Hello Viswoole</h1>');
});
// 兜底路由（404 处理）
Router::miss(function (Request $request, Response $response) {
return $response->status(404)->json(['code' => 404, 'msg' => 'Not Found']);
});框架层 (framework/)
框架层是 Viswoole 的核心代码，作为独立的 Composer 包（viswoole/framework）引入项目中。一般情况下无需修改此目录下的代码。
text
framework/src/
├── Core/ # 核心模块
│ ├── Container.php # IOC 依赖注入容器
│ ├── App.php # 应用引导类
│ ├── Config.php # 配置管理器
│ ├── Event.php # 事件调度器
│ ├── Coroutine.php # 协程上下文管理
│ ├── Facade.php # 门面基类
│ ├── Validate.php # 参数校验器
│ ├── Console.php # 控制台命令内核
│ ├── Server.php # 服务器管理器
│ ├── Service/ # 服务提供者与中间件服务
│ ├── Facade/ # 门面实现（App、Config、Env 等）
│ ├── Middleware/ # 内置中间件（跨域等）
│ ├── Channel/ # 连接池管理
│ ├── Validate/ # 校验规则引擎
│ └── Exception/ # 异常体系
├── HttpServer/ # HTTP 服务模块
│ ├── Request.php # 请求对象
│ ├── Response.php # 响应对象
│ ├── HttpService.php # HTTP 服务启动逻辑
│ ├── AutoInject/ # 参数自动注入（GET/POST/Header/File）
│ ├── Message/ # 消息封装（UploadedFile、Uri 等）
│ ├── Contract/ # 请求/响应接口契约
│ ├── Facade/ # 门面（Request、Response）
│ └── Validate/ # 文件上传校验规则
├── Router/ # 路由模块
│ ├── Router.php # 路由管理器
│ ├── Annotation/ # 注解定义（AutoController、RouteMapping）
│ ├── Route/ # 路由实体（Route、Group、Miss）
│ ├── ApiDoc/ # API 文档生成器
│ ├── Commands/ # 路由相关命令
│ └── Facade/ # Router 门面
├── Database/ # 数据库 ORM 模块
│ ├── Model.php # 模型基类
│ ├── BaseQuery.php # 查询构建器基类
│ ├── DbManager.php # 数据库连接管理器
│ ├── Collection/ # 集合封装
│ ├── Query/ # 查询组件（CRUD、Where、Join 等）
│ ├── Channel/ # PDO 连接池
│ └── Facade/ # DB 门面
├── Cache/ # 缓存模块
│ ├── CacheManager.php # 缓存管理器
│ ├── Driver/ # 缓存驱动（File、Redis）
│ ├── Contract/ # 缓存接口契约
│ └── Facade/ # Cache 门面
└── Log/ # 日志模块
├── LogManager.php # 日志管理器
├── Drives/ # 日志驱动（File）
├── Collector.php # 日志收集器
└── Facade/ # Log 门面公共资源目录 (public/)
存放可直接通过 Web 访问的静态文件：
text
public/
├── favicon.ico # 网站图标
└── logo.png # Logo 图片运行时目录 (runtime/)
存放程序运行期间动态生成的文件，不应纳入版本控制（已配置在 .gitignore 中）：
text
runtime/
├── sysLog.log # Swoole 系统日志
├── log/ # 应用日志
└── cache/ # 缓存文件（如使用 File 缓存驱动）入口文件
viswoole — CLI 入口
项目的命令行入口文件，所有 php viswoole ... 命令均由此文件启动：
php
#!/usr/bin/env php
<?php
declare (strict_types=1);
use Viswoole\Core\App;
ini_set('display_errors', 'on');
ini_set('memory_limit', '1G');
!defined('BASE_PATH') && define('BASE_PATH', __DIR__);
require __DIR__ . '/vendor/autoload.php';
(function () {
App::factory()->console->run();
})();watch — 文件监控脚本
基于 Shell 的文件变化监控脚本，用于开发阶段的热重载。通过 find 命令轮询检测 .php 和 .env 文件的变更，配合防抖机制自动重启 Swoole 服务。
注意事项
- 不要修改
framework/目录：框架核心代码通过 Composer 管理，直接修改会导致更新时丢失更改。如需定制功能，应通过服务提供者、中间件或事件机制进行扩展。 runtime/目录权限：确保运行 Viswoole 的用户对runtime/目录有读写权限，否则日志和缓存写入会失败。- 环境隔离：使用
.env文件区分不同环境的配置，切勿将敏感信息硬编码到config/中的 PHP 文件里。 - 命名空间规范：
app/目录下的代码统一使用App\命名空间前缀，已在composer.json中配置 PSR-4 映射。