当前位置：首页 > news >正文

SpringBoot17-addresourcehandler()方法

news 2025/11/15 10:39:54

一、什么是 addResourceHandler

addResourceHandler 是 Spring MVC 中用于配置静态资源映射的方法，让你可以自定义静态资源（如图片、CSS、JS、视频等）的访问路径。

1-1、基本概念

registry.addResourceHandler("/访问路径/**").addResourceLocations("file:实际存储路径/");

ResourceHandler：浏览器访问的 URL 路径
ResourceLocations：服务器上文件的实际存储位置

1-2、完整配置示例

import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;@Configuration
public class WebConfig implements WebMvcConfigurer {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {// 配置1：映射本地磁盘文件registry.addResourceHandler("/upload/**").addResourceLocations("file:D:/upload/");// 配置2：映射 classpath 下的静态资源registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/");// 配置3：多个位置映射registry.addResourceHandler("/images/**").addResourceLocations("file:D:/images/", "classpath:/images/");}
}

1-3、实际应用场景

场景1：用户上传文件访问

@Configuration
public class WebConfig implements WebMvcConfigurer {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {// Windows 路径registry.addResourceHandler("/upload/**").addResourceLocations("file:D:/myapp/upload/");// Linux 路径// registry.addResourceHandler("/upload/**")//         .addResourceLocations("file:/home/myapp/upload/");}
}

使用效果：

文件存储位置：D:/myapp/upload/avatar/user1.jpg
浏览器访问：http://localhost:8080/upload/avatar/user1.jpg

文件上传示例：

@RestController
public class FileController {@PostMapping("/uploadFile")public String upload(@RequestParam("file") MultipartFile file) {// 保存文件到 D:/myapp/upload/String fileName = file.getOriginalFilename();File dest = new File("D:/myapp/upload/" + fileName);file.transferTo(dest);// 返回访问路径return "http://localhost:8080/upload/" + fileName;}
}

场景2：配置多个静态资源路径

@Configuration
public class WebConfig implements WebMvcConfigurer {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {// 图片资源registry.addResourceHandler("/images/**").addResourceLocations("file:D:/resources/images/");// 视频资源registry.addResourceHandler("/videos/**").addResourceLocations("file:D:/resources/videos/");// 文档资源registry.addResourceHandler("/docs/**").addResourceLocations("file:D:/resources/docs/");}
}

场景3：配置缓存策略

@Configuration
public class WebConfig implements WebMvcConfigurer {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/").setCachePeriod(3600)  // 缓存1小时（秒）.resourceChain(true);   // 启用资源链}
}

给静态资源（如图片、js、css）设置浏览器缓存，让浏览器缓存 1 小时，不用每次都重新请求服务器。

换句话说：

浏览器第一次访问 http://localhost/static/logo.png 时，会向服务器要资源
之后 1 小时内 再访问同样的资源
→ 浏览器直接从本地缓存读取
→ 不去请求服务器
→ 页面加载更快，服务器压力更小

启用资源链，就是让 Spring Boot 对静态资源的处理更智能、更高效，可以支持缓存、版本号解析、压缩、优化等高级特性。

没有资源链 → 只是最基础的静态资源访问
启用资源链 → 静态资源的“增强模式”

场景4：从配置文件读取路径

# application.yml
file:upload-path: D:/myapp/upload/access-path: /upload/**

@Configuration
public class WebConfig implements WebMvcConfigurer {@Value("${file.upload-path}")private String uploadPath;@Value("${file.access-path}")private String accessPath;@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {registry.addResourceHandler(accessPath).addResourceLocations("file:" + uploadPath);}
}

1-4、路径说明

1. ResourceHandler 路径格式

// ✅ 正确：使用 /** 表示匹配所有子路径
registry.addResourceHandler("/upload/**")// ❌ 错误：只会匹配 /upload，不匹配子路径
registry.addResourceHandler("/upload")

2. ResourceLocations 路径格式

// classpath 路径（项目内资源）
.addResourceLocations("classpath:/static/")// file 路径（磁盘文件）
.addResourceLocations("file:D:/upload/")     // Windows
.addResourceLocations("file:/home/upload/")  // Linux// ⚠️ 注意：路径末尾要加 /
.addResourceLocations("file:D:/upload/")  // ✅ 正确
.addResourceLocations("file:D:/upload")   // ❌ 可能出问题

1-5、常见问题

问题1：配置后访问404

// 检查路径末尾是否有 /
registry.addResourceHandler("/upload/**").addResourceLocations("file:D:/upload/");  // 末尾必须有 /

问题2：Windows 路径问题

// ✅ 方式1：使用正斜杠
.addResourceLocations("file:D:/upload/")// ✅ 方式2：使用双反斜杠
.addResourceLocations("file:D:\\upload\\")// ❌ 错误：单反斜杠会被转义
.addResourceLocations("file:D:\upload\")

问题3：覆盖默认静态资源配置

@Configuration
public class WebConfig implements WebMvcConfigurer {@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {// 这样会覆盖 Spring Boot 默认的 /static、/public 等配置// 需要手动添加回来registry.addResourceHandler("/**").addResourceLocations("classpath:/static/");}
}

1-6、完整实战案例

@Configuration
public class WebConfig implements WebMvcConfigurer {@Value("${file.upload-dir:D:/upload/}")private String uploadDir;@Overridepublic void addResourceHandlers(ResourceHandlerRegistry registry) {// 用户上传文件registry.addResourceHandler("/upload/**").addResourceLocations("file:" + uploadDir).setCachePeriod(0);  // 不缓存，实时更新// 保留默认静态资源配置registry.addResourceHandler("/static/**").addResourceLocations("classpath:/static/").setCachePeriod(31536000);  // 缓存1年}
}

@RestController
public class FileController {@Value("${file.upload-dir:D:/upload/}")private String uploadDir;@PostMapping("/upload")public Map<String, String> upload(@RequestParam("file") MultipartFile file) throws IOException {// 生成唯一文件名String originalFilename = file.getOriginalFilename();String fileName = System.currentTimeMillis() + "_" + originalFilename;// 保存文件Path path = Paths.get(uploadDir, fileName);Files.createDirectories(path.getParent());file.transferTo(path.toFile());// 返回访问URLString url = "http://localhost:8080/upload/" + fileName;return Map.of("url", url, "filename", fileName);}
}

1-7、总结

配置项	说明	示例
addResourceHandler	访问路径	`/upload/**`
addResourceLocations	实际存储位置	`file:D:/upload/`
setCachePeriod	缓存时间（秒）	`3600`
resourceChain	启用资源链	`true`