Laravel API从storage获取图片返回前端及show函数最佳实践

现有实现上下文 #

当前开发的Laravel API项目已创建destinations与destination_images两张表，二者为一对多关联关系。存储目的地数据时同步接收上传图片，图片统一存入Storage::disk('public')磁盘，生成随机文件名后将文件名写入destination_images表，现有store函数实现代码如下：

public function store(Request $request)
{
    $validator = Validator::make($request->all(), [
        'name' => 'required|string|max:100',
        'description' => 'nullable|string',
        'fileSource' => 'required'
    ]);

    if ($validator->fails()) {
        $errors = $validator->errors();
        return response()->json($errors);
    }

    $destination = Destination::create([
        'name' => $request->name,
        'description' => $request->description
    ]);

    foreach ($request->fileSource as $img) {
        $extension = explode('/', explode(':', substr($img, 0, strpos($img, ';')))[1])[1];
        $replace = substr($img, 0, strpos($img, ',')+1);
        $image = str_replace($replace, '', $img);
        $image = str_replace(' ', '+', $image);
        $imageName = 'destination-' . Str::random(10).'.'.$extension;
        Storage::disk('public')->put($imageName, base64_decode($image));
        DestinationImage::create([
            'destination_id' => $destination->id,
            'img' => $imageName
        ]);
    }

    return response()->json('Destination Created Successfully');
}

待解决问题 #

• 如何正确实现show函数？
• 是否可以直接使用数据库查询到的图片名称，由前端拼接访问链接？
• 该业务流程的最佳实践方案是什么？

具体实现方案 #

1. show函数标准实现 #

首先提前在Destination模型中定义一对多关联：

// app/Models/Destination.php
public function images()
{
    return $this->hasMany(DestinationImage::class);
}

show函数实现时要注意预加载关联避免N+1查询，直接在接口层返回完整可访问的图片地址，不需要前端拼接：

public function show($id)
{
    // 查不到数据自动返回404响应，预加载关联图片
    $destination = Destination::with('images')->findOrFail($id);
    
    // 为每张图片生成可访问的完整URL
    $destination->images->transform(function ($image) {
        $image->access_url = Storage::disk('public')->url($image->img);
        return $image;
    });

    return response()->json([
        'code' => 0,
        'data' => $destination
    ]);
}

2. 前端拼接链接的可行性 #

不推荐让前端自行拼接图片访问链接：

• 后续如果切换存储驱动（比如从本地public磁盘切换到云对象存储）、调整存储路径前缀，所有前端拼接的链接都会全部失效，必须修改前端代码发版才能修复，维护成本极高
• 后端统一返回URL可以无缝兼容后续的权限校验、临时访问链接、图片缩放裁剪等扩展需求，不需要调整前端逻辑
  如果是临时测试、确定存储策略永久不变的内部小项目可以临时用这种方式，正式生产环境禁止这么做。

3. 业务流程最佳实践 #

• 提前配置存储访问软链接：部署项目时必须执行php artisan storage:link命令，将storage/app/public目录软链接到public/storage路径，否则public磁盘下的文件无法通过HTTP访问。建议把该命令加到项目部署脚本中，避免每次部署覆盖public目录后软链接失效。
• 补全上传校验逻辑：现有代码没有对上传的base64图片做格式、大小校验，也没有处理base64解析失败的异常，很容易被恶意上传非法文件占满服务器磁盘。优化后的校验规则参考：

$validator = Validator::make($request->all(), [
    'name' => 'required|string|max:100',
    'description' => 'nullable|string',
    'fileSource' => 'required|array',
    'fileSource.*' => 'required|string|starts_with:data:image/|max:5120' // 单张图片最大限制5M
]);

• 用数据库事务保证数据一致性：现有代码如果中途某张图片存储失败，会出现目的地主数据已入库、部分图片缺失的脏数据问题。需要把创建主数据、写入图片记录、存储文件的逻辑全部包裹在数据库事务中，任意步骤执行失败则全部回滚：

DB::transaction(function () use ($request, &$destination) {
    $destination = Destination::create([
        'name' => $request->name,
        'description' => $request->description
    ]);
    // 原有循环解析、存储图片的逻辑放在事务内
});

• 优化文件存储路径：不要把所有图片都存在public磁盘根目录，建议按日期分目录存储，避免单目录下文件数量过多降低文件系统读写性能，比如文件名可以调整为'destination/' . date('Y/m/d') . '/' . Str::random(10).'.'.$extension。
• 增加异常捕获：base64解码、文件写入的逻辑要加异常捕获，出现错误时返回明确的业务提示，不要直接抛出500服务端错误给前端。
• 统一返回格式：建议使用Laravel自带的JsonResource做接口输出格式化，后续字段调整、结构变更时不需要修改每个接口的内部逻辑，维护性更强。

内容的提问来源于stack exchange，提问作者Osama Amr