project-structure.md

项目结构规范

标准目录结构

├── app/
│   ├── Controller/       # HTTP 控制器层
│   │   ├── IndexController.php
│   │   └── Api/          # API 控制器子目录
│   ├── Model/            # ORM 模型层
│   ├── Service/          # 业务逻辑层（推荐）
│   ├── Request/          # 请求 DTO / 表单验证
│   │   └── UserCreateRequest.php
│   ├── Exception/        # 自定义异常
│   │   └── Handler/     # 异常处理器
│   │       └── AppExceptionHandler.php
│   ├── Middleware/      # 中间件
│   ├── Annotation/      # 自定义注解
│   ├── Event/           # 事件类
│   ├── Listener/        # 事件监听器
│   ├── Process/         # 自定义进程
│   ├── Command/         # 命令行命令
│   └── Kernel.php       # HTTP Kernel（可选）
├── config/
│   ├── autoload/        # 业务配置（优先级最高）
│   │   ├── databases.php
│   │   ├── middlewares.php
│   │   ├── annotations.php
│   │   ├── services.php
│   │   └── ...（按功能分文件）
│   ├── config.php       # 框架核心配置（一般不改）
│   ├── container.php    # 容器配置
│   ├── dependencies.php # 依赖注入配置
│   └── dev.php / prod.php
├── migrations/          # 数据库迁移
├── test/                # 单元测试
└── composer.json

分层原则

• Controller：只做参数校验、调用 Service、组装响应。禁止写业务逻辑。
• Service：纯业务逻辑，无 HTTP 框架依赖。可单测。
• Model：数据模型，只做数据读写。
• Request：表单请求验证，继承 Hyperf\Validation\Request\FormRequest。
• Exception Handler：统一错误处理，不要在 Controller 里 try/catch。

文件命名

类型	规范	示例
Controller	PascalCase + Controller 后缀	UserController.php
Model	PascalCase，单数名词	User.php
Service	PascalCase + Service 后缀	UserService.php
Middleware	PascalCase + Middleware 后缀	CorsMiddleware.php
Request	PascalCase + Request 后缀	UserCreateRequest.php
Annotation	PascalCase + Annotation 前缀	LoginTokenAnnotation
Command	PascalCase + Command 后缀	InitDbCommand.php
Listener	PascalCase + Listener 后缀	UserLoginListener.php
Event	PascalCase + Event 后缀	UserLoginEvent.php

namespace 规范

<?php
declare(strict_types=1);

namespace App\Controller;        // 顶级 namespace 为 App
namespace App\Controller\Api;
namespace App\Model;
namespace App\Service;
namespace App\Request;
namespace App\Middleware;