SpringMVC_02_注解开发实战

Zhou1411362026-09-29 12:14

【Spring MVC】注解开发实战：核心注解与 RESTful 风格

🔑 关键词：Java、Spring MVC、@Controller、@RequestMapping、@RequestParam、@PathVariable、RESTful

一、常用注解总览

注解 作用 标注位置
@Controller 声明为 Controller 组件 类上
@RestController = @Controller + @ResponseBody 类上
@RequestMapping 映射请求路径 类/方法上
@GetMapping GET 请求快捷注解 方法上
@PostMapping POST 请求快捷注解 方法上
@PutMapping PUT 请求快捷注解 方法上
@DeleteMapping DELETE 请求快捷注解 方法上
@RequestParam 接收查询参数 方法参数上
@PathVariable 接收路径变量 方法参数上
@RequestBody 接收 JSON 请求体 方法参数上
@ResponseBody 返回值写入响应体 方法上
@ModelAttribute 绑定表单数据到模型 方法参数上

二、请求映射注解

2.1 @RequestMapping

java 复制代码 
@Controller
@RequestMapping("/user")  // 类级别：统一前缀
public class UserController {

    @RequestMapping("/list")  // 方法级别：完整路径 /user/list
    public String list() {
        return "userList";
    }

    // 指定请求方法
    @RequestMapping(value = "/add", method = RequestMethod.POST)
    public String add() {
        return "redirect:/user/list";
    }
}

2.2 快捷注解（推荐）

java 复制代码 
@RestController
@RequestMapping("/api/user")
public class UserRestController {

    @GetMapping("/list")      // GET /api/user/list
    public List<User> list() {
        return userService.findAll();
    }

    @GetMapping("/{id}")      // GET /api/user/1
    public User getById(@PathVariable Long id) {
        return userService.findById(id);
    }

    @PostMapping              // POST /api/user
    public User create(@RequestBody User user) {
        return userService.save(user);
    }

    @PutMapping("/{id}")      // PUT /api/user/1
    public User update(@PathVariable Long id, @RequestBody User user) {
        user.setId(id);
        return userService.update(user);
    }

    @DeleteMapping("/{id}")   // DELETE /api/user/1
    public void delete(@PathVariable Long id) {
        userService.deleteById(id);
    }
}

三、参数绑定注解

3.1 @RequestParam ------ 接收查询参数

java 复制代码 
// GET /api/user?name=张三&age=25

@GetMapping("/search")
public String search(
    @RequestParam("name") String name,      // 必传参数
    @RequestParam(value = "age", required = false) Integer age,  // 可选参数
    @RequestParam(defaultValue = "1") int page  // 带默认值
) {
    return "查询：" + name + ", " + age + ", page=" + page;
}

常用属性：

属性 说明
value / name 参数名（可与方法参数名不同）
required 是否必传，默认 true
defaultValue 默认值（设置后 required 自动为 false）

3.2 @PathVariable ------ 接收路径变量

java 复制代码 
// GET /api/user/123
@GetMapping("/{id}")
public User getById(@PathVariable("id") Long id) {
    return userService.findById(id);
}

// GET /api/user/123/order/456
@GetMapping("/{userId}/order/{orderId}")
public Order getOrder(
    @PathVariable Long userId,
    @PathVariable Long orderId
) {
    return orderService.find(userId, orderId);
}

对比：

方式 URL 示例 适用场景
@RequestParam /user?id=1 查询参数、分页、筛选
@PathVariable /user/1 RESTful 资源定位

3.3 @RequestBody ------ 接收 JSON 请求体

java 复制代码 
// POST /api/user
// Content-Type: application/json
// Body: {"name": "张三", "age": 25}

@PostMapping
public User create(@RequestBody User user) {
    // Spring 自动将 JSON 反序列化为 User 对象（需要 Jackson 依赖）
    return userService.save(user);
}

注意：

  • 一个方法只能有一个 @RequestBody
  • 需要引入 Jackson 依赖：jackson-databind
  • Content-Type 必须是 application/json

3.4 直接接收 POJO（无需注解）

java 复制代码 
// GET /api/user?name=张三&age=25
// 或 POST 表单提交
@GetMapping("/register")
public String register(User user) {
    // Spring 自动将请求参数绑定到 User 的同名属性
    System.out.println(user.getName());  // 张三
    System.out.println(user.getAge());   // 25
    return "success";
}

四、响应处理

4.1 @ResponseBody ------ 返回 JSON

java 复制代码 
@Controller
public class ApiController {

    @ResponseBody  // 返回值直接写入响应体（JSON 格式）
    @GetMapping("/api/hello")
    public Map<String, String> hello() {
        Map<String, String> map = new HashMap<>();
        map.put("message", "Hello JSON!");
        return map;
        // 响应：{"message": "Hello JSON!"}
    }
}

4.2 @RestController ------ 类级别 @ResponseBody

java 复制代码 
@RestController  // 等价于 @Controller + 所有方法 @ResponseBody
@RequestMapping("/api")
public class ApiController {

    @GetMapping("/users")
    public List<User> list() {
        return userService.findAll();  // 自动序列化为 JSON
    }
}

4.3 ResponseEntity ------ 完全控制响应

java 复制代码 
@GetMapping("/api/user/{id}")
public ResponseEntity<User> getById(@PathVariable Long id) {
    User user = userService.findById(id);
    if (user == null) {
        return ResponseEntity.notFound().build();  // 404
    }
    return ResponseEntity.ok(user);  // 200 + JSON
}

@PostMapping("/api/user")
public ResponseEntity<User> create(@RequestBody User user) {
    User saved = userService.save(user);
    URI location = URI.create("/api/user/" + saved.getId());
    return ResponseEntity.created(location).body(saved);  // 201
}

常用状态码：

方法 状态码 场景
.ok(body) 200 成功
.created(uri).body(body) 201 创建成功
.noContent().build() 204 无内容
.badRequest().build() 400 请求错误
.notFound().build() 404 资源不存在

五、RESTful 风格设计

5.1 RESTful 核心原则

HTTP 方法 操作 URL 示例 说明
GET 查询 /api/users 获取列表
GET 查询 /api/users/1 获取单个
POST 新增 /api/users 创建资源
PUT 修改 /api/users/1 全量更新
PATCH 修改 /api/users/1 部分更新
DELETE 删除 /api/users/1 删除资源

5.2 完整 RESTful Controller

java 复制代码 
@RestController
@RequestMapping("/api/users")
public class UserRestController {

    @Autowired
    private UserService userService;

    // 查询全部
    @GetMapping
    public ResponseEntity<List<User>> list() {
        return ResponseEntity.ok(userService.findAll());
    }

    // 根据 ID 查询
    @GetMapping("/{id}")
    public ResponseEntity<User> getById(@PathVariable Long id) {
        User user = userService.findById(id);
        return user != null
            ? ResponseEntity.ok(user)
            : ResponseEntity.notFound().build();
    }

    // 新增
    @PostMapping
    public ResponseEntity<User> create(@RequestBody User user) {
        User saved = userService.save(user);
        return ResponseEntity.status(HttpStatus.CREATED).body(saved);
    }

    // 修改
    @PutMapping("/{id}")
    public ResponseEntity<User> update(@PathVariable Long id, @RequestBody User user) {
        user.setId(id);
        return ResponseEntity.ok(userService.update(user));
    }

    // 删除
    @DeleteMapping("/{id}")
    public ResponseEntity<Void> delete(@PathVariable Long id) {
        userService.deleteById(id);
        return ResponseEntity.noContent().build();
    }
}

六、总结

注解 用途 记忆要点
@RequestMapping 路径映射 可标注在类和方法上
@RequestParam 查询参数 ?name=xxx
@PathVariable 路径变量 /user/{id}
@RequestBody JSON 请求体 POST/PUT 的 JSON 数据
@ResponseBody JSON 响应 返回值写入响应体
ResponseEntity 完全控制响应 状态码 + 响应头 + 响应体

📝 下一篇预告：《Spring MVC 进阶功能》，详解拦截器、文件上传下载、全局异常处理。

相关推荐
繁华的地方不一定留下你的脚印1 小时前
C++ 算法与 ranges：用 find_if、transform 写清数据处理意图
开发语言·c++·算法
禹凕2 小时前
机器学习之数据清洗（Machine Learning about Data Cleaning）
人工智能·爬虫·python·机器学习·数据挖掘
浩瀚地学2 小时前
deepagents学习打卡day07
经验分享·笔记·python·学习·agent
霸道流氓气质2 小时前
Mermaid 图表完全指南：从文本语法到LangGraph4j工作流可视化实战
开发语言·python
SamChan902 小时前
PDF翻译时页眉页脚总在捣乱？跨页重复文本块的检测与过滤实测
人工智能·python·ai·pdf·wpf
晴空蓝天2 小时前
MDC traceId 全链路日志追踪：Spring Boot 3.5 里把日志串成一条线
java·spring boot·后端·python
泡海椒2 小时前
JQuick-Excel 项目定位与适用场景：声明式 Java Excel 的边界
java·开发语言·excel
L@ncor2 小时前
第六章可能出现的问题：依赖冲突与成本乘法
python·依赖管理·langgraph·agentscope·避坑
AC赳赳老秦2 小时前
财报附注表格精准提取：OpenClaw 从 PDF 年报附注挖掘隐藏明细，补齐财务分析维度
java·汇编·c++·python·青少年编程·deepseek·openclaw
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02Telegram APK 下载安装完整指南 — 2026年最新03历年考研数学一、数学二、数学三真题试卷及答案PDF04GitHub 镜像站点052026 爱知・名古屋亚运会怎么看？直播平台+赛程安排分享06蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接072026 年 9 月国内外主流大模型横向硬核评测：价格、算力、业务场景全维度对比，GPT‑6 Astra横空出世08给AI一张“业务概念地图“：本体如何从哲学走向企业智能09jev-ultrafast 深度解析：7 秒订机票的浏览器 Agent 是如何炼成的10微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新