控制器类名必须以controller结尾，如usercontroller；命名空间须与文件路径严格一致；prefix仅作字符串拼接，方法path应为不带前导斜杠的相对路径；方法名用语义动词如list()、create()，禁用getuser()等http动词式命名。
控制器类名必须以 Controller 结尾
Hyperf 会通过类名后缀识别控制器，这是 #[AutoController] 和路由扫描机制的硬性约定。如果定义了 class User 或 class UserControllerHandler，即使加了 #[Controller] 注解，AutoController 模式也不会生效，且部分扫描逻辑可能跳过。
- ✅ 正确命名：
UserController、OrderExportController、AdminDashboardController - ❌ 错误命名：
User（缺后缀）、UsersController（复数形式不推荐，且易与 Laravel 风格混淆）、UserCtrl（非标准缩写） - 命名空间需与路径严格对应：例如
App\Controller\UserController必须位于app/Controller/UserController.php
路由前缀和方法路径要区分层级语义
Hyperf 不强制要求控制器名和路由前缀一致，但保持语义对齐能显著降低维护成本。比如 UserController 对应 #[Controller(prefix: '/users')]，而不是 /api/v1/member 这类跨域/跨业务的路径。
-
prefix是路径前缀，不是资源名映射 —— 它只做字符串拼接，不参与逻辑推导 - 方法级
path应为相对路径，且不带前导斜杠：#[GetMapping(path: 'list')]→ 最终是/users/list；若写成'/list'，多数情况下会被 normalize 掉双斜杠，但风格不统一易引发协作歧义 - 避免在 prefix 中混入版本号或环境标识（如
/api-dev/v2），版本应由独立中间件或命名空间控制
方法命名优先用语义动词，而非 HTTP 动词
不要把 getUsers、postUser 当作方法名 —— 这既违反 PSR-2，也割裂了 RESTful 语义与实现细节。Hyperf 的注解已声明 HTTP 方法，方法名应表达“做什么”，而不是“怎么发”。
- ✅ 推荐：
list()、view(int $id)、create()、update(int $id)、remove(int $id) - ❌ 避免：
getUser()（GET 已由#[GetMapping]声明）、deleteUser()（DELETE 同理）、handle()（语义模糊） - 多个相似操作可用下划线分隔：
listByStatus()、exportAsCsv()，但需确保该方法职责单一
大小写与下划线：全部小写 + 驼峰，禁用中划线和下划线分隔
Hyperf 本身不校验方法名格式，但结合 PSR-1/PSR-12 和团队协作实际，命名需兼顾 IDE 支持、静态分析（如 PHPStan）和自动生成文档（如 Swagger）的兼容性。
- 类名用 PascalCase：
UserImportController - 方法名用 camelCase：
syncWithThirdParty()、retryFailedJobs() - 绝对不要用中划线（
user-import-controller）或下划线（user_import_controller）命名类 —— PSR-4 自动加载器无法解析 - 路由 path 字符串允许下划线（如
path: 'export_csv'），但仅限于 URL 可读性优化，不建议用于方法名
namespace 没更新 composer.json 的 psr-4 映射，会导致注解扫描完全失效，且无明确报错。
