【技术沙箱|Springboot依赖|spring-boot-starter-web】1、SpringBoot Web 启动依赖,用于开发 HTTP 接口

一、前置说明

  1. 一句话总结:本篇只讲解 spring-boot-starter-web 这个 依赖,它是 SpringBoot 开发 HTTP 接口的基础依赖。
  2. Springboot API:https://docs.spring.io/spring-boot/docs/2.7.18/reference/htmlsingle/#appendix.configuration-metadata

二、依赖引入方式

知识点:版本统一交给父工程 dependencyManagement 管控,子模块不需要写 version,详情:https://www.cnblogs.com/cmjChunShu/articles/23547464

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
</dependency>

三、spring-boot-starter-web 里面到底包含了什么

  • 内嵌 Tomcat 容器(默认 8080 端口,不用单独部署 Tomcat)
  • Spring MVC:接收请求、参数绑定、视图解析、拦截器等 web 核心能力
  • jackson:JSON 序列化 / 反序列化,接口自动返回 json
  • spring-boot-starter:springboot 基础核心包(自动配置、日志等)

笔记重点:starter 不是一个 jar,是依赖聚合包,帮我们一次性导入整套 web 场景需要的组件,不需要一个个手动引入

四、常用基础配置(application.yml)

  1. 修改服务端口
  2. 配置上下文路径(servlet.context-path)
  3. 常用拓展配置(编码、请求大小限制)
server:
  port: 8080
  servlet:
    context-path: /api
  1. server: 这个配置前缀,确实是 spring-boot-starter-web 带来的自动配置提供的;但是不能说:只要写在 server: 下面的配置,都属于它
  2. server 命名空间,是 SpringBoot 的 web 容器自动配置类(ServerProperties) 定义的,这个自动配置只有在引入 web starter 之后才会生效。
  3. 也就是说:

    1. 没引入 spring-boot-starter-web 你 yml 里就算写上 server: port:8080,这行配置不会生效,SpringBoot 根本不会去解析它,项目也不会启动 Tomcat。
    2. 引入了 spring-boot-starter-webserver.* 的全部配置(端口、context-path、编码、tomcat 线程池、ssl 等)才被加载,用来配置内嵌 web 容器。

五、常用注解

(接收请求(参数接收,高频))

1、@PathVariable 路径变量:/demo/{id}

    /**
     * @PathVariable 路径变量
     * 地址示例: http://127.0.0.1:8080/demo/info/1001
     * {id} 和 @PathVariable("id") 名字对应
   * 如果你方法参数名和请求参数名字一模一样,可以不用写name,但正式项目不建议如:@PathVariable Long id */ @GetMapping("/info/{id}") public String getInfo(@PathVariable("id") Long id){ return "你传入的路径id = " + id; }

2、@RequestParam 获取 URL 问号?后面的查询参数

2.1、地址样例1:http://127.0.0.1:8080/demo/query?name=张三&age=20

/**
 * @RequestParam 获取查询参数
 * 访问地址:http://127.0.0.1:8080/demo/query?name=张三&age=20
 */
@GetMapping("/query")
public String query(@RequestParam("name") String name, @RequestParam("age") Integer age){
    return "name:" + name + ",age:" + age;
}

2.2、默认必传(required = true):/demo/query?name=张三,缺少 age→ 400 报错:参数缺失,(required =false)参数可以不传,defaultValue = "18":不传的时候自动用默认值,字符串形式,Spring 自动转类型

地址样例2:/demo/query?name=张三

@GetMapping("/query")
public String query(
        @RequestParam("name") String name,
        @RequestParam(value = "age", required = false, defaultValue = "18") Integer age
){
    return "name:" + name + ",age:" + age;
}

2.3、接收数组 / 多个同名参数

地址样例3:/demo/list?ids=1&ids=2&ids=3

@GetMapping("/list")
public String list(@RequestParam("ids") List<Long> ids){
    return "ids集合:" + ids;
}

2.4、@PathVariable合并一起写一个混合示例(实战经常遇到)

地址样例4:http://127.0.0.1:8080/demo/user/100?type=vip

@GetMapping("/user/{userId}")
public String userMix(
        @PathVariable Long userId,
        @RequestParam(value = "type", required = false) String type
){
    return "用户id:" + userId + ",类型:" + type;
}

2.5、一次性接收所有查询参数,不知道参数名的时候很好用

@RequestParam 接收 Map 的用法,实战很常用,动态参数场景。

// 一次性接收所有查询参数,不知道参数名的时候很好用

@GetMapping("/map")
public R<Map<String, String>> getMap(@RequestParam Map<String,String> params){
    return R.ok(params);
}

3、@RequestBody 接收 POST 请求请求体里的 JSON 数据(前后端分离最核心的传参方式)

  • Content-Type 必须是 application/json 如果是 form-data、x-www-form-urlencoded,@RequestBody 接收不到。
  • 默认是必传 不传 body,或者传空,直接报 400 错误
/**
 * @RequestBody 接收JSON请求体
 * 请求方式:POST
 * Content-Type:application/json
 */
@PostMapping("/save")
public String saveUser(@RequestBody UserDTO userDTO){
    return "收到前端JSON:用户名=" + userDTO.getUsername()
            + ",年龄=" + userDTO.getAge()
            + ",手机号=" + userDTO.getPhone();
}

4、@RequestHeader 获取请求头,从 HTTP 请求头里拿值。 示例:拿 User-Agent、token、Accept。

请求头一般放鉴权 token、客户端信息;生产更多用拦截器统一处理,接口上直接写 @RequestHeader 属于简单场景使用。

@GetMapping("/header")
public R<String> getHeader(@RequestHeader("User-Agent") String ua) {
    return R.ok("浏览器UA:" + ua);
}

特性:

  • 默认必传;@RequestHeader(value = "token", required = false) 设为非必填
  • 也可以加 defaultValue
  • 可以一次性拿到全部头:@RequestHeader HttpHeaders headers
@GetMapping("/headers/all")
public R<HttpHeaders> allHeader(@RequestHeader HttpHeaders headers){
    return R.ok(headers);
}

5、@CookieValue 获取 Cookie,读取请求携带的 Cookie

特性:

  • required、defaultValue 用法和上面一致
  • Cookie 是浏览器自动带的;前后端分离项目现在很少依赖 Cookie 鉴权,更多用 Header 的 token
@GetMapping("/cookie")
public R<String> getCookie(@CookieValue(value = "JSESSIONID", required = false) String sessionId){
    return R.ok("JSESSIONID = " + sessionId);
}

6、@RequestPart:适合 multipart/form-data,文件上传 + JSON 字段混合表单。

multipart/form-data 混合上传场景优先 @RequestPart;普通 url 参数、简单表单用 @RequestParam。

@PostMapping("/upload")
public R<String> upload(
        @RequestPart("file") MultipartFile file,
        @RequestPart("name") String name
){
    return R.ok("文件名:" + file.getOriginalFilename() + ",名称:" + name);
}

7、@PutMapping、@DeleteMapping,本质都是 @RequestMapping 的组合注解

  • @PutMapping:PUT 请求,一般用于修改资源
  • @DeleteMapping:DELETE 请求,一般用于删除资源
/**
 * 修改
 */
@PutMapping("/{id}")
public R<String> update(@PathVariable Long id){
    return R.ok("修改id:" + id);
}

/**
 * 删除
 */
@DeleteMapping("/{id}")
public R<String> delete(@PathVariable Long id){
    return R.ok("删除id:" + id);
}
同属的注解还有:
  • @GetMapping 查询
  • @PostMapping 新增
  • @PutMapping 修改
  • @DeleteMapping 删除

8、@Controller + @ResponseBody (@RestController 的底层),@RestController = @Controller + @ResponseBody

  • @Controller:标记这是控制器,不会自动返回 JSON,默认走视图解析(返回页面)
  • @ResponseBody:把返回值直接输出到响应体,不解析视图,序列化成 JSON
现在前后端分离几乎全部用 @RestController;@Controller 多用于传统模板引擎(Thymeleaf),项目用不上,但必须知道来源。
// 等价于 @RestController
@Controller
@RequestMapping("/view")
public class ViewController {
    @GetMapping("/test")
    @ResponseBody
    public R<String> test(){
        return R.ok("带ResponseBody");
    }
}

9、@CrossOrigin 跨域注解:前端页面(比如 Vue)域名端口和后端不一致,浏览器同源策略拦截。

注解方式是简单方案;生产项目一般用全局 Cors 配置类,这个注解适合快速测试。

// 加在类上:当前Controller所有接口都允许跨域
@CrossOrigin
@RestController
@RequestMapping("/demo")
public class DemoController {
}
或者加在单个方法:
@CrossOrigin
@GetMapping("/cors")
public R<String> cors(){
    return R.ok("支持跨域");
}

10、@ResponseStatus 用来手动指定 HTTP 响应状态码,不依赖返回 R 对象的 code。

@GetMapping("/notfound")
@ResponseStatus(HttpStatus.NOT_FOUND)
public R<String> notFound(){
    return R.fail(404,"资源不存在");
}

11、@InitBinder 请求参数绑定预处理,比如日期格式化、去掉字符串前后空格、自定义类型转换。

  • 非常实用,很多人不知道,不用写全局配置,controller 内局部生效
  • 适合局部参数格式化;全局一般用 Converter,但这个注解简单场景很香。
@InitBinder
public void initBinder(WebDataBinder binder) {
    // 示例:自动去除字符串前后空格
    binder.registerCustomEditor(String.class, new StringTrimmerEditor(true));
}

12、@ModelAttribute 

两个核心用法:

  • ① 方法上:当前 Controller 所有接口执行前,先执行这个方法,往 Model 塞数据
  • ② 参数上:接收表单 application/x-www-form-urlencoded,自动封装到实体(和 @RequestParam 很像,不接收 JSON)
// 方式1:接口执行前加载
@ModelAttribute("projectName")
public String loadProjectName(){
    return "tech-sandbox";
}

// 方式2:表单实体封装
@PostMapping("/form")
public R<UserDTO> form(@ModelAttribute UserDTO userDTO){
    return R.ok(userDTO);
}
重点区分: @ModelAttribute → urlencoded 表单;@RequestBody → json;@RequestPart → multipart。

13、@ExceptionHandler 局部异常处理器,只对当前 Controller 生效,还没到全局

  • @ExceptionHandler:单 Controller 局部异常(✅ 本篇可以放)
  • @RestControllerAdvice:全局异常(❌ 需要 aop 依赖,放到另外博客)
@ExceptionHandler(IllegalArgumentException.class)
public R<String> handleArgEx(IllegalArgumentException e){
    return R.fail(400, "参数错误:" + e.getMessage());
}
posted @ 2026-11-05 11:20  椿树之久  阅读(13)  评论(0)    收藏  举报