SpringBoot整合Web開發之檔案上傳與@ControllerAdvice

2022-08-15 10:00:49

本章概要

檔案上傳
@ControllerAdvice

檔案上傳

Java 中的檔案上傳一共涉及兩個元件，一個是 CommonsMultipartResolver，另一個是 StandardServletMultipartResolver ，其中 CommonsMultipartResolver 使用 commons-fileupload 來處理 multipart 請求，而 StandardServletMultipartResolver 則是基於 Servlet 3.0 來處理。因此若使用 StandardServletMultipartResolver ，則不需要新增額外的 jar 包。Tomcat 7.0 開始就支援 Servlet 3.0 了，而Spring Boot 2.0.4 內嵌的 Tomcat 為 Tomcat 8.5.32 ，因此可以直接使用 StandardServletMultipartResolver 。而在 Spring Boot 提供的上傳檔案自動化設定類 MultipartAutoConfiguration 中，預設也是採用 StandardServletMultipartResolver ，部分原始碼如下：

	@Bean(name = DispatcherServlet.MULTIPART_RESOLVER_BEAN_NAME)
	@ConditionalOnMissingBean(MultipartResolver.class)
	public StandardServletMultipartResolver multipartResolver() {
		StandardServletMultipartResolver multipartResolver = new StandardServletMultipartResolver();
		multipartResolver.setResolveLazily(this.multipartProperties.isResolveLazily());
		return multipartResolver;
	}

根據設定可以看出，如果開發者沒有提供 MultipartResolver ，那麼預設採用的 MultipartResolver 就是 StandardServletMultipartResolver 。因此上傳檔案甚至可以做到零設定。

單檔案上傳

首先建立 Spring Boot 專案並新增 spring-boot-starter-web 依賴，然後在 resources 目錄下的 static 目錄中建立一個 upload.html 檔案，內容如下：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>檔案上傳</title>
</head>
<body>
<form action="/upload" method="post" enctype="multipart/form-data">
    <input type="file" name="uploadFile" value="請選擇檔案">
    <input type="submit" value="上傳">
</form>
</body>
</html>

接著建立檔案上傳處理介面，程式碼如下：

@RestController
public class FileUploadController {
    SimpleDateFormat sdf = new SimpleDateFormat("yyyy/MM/dd");
    @PostMapping("/upload")
    public String upload (MultipartFile uploadFile, HttpServletRequest request)  {
        // 原書中是這個上傳路徑，但是實際上是個虛擬Tomcat的路徑，後面無法存取到
        // String realPath = request.getSession().getServletContext().getRealPath("/uploadFile/");
        // 根據實際情況靈活設定上傳路徑
        String realPath = ClassUtils.getDefaultClassLoader().getResource("").getPath() + "/static/uploadFile/";
        String format = sdf.format(new Date());
        // 設定儲存路徑為專案執行目錄下的uploadFile資料夾，並在資料夾中通過日期對上傳的檔案歸類儲存
        File file = new File(realPath + format);
        if (!file.isDirectory()){
            file.mkdirs();
        }
        // 檔案重新命名，避免檔案重名
        String oldName = uploadFile.getOriginalFilename();
        String newName = UUID.randomUUID().toString()+oldName.substring(oldName.lastIndexOf("."),oldName.length());
        try {
            // 檔案儲存操作
            File file1 = new File(file, newName);
            uploadFile.transferTo(file1);
            // 生成上傳檔案的存取路徑，並返回
            String filePath = request.getScheme() + "://" + request.getServerName() + ":" + request.getServerPort() + "/uploadFile/" + format + "/" + newName;
            return filePath;
        }catch (Exception e){
            e.printStackTrace();
        }
        return "上傳失敗";
    }
}

注意：介面引數名要與html 中input 標籤的 name 屬性保持一致

執行專案，存取"http://localhost:8081/upload.html"，進行檔案上傳，如圖

單擊“選擇檔案”按鈕上傳檔案，檔案上傳成功後會返回上傳檔案的存取路徑，如圖

在瀏覽器中存取返回的路徑

也可以對檔案上傳的細節進行設定，如下

# 是否開啟檔案上傳，預設true
spring.servlet.multipart.enabled=true
# 寫入磁碟的閾值，預設0
spring.servlet.multipart.file-size-threshold=0
# 上傳檔案的臨時儲存位置
spring.servlet.multipart.location=E:\Gitee\my-work-space\chapter01\tmp
# 單檔案上傳大小限制
spring.servlet.multipart.max-file-size=1MB
# 多檔案上傳大小限制
spring.servlet.multipart.max-request-size=10MB
# 檔案是否延遲解析，預設false
spring.servlet.multipart.resolve-lazily=false

注意：spring.servlet.multipart.location 為臨時儲存位置，確儲存在此資料夾且不會刪除（此項設定不影響前邊上傳圖片的正常存取）

多檔案上傳

多檔案上傳和單檔案上傳基本一致，首先修改HTML檔案，如下：

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <title>多檔案上傳</title>
</head>
<body>
<form action="/upload" method="post" enctype="multipart/form-data">
    <!--  注意多了個multiple  -->
    <input type="file" name="uploadFile" multiple>
    <input type="submit" value="上傳">
</form>
</body>
</html>

然後修改控制器引數，如下

   @PostMapping("/upload")
    public String upload (MultipartFile[] uploadFile, HttpServletRequest request) {
        String filePath = "";
        // 遍歷檔案進行儲存操作
        for (int i = 0; i < uploadFile.length; i++) {
            // 原書中是這個上傳路徑，但是實際上是個虛擬Tomcat的路徑，後面無法存取到
            // String realPath = request.getSession().getServletContext().getRealPath("/uploadFile/");
            // 根據實際情況靈活設定上傳路徑
            String realPath = ClassUtils.getDefaultClassLoader().getResource("").getPath() + "/static/uploadFile/";

            String format = sdf.format(new Date());
            // 設定儲存路徑為專案執行目錄下的uploadFile資料夾，並在資料夾中通過日期對上傳的檔案歸類儲存
            File file = new File(realPath + format);
            if (!file.isDirectory()){
                file.mkdirs();
            }
            // 檔案重新命名，避免檔案重名
            String oldName = uploadFile[i].getOriginalFilename();
            String newName = UUID.randomUUID().toString()+oldName.substring(oldName.lastIndexOf("."),oldName.length());
            try {
                // 檔案儲存操作
                File file1 = new File(file, newName);
                uploadFile[i].transferTo(file1);
                // 生成上傳檔案的存取路徑，並返回
                filePath += request.getScheme() + "://" + request.getServerName() + ":" + request.getServerPort() + "/uploadFile/" + format + "/" + newName + ";";
            }catch (Exception e){
                e.printStackTrace();
            }
        }
        return filePath;
    }
}

@ControllerAdvice

@ControllerAdvice 是 @Controller 的增強版。 @ControllerAdvice 主要用來處理全域性資料，一般搭配 @ExceptionHandler 、 @ModelAttribute 以及 @InitBinder 使用

全域性例外處理

@ControllerAdvice 最常見的使用場景就是全域性例外處理。在4.3章節中檔案上傳設定，如果超過了限制大小，就會丟擲異常，此時可以通過 @ControllerAdvice 結合 @ExceptionHandler 定義全域性異常捕獲機制，程式碼如下：

@ControllerAdvice
public class CustomExceptionHandler {
    @ExceptionHandler(MaxUploadSizeExceededException.class)
    public void uploadException(MaxUploadSizeExceededException e , HttpServletResponse response) throws IOException {
        response.setContentType("text/html;charset=utf-8");
        PrintWriter out = response.getWriter();
        out.write("上傳檔案大小超出限制！");
        out.flush();
        out.close();
    }
}

只需在系統中定義 CustomExceptionHandler 類，然後新增 @ControllerAdvice 註解即可。當專案啟動時，該類就會被掃描到 Spring 容器中，然後定義 uploadException 方法，在該方法上新增了 @ExceptionHandler 註解，其中定義的 MaxUploadSizeExceededException.class 表名該方法用來處理 MaxUploadSizeExceededException 型別的異常。如果想讓該方法處理所有型別的異常，只需將 MaxUploadSizeExceededException 改為 Exception 即可。方法的引數可以有異常範例、HttpServletResponse 以及 HttpServletRequest 、 Model 等，返回值可以是一段JSON、一個ModelAndView 、一個邏輯檢視名等。此時上傳一個超大檔案會有錯誤提示給使用者，如下：

如果返回引數是一個ModelAndView，假設使用的頁面模版為 Thymeleaf （注意新增相關依賴），此時例外處理方法定義如下：

    @ExceptionHandler(MaxUploadSizeExceededException.class)
    public ModelAndView uploadException(MaxUploadSizeExceededException e) {
        ModelAndView mv = new ModelAndView();
        mv.addObject("msg","上傳檔案大小超出限制！");
        mv.setViewName("error");
        return mv;
    }

然後在 resources/templages 目錄下建立error.html 檔案，內容如下：

<!DOCTYPE html>
<html lang="en" xmlns:th="http://www.thymeleaf.org">
<head>
    <meta charset="UTF-8">
    <title>上傳提示</title>
</head>
<body>
<div th:text="${msg}"></div>
</body>
</html>

重啟專案，檢視效果

新增全域性資料

@ControllerAdvice 是一個全域性資料處理元件，因此也可以在 @ControllerAdvice 設定全域性資料，程式碼如下

@ControllerAdvice
public class GlobalConfig {
    @ModelAttribute(value = "info")
    public Map<String,String> userInfo(){
        HashMap<String, String> map = new HashMap<>();
        map.put("username","唐三");
        map.put("sex","男");
        return map;
    }
}

程式碼解釋：

在全域性設定中新增 userInfo 方法，返回一個map。該方法有一個註解 @ModelAttribute ，其中 value 的屬性表示這條返回資料的 key ，而方法的返回值是返回資料的 value
此時在任意請求的 Controller 中，通過方法引數中的Model 都可以獲取 info 的資料

Controller 範例程式碼如下：

@GetMapping("/hello")
public void hello(Model model){
    Map<String, Object> map = model.asMap();
    Set<String> keySet = map.keySet();
    Iterator<String> iterator = keySet.iterator();
    while (iterator.hasNext()){
        String key = iterator.next();
        Object value = map.get(key);
        System.out.println(key + ">>>>" + value);
    }
}

存取介面，列印如下：

info>>>>{sex=男, username=唐三}

請求引數預處理

@ControllerAdvice 結合 @InitBinder 還能實現請求引數預處理，即將表單中的資料繫結到實體類上時進行一些額外處理。

例如有兩個實體類 Book 和 Author ，程式碼如下：

public class Book {
    private String name;
    private String author;
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public String getAuthor() {
        return author;
    }
    public void setAuthor(String author) {
        this.author = author;
    }
}

public class Author {
    private String name;
    private int age;
    public String getName() {
        return name;
    }
    public void setName(String name) {
        this.name = name;
    }
    public int getAge() {
        return age;
    }
    public void setAge(int age) {
        this.age = age;
    }
}

在 Controller 上需要接收兩個實體類的資料，Controller 中的方法定義如下：

@GetMapping(value = "/book")
public String books(Book book, Author author){
    return book.toString() + ">>>" + author.toString();
}

此時在引數傳遞時，兩個實體類中的 name 屬性會混淆，@ControllerAdvice 結合 @InitBinder 可以順利解決問題。設定步驟如下。

先給Controller 中方法的引數新增 @ModelAttribute 註解，程式碼如下：

@GetMapping(value = "/book")
public String books(@ModelAttribute("b") Book book, @ModelAttribute("a") Author author){
    return book.toString() + ">>>" + author.toString();
}

然後設定 @ControllerAdvice ，程式碼如下：

@ControllerAdvice
public class GlobalConfig {
    @InitBinder("b")
    public void init1 (WebDataBinder binder){
        binder.setFieldDefaultPrefix("b.");
    }
    @InitBinder("a")
    public void init2 (WebDataBinder binder){
        binder.setFieldDefaultPrefix("a.");
    }
}