Spring Boot快速搭建RESTful接口实战

本文深入浅出地讲解了使用 Spring Boot 快速搭建可运行 RESTful 接口的核心要点与实战避坑指南：从最精简的依赖选择（仅需 spring-boot-starter-web）、三大必备注解条件（@RestController/@SpringBootApplication/@GetMapping）、主类包位置规范，到端口配置的正确写法（纯数字、无引号）、中文乱码的根因与一劳永逸解决方案，再到常见 404/500/ClassNotFoundException 等错误的精准定位逻辑——所有内容直击新手最易卡壳的“看似简单却死活跑不通”的细节盲区，帮你绕过玄学调试，真正实现“写完即跑通”。

Spring Boot项目初始化选哪个依赖最省事

直接用 spring-boot-starter-web 就够了，别加 spring-boot-starter-tomcat 或 spring-webmvc 这类底层依赖——它们已被 starter 自动拉入，手动加反而可能引发版本冲突。

常见错误现象：IDE 提示 “No dispatcher servlet found”，其实是没加 spring-boot-starter-web；或者启动报 ClassNotFoundException: org.springframework.web.servlet.DispatcherServlet，说明依赖不完整。

• 新建项目时，在 start.spring.io 勾选 Spring Web 即可（对应 spring-boot-starter-web）
• 如果用 Maven，确认 pom.xml 里有且仅有一处 spring-boot-starter-web，scope 保持默认（compile）
• 不用手动配 @EnableWebMvc —— Spring Boot 默认已启用，加了反而会覆盖自动配置

写一个能跑通的 @RestController 必须满足什么条件

三个硬性条件缺一不可：类上必须有 @RestController（或 @Controller + 方法上 @ResponseBody），方法要有 @GetMapping（或其它 HTTP 动词注解），且项目得有主启动类并带 @SpringBootApplication。

常见错误现象：“访问 /hello 返回 404”，大概率是主类没放在包顶层，导致组件扫描不到 Controller；或者用了 @Controller 但忘了加 @ResponseBody，结果返回的是视图名而非 JSON 字符串。

• 主启动类（如 Application.java）必须在“最外层包”下，比如包名是 com.example.demo，那它就得在 com.example.demo 包里，不能在 com.example.demo.controller
• @RestController 类默认路径前缀为空，想统一加前缀就用 @RequestMapping("/api") 在类上
• 方法返回值如果是 String，且没加 @ResponseBody，Spring Boot 会尝试走视图解析——此时若没配模板引擎，直接 500

最小可行示例：

@RestController
public class HelloController {
    @GetMapping("/hello")
    public String hello() {
        return "Hello, World!";
    }
}

启动后端口被占或想换端口怎么改

改 application.properties 里的 server.port 最直接，但要注意：如果值是字符串（比如写成 server.port="8081"），Spring Boot 会静默失败，端口还是 8080。

使用场景：本地开发时和 Node.js 或其他 Java 进程冲突；CI/CD 环境需固定端口；测试时想快速起多个实例。

• 正确写法：server.port=8081（纯数字，无引号、无空格）
• 临时覆盖：启动命令加参数 --server.port=8082，比配置文件优先级高
• 想随机端口？写 server.port=0，启动后看日志里打印的实际端口（常用于集成测试）
• Windows 下如果提示 “Address already in use”，先用 netstat -ano | findstr :8080 找 PID，再 taskkill /PID xxx /F

为什么返回中文变问号或乱码

根本原因是响应头没设对 Content-Type 的字符集，Spring Boot 默认用 text/plain;charset=ISO-8859-1，而中文需要 UTF-8。

性能影响几乎为零，但兼容性差——浏览器、Postman、curl 都可能显示异常；移动端尤其敏感。

• 最稳妥方式：在 application.properties 加两行：
  server.servlet.encoding.charset=UTF-8
server.servlet.encoding.force=true
• 如果只针对 JSON 接口，确保返回对象是 POJO（不是 String），Spring Boot 会自动用 application/json;charset=UTF-8，无需额外配置
• 千万别在 @GetMapping 上硬写 produces = "text/plain;charset=UTF-8"——这会覆盖默认的 JSON 自动推导

真正卡住人的地方往往不是语法，而是包结构位置、配置项的格式细节、以及 Spring Boot 那些“默认做了但你不知道”的隐式行为。多看启动日志里有没有 “Mapped URL path” 这行，比反复改代码更省时间。

文中关于的知识介绍，希望对你的学习有所帮助！若是受益匪浅，那就动动鼠标收藏这篇《Spring Boot快速搭建RESTful接口实战》文章吧，也可关注golang学习网公众号了解相关技术文章。