Trait用于控制器鉴权可按需混入、避免深继承和胖父类，支持JWT、游客降级、IP白名单等多策略组合，且初始化时机可控，语义清晰、职责分明。
控制器鉴权不必堆砌重复逻辑，用 Trait 封装鉴权行为，既能复用又不破坏类职责。
为什么用 Trait 做鉴权而不是基类继承
基类继承容易导致“胖父类”：所有控制器被迫带上登录、角色、权限等通用逻辑，哪怕某个接口根本不需要鉴权。而 Trait 是按需混入——只在需要鉴权的控制器里 use，语义清晰，也避免深继承链。ThinkPHP 8 和 Laravel 都默认推荐这种方式，尤其适合中大型项目里“部分接口需鉴权、部分开放”的混合场景。
鉴权 Trait 的典型结构
一个轻量级鉴权 Trait 通常包含三类能力：设置主体（Principal）、校验表达式、快捷注解支持。参考 Security 插件初始化方式，可封装为：
- 提供 setAuthRole($role) 和 setAuthPermission($perm) 方法，内部自动构建 Principal 对象并调用
$this->setPrincipal() - 封装 checkRole($role) 和 checkPermission($perm) 方法，直接返回布尔值，便于在方法体内手动判断
- 配合注解使用时，Trait 不干涉注解解析器，但确保
$this->getPrincipal()可用——这点要求控制器已引入或继承了对应安全支持（如 ESD 框架需 use GetSecurity trait）
和框架注解协同工作的关键点
像 @PreAuthorize("hasRole('admin')") 这类注解，底层依赖的是控制器能拿到有效的 Principal 实例。因此 Trait 初始化必须早于注解执行时机：
- 不要在构造函数里初始化鉴权信息，因为此时 Request/Session 可能未就绪
- 推荐在控制器的 initialize() 方法（TP8）或中间件后、方法执行前完成 Principal 设置
- 若用户未登录，可设为 guest 角色 + read 权限，既保持流程通畅，又守住最小权限边界
多个鉴权需求共存时怎么处理
比如一个控制器既要支持 JWT 登录态校验，又要兼容游客读取权限，还可选配 IP 白名单。这时可拆成多个 Trait：
-
Use JwtAuthTrait：负责从 header 解析 token 并设置 Principal -
Use GuestAuthTrait：无 token 时降级为 guest 主体 -
Use IpWhitelistTrait：额外校验客户端 IP - 方法上用
@PreAuthorize("hasRole('admin') || hasPermission('read')")组合表达式，由框架统一执行
不复杂但容易忽略。
