Spring 請求與回應

📢 本文由 gemini-2.5-flash 翻譯

瀏覽器發送請求會先經過 DispatcherServlet 轉交給各 *Controller 程式處理，處理完成後將結果返回給 DispatcherServlet，然後再回傳給瀏覽器。

DispatcherServlet 被稱為核心控制器或前端控制器。

對於瀏覽器請求的資料，會被封裝到 HttpServletRequest 物件中；回應資料則會被封裝到 HttpServletResponse 物件中。

*Controller 接收請求，設定回應

請求

簡單參數

首先是原始方式，透過 HttpServletRequest 物件手動取得請求參數。

1
2
3
4
5
6
7
8
9
@RequestMapping("/simpleParam")
public String simpleParam(HttpServletRequest request){
    String name = request.getParameter("name");
    String ageStr = request.getParameter("age");

    int age = Integer.parseInt(ageStr);
    System.out.println(name + ";" + age);
    return "OK";
}

當瀏覽器存取 http://localhost:8080/simpleParam?name=tom&age=18 網頁時會回傳字串 “OK”，程式則會回傳 “Tom;18”。

顯然這種方式過於麻煩，在 SpringBoot 中可以透過參數名稱與方法參數名稱相同的方式，直接定義方法參數即可接收。

1
2
3
4
5
@RequestMapping("/simpleParam")
public String simpleParam(String name, Integer age){
    System.out.println(name + ";" + age);
    return "OK";
}

效果相同。

不過上述方法即使請求的參數名稱不同也會繼續執行，未提供的參數會是 null。

可以使用 @RequestParam 完成映射，實現請求名稱與方法參數名稱不同時的對應。

1
2
3
4
5
6
7
@RequestMapping("/simpleParam")
public  String simpleParam(@RequestParam(name = "name") String username, Integer age){
    // 當宣告 @RequestParam 後，代表該參數必須被傳遞，否則會報錯。
    // 若更改為 @RequestParam(name = "name", required = false) 代表該參數並非必要。
    System.out.println(username + ";" + age);
    return "OK";
}

實體參數

如果只是少量參數，使用上述方法可行；但若是較多的資料，可以透過簡單實體物件來處理，只要請求參數名稱與方法參數物件的屬性名稱相同，定義 POJO 即可接收。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
@RequestMapping("/simplePojo")
public String simplePojo(User user){
    System.out.println(user);
    return "OK";
}

// User類
public class User{
    private String name;
    private Integer age;
    // set get toString 方法
}

存取 http://localhost:8080/simplePojo?name=tom&age=18 網頁時會回傳字串 “OK”，程式則會回傳 “User{name=‘tom’, age=18}”。

複雜實體物件：請求參數名稱與方法參數屬性名稱相同，依照物件的階層結構關係即可接收巢狀 POJO 屬性參數。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
@RequestMapping("/complexPojo")
public String complexPojo(UserComplex user){
    System.out.println(user);
    return "OK";
}

// User類
public class UserComplex{
    private String name;
    private Integer age;
    private Address address;
    // set get toString
}

// Address類
public class Address{
    private String province;
    private String city;
    // set get toString
}

存取 http://localhost:8080/complexPojo?name=tom&age=18&address.province=beijing&address.city=beijing 網頁時會回傳字串 “OK”，程式則會回傳 “UserComplex{name=‘tom’, age=1000, address=Address{province=‘ads,beijing’, city=‘asda,beijing’}}”。

陣列參數

請求參數名稱與方法參數陣列名稱相同且請求參數有多個時，定義陣列型別的方法參數即可接收。例如多選框。

1
2
3
4
5
@RequestMapping("/arrayParam")
public String arrayParam(String[] hobby){
    System.out.println(Arrays.toString(hobby));
    return "OK";
}

存取 http://localhost:8080/arrayParam?hobby=ads&hobby=58s 網頁時會回傳字串 “OK”，程式則會回傳 “[ads, 58s]”。

集合參數

請求參數名稱與方法參數陣列名稱相同且請求參數有多個時，使用 @RequestParam 繫結參數關係。

1
2
3
4
5
@RequestMapping("/listParam")
public String listParam(@RequestParam List<String> hobby){
    System.out.println(hobby);
    return "OK";
}

存取 http://localhost:8080/listParam?hobby=ads&hobby=58s 網頁時會回傳字串 “OK”，程式則會回傳 “[ads, 58s]”。

日期參數

使用 @DateTimeFormat 註解來完成日期參數的格式轉換。

需要注意的是傳遞參數有三種形式：

yyyy-MM-dd HH:mm:ss
yyyy/MM/dd HH:mm:ss
yyyy年MM月dd日 HH時mm分ss秒

需要前後端統一格式才行。

1
2
3
4
5
@RequestMapping("/dateParam")
public String dateParam(@DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss") LocalDateTime localDateTime){
    System.out.println(localDateTime);
    return "OK";
}

存取 http://localhost:8080/dateParam?localDateTime=2024-01-01%2001:01:01 網頁時會回傳字串 “OK”，程式則會回傳 “2024-01-01T01:01:01”。

JSON 參數

JSON 資料的鍵名與方法參數物件的屬性名稱相同，定義 POJO 型別的方法參數即可接收參數，需要使用 @RequestBody 標示。

若要傳輸 JSON 資料，必須使用 POST 請求。

1
2
3
4
5
@RequestMapping("/jsonParam")
public String jsonParam(@RequestBody UserComplex userComplex){
    System.out.println(userComplex);
    return "OK";
}

請求資料

1
2
3
4
5
6
7
8
{
    "name": "jane",
    "age": "18",
    "address": {
        "province": "上海",
        "city": "上海"
    }
}

使用 POST 方法請求 http://localhost:8080/jsonParam ，資料如上，網頁會回傳字串 “OK”，程式則會回傳 “UserComplex{name=‘jane’, age=18, address=Address{province=‘上海’, city=‘上海’}}"。

路徑參數

透過請求 URL 直接傳遞參數，使用 {...} 來標示該路徑參數，需要使用 @PathVariable 取得路徑參數。

1
2
3
4
5
@RequestMapping("/path/{id}")
public String pathParam(@PathVariable Integer id){
    System.out.println(id);
    return "OK";
}

存取 http://localhost:8080/path/52 網頁時會回傳字串 “OK”，程式則會回傳 “52”。

存取 http://localhost:8080/path/255 網頁時會回傳字串 “OK”，程式則會回傳 “255”。

對於多個路徑參數：

1
2
3
4
5
@RequestMapping("/path/{id}/{name}")
public String pathParam(@PathVariable Integer id, @PathVariable String name){
    System.out.println(id + ";" + name);
    return "OK";
}

存取 http://localhost:8080/path/255/Tom 網頁時會回傳字串 “OK”，程式則會回傳 “255;Tom”。

總結

簡單參數
- 定義方法參數，請求參數名稱與方法參數變數名稱一致。
- 如果名稱不一致，透過 @RequestParam 手動映射。
實體參數
- 請求參數名稱與實體物件的屬性名稱一致，會自動接收並封裝。
陣列集合參數
- 陣列：請求參數名稱與陣列名稱一致，直接封裝。
- 集合：請求參數名稱與陣列名稱一致，使用 @RequestParam 繫結關係。
日期參數
- @DateTimeFormat
JSON 參數
- @RequestBody
路徑參數
- @PathVariable

回應

使用 @RequestBody 處理回應

上述請求之所以能夠回應，是因為註解 @RestController 包含 @Controller 和 @ResponseBody。

@RequestBody

型別：方法註解、類別註解

位置：Controller 方法上或類別上

作用：將方法的返回值直接回應，若返回值型別為 實體物件或集合，將會轉換為 JSON 格式回應。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
@RestController
public class ResponseController {
    @RequestMapping("/hello")
    public String hello(){
        System.out.println("Hello SpringBoot");
        return "Hello SpringBoot";
    }

    @RequestMapping("/getAddr")
    public Address getAddr(){
        Address address = new Address();
        address.setProvince("上海");
        address.setCity("上海");
        return address;
    }

    @RequestMapping("/listAddr")
    public List<Address> listAddr(){
        List<Address> list = new ArrayList<>();
        Address address1 = new Address();
        address1.setProvince("北京");
        address1.setCity("北京");
        Address address2 = new Address();
        address2.setProvince("上海");
        address2.setCity("上海");

        list.add(address1);
        list.add(address2);
        return list;
    }
}

存取相關網址進行測試。

統一回應結果

以上三個方法的回傳型別都不一樣，使得前端開發較為困難，因此可以統一回應結果為一個類別。

1
2
3
4
5
6
7
8
9
public class Result{
    // 回應碼，1 代表成功，0 代表失敗
    private Integer code;
    // 提示訊息
    private String msg;
    // 回傳的資料
    private Object data;
    // ...
}

讓所有的回應方法都回傳一個 Result 物件，使專案管理與維護更為容易。

例如以下類別：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
public class Result {
    private Integer code ;//1 成功 , 0 失敗
    private String msg; //提示訊息
    private Object data; //資料 data

    public Result() {
    }
    public Result(Integer code, String msg, Object data) {
        this.code = code;
        this.msg = msg;
        this.data = data;
    }
    public Integer getCode() {
        return code;
    }
    public void setCode(Integer code) {
        this.code = code;
    }
    public String getMsg() {
        return msg;
    }
    public void setMsg(String msg) {
        this.msg = msg;
    }
    public Object getData() {
        return data;
    }
    public void setData(Object data) {
        this.data = data;
    }

    public static Result success(Object data){
        return new Result(1, "success", data);
    }
    public static Result success(){
        return new Result(1, "success", null);
    }
    public static Result error(String msg){
        return new Result(0, msg, null);
    }

    @Override
    public String toString() {
        return "Result{" +
                "code=" + code +
                ", msg='" + msg + '\'' +
                ", data=" + data +
                '}';
    }
}

那麼上面程式碼可以改為：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
@RequestMapping("/hello")
public Result hello(){
    System.out.println("Hello SpringBoot");
    return Result.success("Hello SpringBoot");
}

@RequestMapping("/getAddr")
public Result getAddr(){
    Address address = new Address();
    address.setProvince("上海");
    address.setCity("上海");
    return Result.success(address);
}

@RequestMapping("/listAddr")
public Result listAddr(){
    List<Address> list = new ArrayList<>();
    Address address1 = new Address();
    address1.setProvince("北京");
    address1.setCity("北京");
    Address address2 = new Address();
    address2.setProvince("上海");
    address2.setCity("上海");

    list.add(address1);
    list.add(address2);
    return Result.success(list);
}

存取相關網址進行測試。