Service层不可直接调用think\File::move()，须封装为UploadService统一处理验证、存储、日志、多磁盘适配等全流程，并强制try-catch捕获异常、结构化记录错误。
Service 层不能直接调用 think\File::move()
ThinkPHP 的文件上传核心逻辑在 think\File 类里，但它的 move() 方法是同步、无事件、无容器管理的纯函数式调用。Service 层若直接 new think\File 或接收原始 $file 对象后调 move()，会破坏依赖注入原则，也绕过所有生命周期控制。更关键的是：框架内部创建 think\File 实例是硬编码的，无法被容器替换或 AOP 拦截——你重写类、监听事件、改配置都无效。
必须把上传动作封装成独立 Service，并统一入口
上传不是“存个文件”那么简单，它含验证、路径生成、权限检查、失败回滚、日志埋点、多磁盘适配（如 OSS）、甚至异步转存等环节。这些必须收口到一个 Service 里，比如 UploadService：
- 在
app/service/UploadService.php中定义类，确保已注册 PSR-4 命名空间（"app\service\": "app/service/"+composer dump-autoload） - 构造函数只接收配置项或依赖（如
Filesystem实例），不接收原始$file；上传操作由方法参数传入 - 方法签名建议为：
public function store(\think\File $file, array $options = []): array，返回结构化结果（['url' => '', 'path' => '', 'size' => 0]） - 所有
$file->validate()和$file->move()必须包裹在 try-catch 内，且Log::error()要写在 catch 块里，否则上传失败时日志根本不会落盘
上传失败时的日志和异常必须显式捕获并结构化
常见错误是把日志写在 try 外面，或用 Log::record() 这种低级别方法——TP6+ 默认不记录 notice/debug 级别，而 $file->validate() 失败返回 false 时只抛 warning，会被静默吞掉。实操要点：
- 验证失败要主动 throw 异常：
if (!$file->validate(['size' => 1024 * 1024, 'ext' => 'jpg,png'])) { throw new ValidateException($file->getError()); } - move() 失败的异常必须 catch：
} catch (\think\exception\FileException $e) { Log::error('move failed', ['original_name' => $file->getOriginalName(), 'error' => $e->getMessage()]); throw $e; } - 别依赖
Log::write()返回值判断是否成功——它只表示进队列，真正写入靠请求结束时的Log::save()，上传失败时请求可能已中断
上传路径和磁盘策略要在 Service 内部解耦
硬编码 Filesystem::disk('public') 会让 Service 无法复用于 OSS、COS 或 SFTP 场景。正确做法是把磁盘名作为 $options['disk'] 传入，再在 Service 内部做判断：
立即学习“PHP免费学习笔记（深入）”；
- 支持字符串磁盘名：
$disk = Filesystem::disk($options['disk'] ?? 'public') - 支持闭包动态构建磁盘（如按用户 ID 切桶）：
if (is_callable($options['disk'])) { $disk = $options['disk'](); } - 路径生成不要拼接字符串，用
Str::random(16)+date('Y/m/d')构建唯一子目录，避免同名覆盖 - 如果用了
think\facade\Filesystem，注意它底层仍是调think\File::move()，钩子位置没变，别误以为 facade 自带日志能力
上传逻辑一旦脱离控制器进入 Service，就不再是“一次性的业务代码”，而是需要事务感知、可测试、可降级、可监控的基础设施组件。最容易被忽略的点是：上传失败时的上下文丢失——没有结构化 error 日志，就没有排查依据；没有统一入口，就无法加熔断、限流或灰度开关。
