SpringBoot的HelloWorld虽然只有寥寥几行代码，但它背后涉及项目构建方式、自动装配机制、内嵌容器和注解扫描等多个知识点。很多初学者照着教程敲完代码能跑起来，却说不清楚为什么这样写，一旦换个环境或者调整目录结构就各种报错。这篇文章从项目创建讲起，把HelloWorld的每个细节掰开揉碎说清楚，并汇总常见的踩坑点，最后给出几道练习题帮助巩固。
一、创建SpringBoot项目的三种常用方式
创建SpringBoot工程最推荐的方式是通过官方的Spring Initializr。访问start.spring.io，选择项目类型（Maven或Gradle）、语言（Java）、SpringBoot版本号，填写Group和Artifact信息，勾选Spring Web依赖，点击生成后下载压缩包，解压后用IDEA或Eclipse导入即可。这种方式生成的项目结构规范，pom.xml配置完整，适合新手。
第二种方式是直接在IDEA中创建。新建项目时选择Spring Initializr，IDEA会调用官方初始化服务，操作流程与网页版基本一致。第三种方式是手工创建Maven项目，然后自己引入spring-boot-starter-parent作为父依赖，再添加spring-boot-starter-web依赖。手工方式能让你更清楚依赖的结构，适合想深入理解构建过程的开发者。
二、HelloWorld示例代码详解
一个最小的HelloWorld应用只需要两个类：启动类和Controller。代码如下：
// 启动类，通常放在根包下
@SpringBootApplication
public class DemoApplication {
public static void main(String[] args) {
SpringApplication.run(DemoApplication.class, args);
}
}
// Controller，处理HTTP请求
@RestController
public class HelloController {
@GetMapping("/hello")
public String hello() {
return "Hello World";
}
}
先看启动类上的@SpringBootApplication注解，它是一个组合注解，内部包含了@SpringConfiguration、@EnableAutoConfiguration和@ComponentScan三个核心注解。其中@ComponentScan默认扫描启动类所在包及其子包下的组件，这就是为什么启动类必须放在根包位置的原因。如果把Controller放在启动类的上层包中，扫描不到，访问接口就会返回404。
再看Controller部分的两个注解。@RestController等价于@Controller加@ResponseBody，表示类中所有方法的返回值直接写入HTTP响应体，而不是跳转视图。@GetMapping("/hello")是@RequestMapping(value="/hello", method=RequestMethod.GET)的缩写形式，用于将GET请求映射到hello方法。启动main方法后，控制台会出现Spring的banner日志和Tomcat started on port 8080字样，浏览器访问http://127.0.0.1:8080/hello即可看到输出。
这里有个容易被忽略的细节：整个项目没有引入任何Tomcat相关配置，却能直接对外提供HTTP服务，这是因为spring-boot-starter-web默认内嵌了Tomcat容器，应用以jar包形式运行时会自动启动内嵌容器。如果想换成Jetty或Undertow，只需要在pom.xml中排除tomcat依赖再引入对应的starter即可。
三、配置文件的使用与常见调整
SpringBoot默认读取src/main/resources目录下的application.properties文件。最常见的需求是修改端口号，配置如下：
# 修改Tomcat端口 server.port=9090 # 设置应用上下文路径，访问时需加上前缀 server.servlet.context-path=/demo
除了properties格式，SpringBoot也支持yml格式。yml使用缩进表示层级关系，书写更简洁，但要注意缩进必须用空格，不能用Tab，且冒号后面必须跟一个空格。两种格式可以共存，但同一目录下application.properties的优先级高于application.yml，实际项目中建议只用一种，避免混乱。
如果同一个项目需要区分开发环境和生产环境配置，可以通过spring.profiles.active来激活不同profile，例如创建application-dev.yml和application-prod.yml，然后在主配置中指定spring.profiles.active=dev，这样打包部署时切换环境只需改一行配置。
四、常见问题与注意事项
第一个高频问题是端口占用。启动时报Port 8080 was already in use，说明端口被其他进程占用了，可以修改server.port，或者用命令行找到占用进程并结束它。Windows下使用netstat -ano | findstr 8080查到进程号，再用taskkill /pid 进程号 /f结束进程。
第二个问题是访问接口返回404。多数原因是Controller不在启动类的扫描范围内，或者启动类位置放错。也有新手误把启动类放在controller包下面，导致其他包的组件扫不到。记住一个原则：启动类放根包，其他类都放在它的子包中。
第三个问题是返回中文乱码。可以在配置文件中设置server.servlet.encoding.charset=UTF-8和server.servlet.encoding.force=true，同时确保源代码文件本身以UTF-8编码保存。另外注意JDK版本与SpringBoot版本的兼容性，SpringBoot 2.x要求JDK 8以上，SpringBoot 3.x则要求JDK 17以上，版本不匹配会在编译阶段就报出各种奇怪的错误。
五、推荐练习题
掌握HelloWorld后，建议通过以下练习巩固知识点：
- 练习一：新增一个接口，通过
@RequestParam接收name参数，返回"你好，xxx"，并处理参数缺失的情况。 - 练习二：将端口改为9090，添加上下文路径/api，验证访问路径的变化。
- 练习三：分别用properties和yml写同样的配置，体会两种格式的差异，并测试二者的优先级。
- 练习四：故意把Controller移到启动类的上层包，观察404现象，再调整回来，加深对包扫描机制的理解。
- 练习五：尝试返回一个自定义对象而不是字符串，观察自动转成JSON的效果，初步体验HttpMessageConverter的作用。
完成这些练习后，你对SpringBoot的基本运行机制会有直观的认识，再往下学习依赖注入、数据库访问和配置绑定等内容时也会顺畅很多。学习任何框架，把第一个程序彻底搞懂永远是性价比最高的一步。
SpringBoot HelloWorldSpringBoot入门SpringBoot示例修改时间：2026-09-06 12:14:31