控制器细节全解：参数绑定、返回值与类型转换

@GetMapping("/users/{userId}/orders/{orderId:\\d+}")public Order detail(@PathVariable Long userId,                    @PathVariable("orderId") Long orderId) {    return orderService.findByUserAndOrder(userId, orderId);}// 或者用 Map 一次性接收全部路径变量@GetMapping("/files/{folder}/{name}")public String read(@PathVariable Map<String, String> vars) {    return files.read(vars.get("folder"), vars.get("name"));}

@PostMapping("/users")public UserVO create(@Valid @RequestBody UserCreateDTO dto) {    // 请求体被 Jackson 读成 JSON 树反序列化成 dto    // Content-Type 必须是 application/json，否则 415    return userService.create(dto);}public record UserCreateDTO(        @NotBlank String username,        @Email String email,        Integer age) {}

@GetMapping("/users")public PageResult<UserVO> page(@ModelAttribute UserQuery query) {    // 查询串里的 username、status、page、size 会按 setter/构造器注入 query    return userService.page(query);}public class UserQuery {    private String username;    private UserStatus status = UserStatus.ACTIVE;    private int page = 1;    private int size = 20;    // getter / setter 省略}

public class ReportQuery {    // 声明文本格式，否则字符串 "2024-05-01" 无法变成 LocalDate    @DateTimeFormat(iso = DateTimeFormat.ISO.DATE)    private LocalDate from;    @DateTimeFormat(pattern = "yyyy-MM-dd HH:mm:ss")    private LocalDateTime createdAt;    // 枚举按名字匹配：?status=ACTIVE    private UserStatus status;}

public class InvoiceQuery {    @DateTimeFormat(pattern = "yyyyMMdd")    private LocalDate billDate;           // 20240501 → LocalDate    @NumberFormat(pattern = "#,###.##")    private BigDecimal amount;            // "12,345.67" → BigDecimal}

@Componentpublic class PercentFormatter implements Formatter<BigDecimal> {    @Override    public BigDecimal parse(String text, Locale locale) {        return new BigDecimal(text.replace("%", "")).movePointLeft(2);    }    @Override    public String print(BigDecimal value, Locale locale) {        return value.movePointRight(2).toPlainString() + "%";    }}

@Configurationpublic class WebConvertConfig implements WebMvcConfigurer {    @Override    public void addFormatters(FormatterRegistry registry) {        registry.addConverter(new OrderNoConverter());        registry.addFormatter(new PercentFormatter());    }}

@RestController@RequestMapping("/api/files")public class FileController {    // 1) 自定义状态码：创建成功返回 201 + Location 头    @PostMapping    public ResponseEntity<UserVO> create(@RequestBody UserCreateDTO dto) {        UserVO vo = userService.create(dto);        return ResponseEntity                .created(URI.create("/api/files/" + vo.id()))  // 201                .body(vo);    }    // 2) 无内容：删除成功返回 204    @DeleteMapping("/{id}")    public ResponseEntity<Void> delete(@PathVariable Long id) {        fileService.delete(id);        return ResponseEntity.noContent().build();             // 204    }    // 3) 文件下载：自定义 Content-Type 与 Content-Disposition    @GetMapping("/{id}/download")    public ResponseEntity<Resource> download(@PathVariable Long id) throws IOException {        Resource resource = fileService.loadAsResource(id);        String filename = URLEncoder.encode(resource.getFilename(), StandardCharsets.UTF_8);        return ResponseEntity.ok()                .header(HttpHeaders.CONTENT_TYPE, MediaType.APPLICATION_OCTET_STREAM_VALUE)                .header(HttpHeaders.CONTENT_DISPOSITION,                        "attachment; filename*=UTF-8''" + filename)                .contentLength(resource.contentLength())                .body(resource);    }}

@GetMapping("/users")public PageResult<UserVO> page(        @RequestParam(defaultValue = "1") int page,        @RequestParam(defaultValue = "20") int size,        @RequestParam(required = false) String sort,        @RequestParam(required = false) String keyword) {    return userService.page(keyword, page, size, sort);}

@GetMapping("/users/search")public PageResult<UserVO> search(@ModelAttribute UserQuery query) {    // query 里可以塞十几个筛选字段，方法签名依然干净    return userService.search(query);}

package com.example.lab.controller;import jakarta.validation.constraints.Email;import jakarta.validation.constraints.NotBlank;import org.springframework.http.ResponseEntity;import org.springframework.web.bind.annotation.*;import java.time.LocalDate;import java.util.Map;@RestController@RequestMapping("/api/orders")public class OrderLabController {    record OrderVO(Long id, String username, LocalDate from, String token, String keyword) {}    @PostMapping("/{id}/search")    public ResponseEntity<OrderVO> handle(            @PathVariable Long id,                                  // 门牌号            @RequestParam(required = false, defaultValue = "1") int page,   // 附加栏            @RequestHeader("X-Auth-Token") String token,             // 面单条款            @RequestBody SearchForm form) {                          // 包裹本体        return ResponseEntity.ok(new OrderVO(id, form.keyword(), form.from(), token, form.keyword()));    }    record SearchForm(@NotBlank String keyword, LocalDate from) {}   // from 必须是 yyyy-MM-dd    // 表单式提交（没有请求体 JSON）：@ModelAttribute 路线    @GetMapping    public ResponseEntity<Map<String, Object>> list(@ModelAttribute PageQuery q) {        return ResponseEntity.ok(Map.of("page", q.page, "size", q.size, "from", String.valueOf(q.from)));    }    static class PageQuery {        private int page = 1;        private int size = 20;        @org.springframework.format.annotation.DateTimeFormat(iso = org.springframework.format.annotation.DateTimeFormat.ISO.DATE)        private LocalDate from;        public int getPage() { return page; }        public void setPage(int page) { this.page = page; }        public int getSize() { return size; }        public void setSize(int size) { this.size = size; }        public LocalDate getFrom() { return from; }        public void setFrom(LocalDate from) { this.from = from; }    }}

# 1) 四种来源齐全 → 200curl -i -X POST http://localhost:8080/api/orders/7/search \     -H "Content-Type: application/json" \     -H "X-Auth-Token: tk-abc" \     -d '{"keyword":"phone","from":"2024-05-01"}'# 2) 漏掉自定义请求头 → 400 MissingRequestHeaderExceptioncurl -i -X POST http://localhost:8080/api/orders/7/search \     -H "Content-Type: application/json" -d '{"keyword":"phone"}'# 3) 漏掉 Content-Type → 415（后端根本没机会看你的 JSON）curl -i -X POST http://localhost:8080/api/orders/7/search -d '{"keyword":"phone"}'# 4) 日期格式不对 → 400 Failed to convert value of type 'java.lang.String'curl -i -X POST http://localhost:8080/api/orders/7/search \     -H "Content-Type: application/json" -H "X-Auth-Token: tk-abc" \     -d '{"keyword":"phone","from":"01/05/2024"}'# 5) 查询串绑对象 → 200，未传的字段保留字段上的默认值curl -i "http://localhost:8080/api/orders?page=3&from=2024-05-01"

{  "id": 7,  "username": "phone",  "from": "2024-05-01",  "token": "tk-abc",  "keyword": "phone"}

{  "page": 3,  "size": 20,  "from": "2024-05-01"}