005-SpringSecurity-Demo 配置外部文件映射

SpringSecurity-Demo 配置外部文件映射

    • 一、需求说明
    • 二、实现步骤
      • [1. 定义配置属性类(读取yml配置)](#1. 定义配置属性类(读取yml配置))
      • [2. 编写资源映射配置](#2. 编写资源映射配置)
      • [3. application.yml 配置(路径可自定义)](#3. application.yml 配置(路径可自定义))
    • 三、原理讲解(一看就懂)
    • 四、使用示例
    • 五、路径写法说明
      • [1. 相对路径](#1. 相对路径)
      • [2. Windows 绝对路径](#2. Windows 绝对路径)
      • [3. Linux 绝对路径](#3. Linux 绝对路径)
    • 六、常见问题
      • [1. 访问404](#1. 访问404)
      • [2. 不想用profile作为URL前缀](#2. 不想用profile作为URL前缀)
      • [3. 映射网络路径?](#3. 映射网络路径?)

在 Spring Boot 项目开发中,我们经常需要上传图片、文档等文件,并希望通过浏览器地址直接访问(比如头像、附件预览)。

但直接把文件存在项目内部会导致打包过大、更新不便,所以最佳实践是:文件存在外部文件夹,通过 Spring MVC 资源映射实现外网访问。

本篇博客就带你一步步实现:外部文件目录 → 浏览器在线访问,完全适配 Spring Boot 3.2.4 + JDK 21,代码可直接复制用于生产环境。


一、需求说明

我们要实现的功能非常简单实用:

  1. 把文件存在项目根目录的 ./file 文件夹(实际使用可配置其它目录)
  2. 通过地址 http://localhost:5826/profile/xxx.png 直接访问图片
  3. 路径可配置,不写死代码

二、实现步骤

代码已推送至 Gitee 仓库:springdecurity-demo

1. 定义配置属性类(读取yml配置)

专门用来读取外部配置,代码解耦、规范优雅。

java 复制代码
package com.junjiu.springboot3.config.properties;

import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.stereotype.Component;

/**
 * program: security-demo
 * ClassName: JunjiuCustomProperties
 * description:
 *
 * @author: 君九
 * @create: 2026-04-03 14:35
 * @version: 1.0
 **/
@Data
@Component
@ConfigurationProperties(prefix = "junjiu.custom")
public class JunjiuCustomProperties {

    /**
     * 外部资源存储路径
     * 例如:./file
     */
    private String resourcePath;
}

2. 编写资源映射配置

继承 WebMvcConfigurer,重写 addResourceHandlers 实现外部文件夹映射到URL。

java 复制代码
package com.junjiu.springboot3.config;

import com.junjiu.springboot3.config.properties.JunjiuCustomProperties;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

/**
 * 外部资源映射配置
 * 实现:外部文件夹 -> 浏览器URL访问
 */
@Configuration
public class ResourceConfig implements WebMvcConfigurer {

    @Autowired
    private JunjiuCustomProperties junjiuCustomProperties;

    @Override
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
        // 从配置文件读取路径
        String resourcePath = junjiuCustomProperties.getResourcePath();

        // 确保路径以 / 结尾,避免拼接错误
        if (!resourcePath.endsWith("/")) {
            resourcePath += "/";
        }

        System.out.println("外部资源路径:" + resourcePath);

        // 映射规则:
        // 浏览器访问 /profile/**  →  找本地 file:xxx 目录
        registry.addResourceHandler("/profile/**")
                .addResourceLocations("file:" + resourcePath);
    }
}

3. application.yml 配置(路径可自定义)

yaml 复制代码
junjiu:
  custom:
    resource-path: ./file  # 相对路径,项目根目录下的 file 文件夹

三、原理讲解(一看就懂)

java 复制代码
registry.addResourceHandler("/profile/**")
        .addResourceLocations("file:" + resourcePath);

作用:

  • 当你访问:http://localhost:5826/profile/avatar.jpg
  • Spring Boot 就会去:项目根目录/file/avatar.jpg 找图片
  • 找到就直接显示,找不到返回404

✅ 支持:

  • 图片(png/jpg/gif)
  • 文档(pdf/txt)
  • 视频(mp4)
  • 音频(mp3)

四、使用示例

  1. 在项目根目录创建 file 文件夹

  2. 放入一张图片 xr.jpg

  3. 启动项目

  4. 浏览器访问:

    http://localhost:5826/profile/xr.jpg

✅ 直接显示图片!


五、路径写法说明

1. 相对路径

yaml 复制代码
resource-path: ./file

表示:项目根目录/file

2. Windows 绝对路径

yaml 复制代码
resource-path: D:/upload/file

3. Linux 绝对路径

yaml 复制代码
resource-path: /home/server/upload

六、常见问题

1. 访问404

  • 检查文件夹是否创建
  • 检查文件名大小写
  • 检查路径是否以 / 结尾
  • 重启项目

2. 不想用profile作为URL前缀

修改这里即可:

java 复制代码
addResourceHandler("/files/**")

访问地址变成:

复制代码
http://localhost:5826/files/test.jpg

3. 映射网络路径?

支持,但需要权限和共享目录。


相关推荐
Flynn Liang4 小时前
流量治理不是限流那么简单:I/O 密集型 Java 服务的 6 层防线
java·微服务·高并发·限流·熔断·系统稳定性·resilience4j
学长毕设4 小时前
基于SpringBoot智慧养老服务平台设计与实现-附源码
java·spring boot·后端
曹牧4 小时前
Java:“刷新雪崩”
java·开发语言
秋天的怀念_David4 小时前
算法一千零一夜 · 第三十三夜 · 跳表
java·程序人生·算法
Forget the Dream6 小时前
Spring AI 2.0 系列(二):第一个 ChatClient——从注入到一次完整调用
java·人工智能·spring boot·ai·springai
黑十7 小时前
FDE 怎么快速搭一个可演示页面?最小前端方案
java·大数据·前端·数据库·人工智能
神明不懂浪漫8 小时前
【第八章】多线程(一)
java·开发语言·经验分享·笔记
用户54817845909508 小时前
Java 与 Python 在大模型与智能体领域的选型
java·python
文丑颜不良啊8 小时前
LeetCode3341~3360题目解析
java·leetcode
hai_android8 小时前
一行 asLiveData,背后是一座生命周期的桥
android·java·kotlin