springboot实现图片上传至服务器本地保存

在实际开发中，将用户上传的图片保存到服务器本地，是最常见的需求之一。下面就来完整梳理一下基于 Spring Boot 的实现流程——从静态资源映射配置，到数据访问层、服务层，再到控制器封装，每一步都会附上代码和关键细节。

先看一个基础环节：如何让上传后的图片能够被前端访问到？这就需要配置一个映射路径，把本地磁盘上的某个文件夹，映射成 /uploads/a vatar/** 这样的 URL 路径。比如下面的配置类，设定本地存储路径为 F:\aaa，访问时通过 /uploads/a vatar/ 开头来获取文件。

package com.example.demo.config;

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

import ja va.nio.file.Path;
import ja va.nio.file.Paths;

@Configuration
public class WebConfig implements WebMvcConfigurer {

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        Path uploadPath = Paths.get("F:", "aaa");
        registry.addResourceHandler("/uploads/a vatar/**")
                .addResourceLocations(uploadPath.toUri().toString());
    }
}

数据访问层：定义 Mapper 和 SQL

接着需要编写一个用于插入用户信息的 Mapper。这里定义了一个 UserMapper 接口，通过注解参数直接传入 userId、userName、userGender 和 userA vatar 四个字段。

package com.example.demo.mapper;

import com.example.demo.pojo.Member;
import com.example.demo.pojo.MemberQuery;
import org.apache.ibatis.annotations.Mapper;
import org.apache.ibatis.annotations.Param;

import ja va.util.List;

@Mapper
public interface UserMapper {
    
     Integer insertUserProfile(
             @Param("userId") Integer userId,
             @Param("userName") String userName,
             @Param("userGender") String userGender,
             @Param("userA vatar") String userA vatar
     );
}

对应的 XML 映射文件采用动态 SQL 处理——字段非空时才插入，这样在面对不同用户填写情况时能灵活适配。

    INSERT INTO t_user
    
        user_id,
        
            user_name,
        
        
            user_gender,
        
        
            user_a vatar,
        
    
    
        #{userId},
        
            #{userName},
        
        
            #{userGender},
        
        
            #{userA vatar},
        
    

服务层：接口定义与核心实现

Service 层接口只暴露一个上传头像的方法：uploadUserA vatarBase64，传入 base64 格式的头像数据，返回上传结果。

package com.example.demo.service;

import com.example.demo.common.PageResult;
import com.example.demo.common.UploadImageResult;
import com.example.demo.pojo.Member;
import com.example.demo.pojo.MemberQuery;
import com.example.demo.pojo.UserA vatarBase64Request;
import org.springframework.web.multipart.MultipartFile;

public interface UserService {
    UploadImageResult uploadUserA vatarBase64(UserA vatarBase64Request request);
}

真正的业务逻辑集中在 UserServiceImpl 中。核心流程分为三步：解析 base64 图片数据、保存文件到本地、将用户信息写入数据库。先看解析方法 parseBase64Image——它从 data:image/ 前缀中提取 MIME 类型并验证图片格式，仅允许 jpg、jpeg、png、gif、webp 这几种常见格式。解析完成后返回一个包含文件扩展名和字节数组的内部类对象。

保存到本地时，用 UUID 生成唯一文件名，避免冲突。文件写入前先确保目录存在（Files.createDirectories），然后写入字节。保存成功后，返回相对路径 /uploads/a vatar/ 加上文件名，后续直接存入数据库。

数据库写入部分由 sa veUserProfile 方法完成：如果用户已存在则更新，否则插入。同时做了一些参数校验——用户名、性别、头像至少要传一个，否则直接抛异常。

package com.example.demo.service.impl;

import com.example.demo.common.PageResult;
import com.example.demo.common.UploadImageResult;
import com.example.demo.mapper.UserMapper;
import com.example.demo.pojo.Member;
import com.example.demo.pojo.MemberQuery;
import com.example.demo.pojo.UserA vatarBase64Request;
import com.example.demo.service.UserService;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.stereotype.Service;
import org.springframework.util.StringUtils;
import org.springframework.web.multipart.MultipartFile;

import ja va.io.IOException;
import ja va.nio.file.Files;
import ja va.nio.file.Path;
import ja va.nio.file.Paths;
import ja va.util.Base64;
import ja va.util.List;
import ja va.util.Locale;
import ja va.util.Set;
import ja va.util.UUID;

@Service
public class UserServiceImpl implements UserService {

    private static final Set ALLOWED_IMAGE_EXTENSIONS = Set.of("jpg", "jpeg", "png", "gif", "webp");

    @Autowired
    private UserMapper userMapper;

    @Override
    public PageResult getUserList(MemberQuery query) {
        MemberQuery safeQuery = query == null ? new MemberQuery() : query;
        int safeIndex = (safeQuery.getIndex() == null || safeQuery.getIndex() < 1) ? 1 : safeQuery.getIndex();
        int safePageSize = (safeQuery.getPageSize() == null || safeQuery.getPageSize() < 1) ? 10 : safeQuery.getPageSize();
        int offset = (safeIndex - 1) * safePageSize;
        List users = userMapper.selectUserList(safeQuery, offset, safePageSize);
        Long total = userMapper.selectUserCount(safeQuery);
        return new PageResult<>(users, total, safeIndex, safePageSize);
    }

    

    @Override
    public UploadImageResult uploadUserA vatarBase64(UserA vatarBase64Request request) {
        if (request == null) {
            throw new IllegalArgumentException("请求参数不能为空");
        }
        Integer userId = request.getUserId();
        String userName = request.getUserName();
        String userGender = request.getUserGender();
        String userA vatar = request.getUserA vatar();

        if (userId == null) {
            throw new IllegalArgumentException("用户id不能为空");
        }
        String a vatarPath = null;
        if (StringUtils.hasText(userA vatar)) {
            Base64Image base64Image = parseBase64Image(userA vatar);
            String fileName = UUID.randomUUID() + "." + base64Image.extension;
            Path uploadDir = Paths.get("F:", "aaa");
            Path targetPath = uploadDir.resolve(fileName);

            try {
                Files.createDirectories(uploadDir);
                Files.write(targetPath, base64Image.bytes);
            } catch (IOException e) {
                throw new RuntimeException("图片保存失败", e);
            }

            a vatarPath = "/uploads/a vatar/" + fileName;
        }

        return sa veUserProfile(userId, userName, userGender, a vatarPath);
    }

    private UploadImageResult sa veUserProfile(Integer userId, String userName, String userGender, String userA vatar) {
        if (!StringUtils.hasText(userName) && !StringUtils.hasText(userGender) && !StringUtils.hasText(userA vatar)) {
            throw new IllegalArgumentException("用户名称、用户性别、用户头像至少传一个");
        }

        Integer exists = userMapper.selectUserById(userId);
        Integer affectedRows;
        if (exists != null && exists > 0) {
            affectedRows = userMapper.updateUserProfile(userId, userName, userGender, userA vatar);
        } else {
            affectedRows = userMapper.insertUserProfile(userId, userName, userGender, userA vatar);
        }

        if (affectedRows == null || affectedRows == 0) {
            throw new IllegalArgumentException("用户信息保存失败");
        }
        return new UploadImageResult(userId, userName, userGender, userA vatar);
    }

    private String getFileExtension(String originalFilename) {
        String filename = StringUtils.cleanPath(originalFilename == null ? "" : originalFilename);
        int dotIndex = filename.lastIndexOf('.');
        if (dotIndex < 0 || dotIndex == filename.length() - 1) {
            throw new IllegalArgumentException("图片文件后缀不能为空");
        }
        return filename.substring(dotIndex + 1).toLowerCase(Locale.ROOT);
    }

    private Base64Image parseBase64Image(String userA vatar) {
        String base64Content = userA vatar.trim();
        String extension = "png";

        if (base64Content.startsWith("data:image/")) {
            int mimeEndIndex = base64Content.indexOf(";base64,");
            if (mimeEndIndex < 0) {
                throw new IllegalArgumentException("图片base64格式错误");
            }
            extension = base64Content.substring("data:image/".length(), mimeEndIndex).toLowerCase(Locale.ROOT);
            if ("jpg".equals(extension)) {
                extension = "jpeg";
            }
            base64Content = base64Content.substring(mimeEndIndex + ";base64,".length());
        }

        if (!ALLOWED_IMAGE_EXTENSIONS.contains(extension)) {
            throw new IllegalArgumentException("只支持 jpg、jpeg、png、gif、webp 格式图片");
        }

        try {
            byte[] bytes = Base64.getDecoder().decode(base64Content);
            if (bytes.length == 0) {
                throw new IllegalArgumentException("用户头像base64不能为空");
            }
            return new Base64Image(extension, bytes);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("图片base64解析失败");
        }
    }

    private static class Base64Image {
        private final String extension;
        private final byte[] bytes;

        private Base64Image(String extension, byte[] bytes) {
            this.extension = extension;
            this.bytes = bytes;
        }
    }
}

控制器层：接收请求并返回统一响应

最后是 Controller。这里定义一个 uploadA vatarBase64 的 POST 接口，接收 JSON 请求体，调用 Service 层方法后封装成统一响应格式。异常处理分几种情况：参数校验不合法返回 400，运行时异常返回 500，成功则返回 200 和数据。

@PostMapping("/uploadA vatarBase64")
public org.springframework.http.ResponseEntity> uploadA vatarBase64(
        @RequestBody UserA vatarBase64Request request
) {
    try {
        UploadImageResult result = userService.uploadUserA vatarBase64(request);
        return org.springframework.http.ResponseEntity.ok(
                ResponseEntity.success(200, result, "用户信息保存成功")
        );
    } catch (IllegalArgumentException e) {
        return org.springframework.http.ResponseEntity
                .status(HttpStatus.BAD_REQUEST)
                .body(ResponseEntity.fail(400, e.getMessage()));
    } catch (RuntimeException e) {
        return org.springframework.http.ResponseEntity
                .status(HttpStatus.INTERNAL_SERVER_ERROR)
                .body(ResponseEntity.fail(500, e.getMessage()));
    }
}

整个流程从配置到接口调用，环环相扣。唯一需要特别留意的就是 base64 解析时的格式校验——实际生产环境中可能还会遇到 data URI 不标准的情况，建议根据具体场景再做增强。此外，文件保存路径建议抽取到配置文件中，不要在代码里硬编码。这些细节做好，本地上传头像的功能就能稳定运行了。