Spring Boot入门进阶：项目结构、配置文件与依赖注入实战

很多刚接触Spring Boot的朋友，第一天的Hello World跑通之后，第二天往往会陷入一种“接下来学什么”的迷茫。IDEA里那个自动生成的Demo项目，pom文件、启动类、一个空的测试类摆在那里，好像什么都给了，又好像什么都没给。我这篇day02，就专门解决这个断层——把项目结构盘清楚，把配置文件玩明白，把依赖注入这件事弄透彻，再写几个真正能落地的RESTful接口。内容按我实际带新人的顺序来组织，不求快，但求每个环节你都能想通“为什么这样做”，这样后面接触微服务、Spring Cloud这些重型框架时，才不会觉得地基是虚的。这篇适合刚跑通Hello World、对Spring Boot有基本命令行操作能力的读者，如果你连Maven是什么都还不清楚，建议先花半小时把依赖管理的基础概念过一遍再回来。

1. 项目结构规范化——先把手里的代码摆整齐

1.1 标准分层结构长什么样

Spring Boot默认生成的项目里只有一个主启动类和application.properties，业务代码全靠自己往里加。问题就出在这个“自己加”上——没有任何约束的情况下，十个人能写出十种包结构。我以前见过一个模拟项目，所有类都堆在同一个包下面，Controller里直接写SQL查询，Service层完全不存在，三个月后维护成本高到想重构都无从下手。

我这边带新人时，第一件事就是让他们把包结构固定下来。一个比较通用的模板是这样的：

src/main/java/com/你的组织名/你的项目名/ ├── controller // HTTP接口层，只做参数接收、调Service、返回结果 ├── service // 业务逻辑层，接口定义在顶层，Impl放子包 │ └── impl ├── mapper // 数据访问层，操作数据库的接口（或者叫repository） ├── entity // 数据库表映射的实体类 ├── dto // 数据传输对象，接口入参和出参的定义 ├── config // 配置类，比如拦截器、跨域配置 └── common // 通用类，统一返回结果、异常处理、工具类

这套结构不是Spring Boot强制的，而是社区多年实践沉淀下来的经验。核心思想很简单：按职责划分包，让每一层的代码只干一件事。Controller不碰数据库，Service不处理HTTP协议细节，Mapper只负责和数据库打交道，这样哪一层出了问题，你只需要去对应的包里找，改起来也不会牵一发动全身。

1.2 主启动类的位置为什么不能乱放

很多人不知道，主启动类的位置其实是有讲究的。单个Spring Boot项目的标准做法是把主启动类放在最外层目录下，也就是com.xxx.yyy这个包的根部，比如com.example.demo.DemoApplication。原因在于，启动类上标注的@SpringBootApplication注解会自动扫描“当前包及其子包”下的所有Spring组件。

如果把启动类放在com.example.demo这个包下，而某个Controller放在com.example.controller包里，这个Controller就处于启动类所在包的外面，扫描不到，启动不报错，但接口404。这类问题排查起来相当隐蔽，新人经常被绕进去半小时出不来。

我习惯的做法是：启动类放在src/main/java/com/自己的前缀/项目名/这个层级，业务代码都写在它下面。举个例子，启动类是com.xcoder.shop.ShopApplication，那么controller包就是com.xcoder.shop.controller，service包就是com.xcoder.shop.service，以此类推。这样做的好处有两个：第一，满足自动扫描的默认规则，不用额外配置@ComponentScan；第二，包名结构清晰，谁一看就知道这个类属于哪个模块。

注意：如果项目以后要拆多模块，情况会复杂一些，届时需要显式配置@ComponentScan指定扫描路径，或者用@SpringBootApplication(scanBasePackages = "com.xxx")来做。单体阶段，遵循“启动类在顶层，业务代码在下面”这个最简原则即可。

2. 配置文件进阶——application.yml的正确打开姿势

2.1 yml和properties怎么选

Day01生成的默认配置文件是application.properties，里面只有一行spring.application.name之类的信息。我建议你从day02开始，果断切换到application.yml。原因是properties格式的配置只有“扁平”的键值对，配置一多就靠前缀层层堆叠，比如spring.datasource.url、spring.datasource.username，要扫一眼定位某个配置，眼睛容易看花。

yml格式用缩进表达层级关系，同样的内容写出来是这样：

spring: application: name: demo-project datasource: url: jdbc:mysql://localhost:3306/test_db username: root password: 123456

缩进关系一眼就能看出datasource是spring的子级，阅读效率高很多。但yaml有一个必须注意的坑：缩进不能用Tab，只能用空格，且同一层级要对齐。第一次用yaml的人，十有八九会被这个坑折磨——启动时报YamlPropertiesConfigurationException，然后发现是某个地方多了一个空格或少了一个空格。

2.2 多环境配置：local、test、prod怎么切

实际开发中，开发环境、测试环境、生产环境的配置肯定不一样。数据库地址不同、日志级别不同、Redis连接不同，最原始的做法是每次发布前手动改配置文件——风险极大，漏改一个配置就能让生产环境连上开发库。

正确做法是拆分多环境配置。Spring Boot支持用application-{环境名}.yml做配置文件分离，比如：

• application.yml：公共配置，以及当前激活环境的选择
• application-dev.yml：开发环境配置
• application-test.yml：测试环境配置
• application-prod.yml：生产环境配置

在application.yml里通过spring.profiles.active激活对应环境：

spring: profiles: active: dev

启动的时候想切到生产环境，不用改文件，命令行加参数即可：

java -jar demo-0.0.1.jar --spring.profiles.active=prod

这个机制的价值在于，环境切换从“改代码”变成了“改参数”。部署的人不需要懂代码，只需要在启动命令里指定用哪个profile。配合打包时排除多余的配置文件，也能避免把开发配置带到生产环境。

2.3 自定义配置项的正确玩法

除了用Spring Boot预定义的配置，业务中经常需要自定义一些配置项，比如某个接口的超时时间、某个功能的开关。最常见的错误是把这些配置直接写死在代码里，写死后的直接后果是改配置要改代码重新编译打包。

自定义配置项的标准玩法我看有两个级别：

第一个级别是@Value注解，适合单个或几个零散的配置：

@Service public class OrderService { @Value("${order.timeout:5000}") private int timeout; }

写法里那个5000是默认值，如果配置文件中没有order.timeout这个key，就用5000兜底。这里要注意，@Value能用在任何Spring管理的Bean中，但它对复杂结构的支持很差，比如一个包含多个属性的对象，用@Value要写好几行。

第二个级别是@ConfigurationProperties，适合有结构的一组配置。比如支付相关的配置可能有appId、私钥、回调地址等多个字段，可以定义一个配置类：

@Component @ConfigurationProperties(prefix = "pay") public class PayProperties { private String appId; private String privateKey; private String callbackUrl; // getters and setters 必须写，否则绑定不进来 }

然后yml里面对应写：

pay: app-id: wx123456 private-key: xxxx callback-url: https://api.demo.com/pay/callback

注意两点：第一，用@ConfigurationProperties时，类必须提供getter和setter方法，Spring是通过Setter方法进行绑定的；第二，yml里的kebab-case命名（app-id）自动映射到驼峰属性名（appId），这个映射规则是默认支持的。

3. 依赖注入——把创建对象这件事交给容器

3.1 控制反转到底反转了什么

很多教程一上来就讲概念，IoC、DI、容器一堆术语，新手听完更晕了。我更喜欢用生活场景来类比。你去餐厅吃饭，不需要自己买食材、不需要自己颠勺炒菜，只需要跟服务员点单，后厨自然会做。这里餐厅就是“容器”，你只管声明“我要什么”，不用关心食材怎么来的、菜是怎么炒的。

对应到Spring里，以前没有IoC时，Service里要使用Mapper，得自己new一个实例，对象之间的依赖关系散落在代码各处，一改实现类就要到处找人。有了IoC容器之后，你在类里声明一个依赖，Spring看到后自动把对应的对象实例化好、注入进来。依赖创建和查找的职责从程序员手里转移给了容器，这件事就叫控制反转。

看个最直观的对比。没有依赖注入的写法：

public class OrderService { private OrderMapper orderMapper = new OrderMapper(); }

有依赖注入的写法：

@Service public class OrderService { private final OrderMapper orderMapper; public OrderService(OrderMapper orderMapper) { this.orderMapper = orderMapper; } }

第二段代码里，OrderMapper是谁创建的？你不需要管，Spring容器会创建好并填进来。代码之间不再硬生生地“new”在一起，而是通过接口和声明连接，耦合度大幅下降。这也是为什么Spring构建的微服务能拆能合，模块边界清晰。

3.2 三种注入方式的取舍

Spring支持三种管理方式：字段注入、构造器注入、Setter注入。用的最多的是第一种，也就是直接在字段上加@Autowired，很多培训视频也是这么教的——短、少写几个方法。但实际工程中，我逐步转向了构造器注入：

@RestController public class UserController { private final UserService userService; public UserController(UserService userService) { this.userService = userService; } }

构造器注入的最大优点是保证对象状态的完整性，依赖在创建时就固定下来，后期不可能被替换或遗漏。字段注入的缺点是，测试时想换个Mock依赖比较别扭，因为字段是私有的，只能反射去改。构造器注入在写单元测试时就舒服多了，直接把Mock对象传进去就行。

还有个细节：如果类只有一个构造器，Spring会自动选择这个构造器进行注入，不需要加@Autowired注解，这是Spring 4.3以后的行为。如果你看到别人的代码里构造器上还带着@Autowired，也别觉得奇怪，那是老版本的写法习惯。

Setter注入现在用的场景不多，主要用来解决“依赖不是创建时必须的、但后续可能被修改”这种需求。日常开发中记住一个原则：优先构造器注入，特殊场景用字段或Setter，基本不会出错。

3.3 循环依赖：一个真实的实际坑

说循环依赖之前，先交代一个背景：Spring Boot 2.6版本之后，默认禁止了循环依赖，启动时检测到直接报错。消息长这样：

The dependencies of some of the beans in the application context form a cycle

什么场景会触发？最典型的是两个Service互相调用。比如OrderService要调用UserService查询用户信息，而UserService要调用OrderService查询订单信息。你可能会想：我写的时候没觉得有什么问题啊，代码能编译能运行，为什么Spring不让我过？

实际上Spring 2.6之前是宽容的，能处理两级循环依赖，但容器内部要采用提前暴露对象引用的机制，会让Bean的生命周期变得很微妙。Spring框架团队考虑到这个特性带来的复杂度和潜在风险，干脆在新版本里默认关闭了支持。

遇到循环依赖，排错思路有三个层次。第一层，检查是不是设计问题——两个Service互相调用，通常意味着业务边界没划清楚，可以尝试把互相调用的公共逻辑下沉到第三个组件，让两个Service各自调用它。第二层，使用@Lazy注解打破循环，比如在其中一个依赖注入处加@Lazy，让容器先注入代理对象，调用时才真正去解析。第三层，实在不想改代码，可以在配置里打开spring.main.allow-circular-references=true，但我不推荐这么做。

我实际经验是，90%的循环依赖都是设计问题导致的。先停下来审视业务逻辑，比找解决办法更重要。

4. RESTful接口开发——让Controller真正干活

4.1 REST风格设计最容易犯的错

现在做Web开发，接口基本都按RESTful风格来设计，核心是用HTTP方法表达操作意图：

• GET：查询资源
• POST：新增资源
• PUT：更新资源
• DELETE：删除资源

很多同学设计的接口是这样的：

POST /getUser // 查询用户，却用了POST POST /deleteUser // 删除用户，却用了POST GET /updateUser // 更新用户，却用了GET

URL看着像动词，方法却和语义对不上。这是个典型误区。RESTful设计的重点是用名词表达资源，用HTTP方法表达操作。正确示例：

我见过不少团队在“REST风格”这件事上走火入魔，把业务动作硬扯成资源嵌套，比如把“用户下单”设计成POST /users/{id}/orders，好像资源URL必须层层嵌套才叫REST。问题是，过度嵌套会让URL变得很长很难维护。实际项目里，REST风格作为指导原则没错，但遇到复杂的业务动作（比如批量审核、发布操作），直接用带动词的Endpoint也不算错误。工程上的最佳实践是：大部分接口遵循RESTful风格，极少数动作型接口允许例外。

4.2 接口参数接收的完整案例与易错点

一个Controller要接收前端传的参数，场景无非就那么几种：查询参数拼在URL后面、参数嵌在URL路径里、JSON数据放在请求体里。Spring Boot对这三种都有对应的写法，但很多人会混。

写一个完整示例来演示：

@RestController @RequestMapping("/api/users") public class UserController { @GetMapping public Result list(@RequestParam(defaultValue = "1") int page, @RequestParam(defaultValue = "10") int size) { // 处理分页查询 return Result.success(); } @GetMapping("/{id}") public Result detail(@PathVariable Long id) { // 按ID查询 return Result.success(); } @PostMapping public Result create(@RequestBody UserCreateDTO createDTO) { // 解析请求体中的JSON并创建用户 return Result.success(); } }

这里的三个注解，各有各的坑。

@RequestParam取的是URL上的查询参数，比如/api/users?page=1&size=10。注意defaultValue属性的用法——如果前端没传page，不会报错，直接用默认值。

@PathVariable取的是路径里{id}那一段。路径变量名和方法参数名不一致时，必须写全注解名称，比如@PathVariable("id") Long userId。Spring Boot的编译参数里如果配了-parameters，同名时可以省略，但我建议别依赖这个特性，显式写清楚最稳妥。

@RequestBody接收的是请求体里的JSON。这里最常见的错误是前端传的不是JSON而是表单格式（x-www-form-urlencoded），用@RequestBody接会直接抛异常，报HttpMessageNotReadableException。表单格式应该用@RequestParam或者定义一个对象直接接收。

还有一个容易被坑的点：POST请求不传Content-Type或Content-Type不对，Spring解析JSON会失败。前端排查问题时要先确认请求头里有没有Content-Type: application/json，再来看后端代码。

4.3 统一返回结果这事，越早做越好

如果每个Controller方法返回的类型都不一样——有的返回String，有的返回Map，有的直接返回Entity——前后端联调的时候，前端就惨了。他们没法做一层统一的拦截处理，每个接口都要单独适配返回结构。

更麻烦的是异常处理。接口执行业务时出了错，如果不想让前端看到默认的500错误页，就得在Controller里try-catch，然后包装成特定格式返回。每个业务方法都写一遍try-catch，代码冗余到发疯。

工程上普遍的做法是定义统一返回体。一个精简但够用的Result类大致长这样：

public class Result<T> { private int code; // 状态码：200成功，其他失败 private String message; // 提示信息 private T data; // 业务数据 public static <T> Result<T> success(T data) { Result<T> result = new Result<>(); result.code = 200; result.message = "success"; result.data = data; return result; } public static <T> Result<T> error(int code, String message) { Result<T> result = new Result<>(); result.code = code; result.message = message; return result; } }

Controller返回的类型统一成Result<T>之后，前端得到了固定结构，处理起来非常省事。再配合一个@RestControllerAdvice做全局异常处理，业务代码里完全不用写catch，异常都被统一拦截并转换成Result格式返回。

这套组合拳做下来，接口层就干净了——Controller只管收参数和返回结果，真正的业务逻辑和异常处理都有明确的归属地。

5. 分层设计——Controller瘦身与职责划分

5.1 Service层存在的意义到底是什么

很多人刚学Spring Boot时会觉得Service层是多余的，Controller直接写逻辑它不香吗？项目一旦复杂起来，“直接写在Controller”的写法就成了灾难的起点。

先看一个Controller直写数据库操作的反例：

@RestController @RequestMapping("/api/users") public class UserController { @Autowired private JdbcTemplate jdbcTemplate; @GetMapping("/{id}") public User detail(@PathVariable Long id) { // 直接在这里写SQL查询逻辑 return jdbcTemplate.queryForObject("select * from user where id = ?", new Object[]{id}, User.class); } }

功能是能跑，但问题很多：查询逻辑写在Controller里，无法复用，另一个Controller要按用户名查询就得再写一遍；没有事务管理，多个数据库操作组合时无法保证原子性；Controller代码越来越长，最后上千行都有，读起来极其痛苦。

Service层要解决的问题，就是把业务逻辑从Controller里抽出来，让它成为独立可复用的一层。Controller只保留“接收参数、调用Service、返回结果”的功能：

@RestController @RequestMapping("/api/users") public class UserController { private final UserService userService; public UserController(UserService userService) { this.userService = userService; } @GetMapping("/{id}") public Result<UserVO> detail(@PathVariable Long id) { return Result.success(userService.getUserById(id)); } }

Service层负责的业务逻辑，包括参数校验、复杂规则计算、事务管理、多个数据源组合查询等。事务边界也应当划在Service这一层，加@Transactional注解时加在Service方法上，而不是Controller方法上。

5.2 实体类、DTO、VO的分工逻辑

分层设计逃不开一个经典问题：数据库实体、接口入参、接口出参到底要分成几个类？

我见过某些项目的做法是：一个User类从数据库到接口返回都用它，字段很多，包括password、salt这些敏感信息，接口返回的时候直接把User全字段都甩给前端了。密码字段跟着响应体暴露在HTTP里，光想到这一点就觉得后怕；更别说数据库字段和前端需要的展示格式经常不一样，硬用同一个类会让代码越来越别扭。

规范一点的做法是三类角色分开：

• Entity（实体类）：对应数据库表结构，一个字段对应一个列，放在entity包下
• DTO（数据传输对象）：接口接收的入参，定义在dto包下，比如UserCreateDTO
• VO（视图对象）：接口返回给前端的数据结构，定义在vo包下，比如UserVO

写一段转换代码示意：

public class UserVO { private Long id; private String username; private String nickname; private String avatar; }

Service查询完用户后，需要把Entity转换成VO，排除掉password字段。转换方式最直接的是手写setter，或者用工具类（项目中可以用MapStruct，但这里不做展开）。原则是：各个层用适合自己角色的模型，不跨层混用。

很多新手会说“这不增加了很多代码量吗”。实际上增加的代码量很少，省下的麻烦却很多——改数据库表结构时不用重新跟前端对接口，前端展示变化时也不用动数据库实体。边界越清晰，后续维护越轻松。

6. 常见问题与排查技巧实录

6.1 启动失败的三大原因

Spring Boot应用启动失败的排查，是入门阶段必过的一道关。我整理了三个最高频的原因，你在实际开发中大概率会轮流踩一遍。

第一个是端口被占用。默认情况下Spring Boot的Web应用占8080端口，你之前启动过没关掉、或者开了其他服务占用了8080，就会报：

Web server failed to start. Port 8080 was already in use.

解决方案有三个：第一，找到占用程序，关掉它；第二，把配置文件的server.port改成别的端口；第三，用随机端口server.port=0（但这个只在测试时有用）。要注意的是，换个端口后，前端请求的地址也要跟着变，不要让前后端端口对不上。

第二个是Bean找不到。日志报NoSuchBeanDefinitionException或者UnsatisfiedDependencyException。原因多数是某个类忘记加注解（@Component、@Service、@Repository等），或者类放在了主启动类的包扫描范围之外。排查思路：先检查注解，再检查包结构。

第三个是数据库连接失败，一旦配置文件里配了数据源，Spring Boot启动时会尝试初始化连接池，如果数据库没启动或密码不对，启动就会中断。排查方式很直白，检查数据库服务是否在运行、账号密码是否正确、URL有没有写错，比如localhost和127.0.0.1在某些环境下的表现也会不一样。

6.2 配置不生效的排查思路

“我改了配置文件，但运行结果没变”，这个问题被问了无数遍。排查这类问题，先确认一个有顺序的清单：

1. 改的是不是正在生效的文件。项目里可能有多个配置文件，application.yml和application.properties同时存在时，properties优先级更高。
2. 缩进是否正确。yaml里少一个空格，配置就静默不生效，不报错，但值读不出来。
3. 是否被多环境配置覆盖。你改的是application-dev.yml，但激活的环境是prod，那你的改动当然不会生效。
4. 是否启动了配置缓存机制。Spring Cloud的配置中心客户端会缓存远程配置，本地调试时会看到旧值。

还有一个debug技巧：在配置类上加上@ConfigurationProperties之后，可以在启动日志里打开配置检查器，或者简单粗暴地在代码里打个断点，看看属性值有没有被正确绑定。如果绑定不上，优先检查setter方法和前缀拼写。

6.3 接口中文返回值乱码

这个坑看起来小，踩起来很痛。接口返回的中文乱码，本质是编码不一致的问题。Spring Boot的HTTP消息转换默认用UTF-8输出，但如果框架检测到的请求头里没有指定charset，不同版本的Spring Boot表现会有细微差别。

我自己碰到的情况是这样的：接口返回的JSON里中文全部变成问号（????）。排查后发现是配置文件里显式写了一个非UTF-8的字符集设置。另外还有一个场景，数据库里的中文读出来乱码——这种情况通常是TDD没有修对，或者数据库连接URL里没加characterEncoding=utf8参数。

排查建议按顺序来：请求响应头里Content-Type是不是application/json且带不带charset=UTF-8；配置文件里有没有手工指定过server.servlet.encoding.*；最后检查数据库连接URL。

6.4 热部署，早点装上省心很多

每次改代码都要手动重启，尤其在调试Controller参数绑定时，半天时间都耗在等待重启上了。这里强烈建议引入spring-boot-devtools，它能实现代码变更后自动重启（是重启，不是热替换JVM），让开发节奏快不少。

pom.xml加依赖即可：

<dependency> <groupId>org.springframework.boot</groupId> <artifactId>spring-boot-devtools</artifactId> <optional>true</optional> </dependency>

需要注意几个细节。第一，IDEA里默认可能不会自动编译，需要打开Build > Build Project快捷键（Ctrl+F9）手动触发编译，devtools检测到编译后的类变化才会重启。第二，devtools的自动重启只对src/main下的文件生效，对pom.xml这类配置文件的修改不会触发重启，改完还是要手动重启一次。第三，生产环境打包时devtools不会被打进去，因为optional标记了，不需要额外处理。

我自己的体验是，devtools让日常调试节约的时间至少在40%以上。配合IDEA里的热部署快捷键，改完方法体手一松，项目两秒内自动重启，接口测试才能进入“改一行、验一次”的舒适节奏。

结尾

最后说个我反复在新人身上看到的现象：很多人学Spring Boot，看视频觉得啥都懂了，自己一动手就卡壳，卡在注解不生效、配置绑定不上、依赖循环这些地方。我写这篇day02，刻意把内容收敛到“项目结构、配置、依赖注入、REST接口、分层设计”这五个最常用的知识底座上。如果你能把这篇里的Demo都亲手敲一遍——不是复制粘贴，而是看着思路自己写——再回到业务里写代码，思路会比之前清晰得多。下一步我建议你把统一返回结果和全局异常处理再深入做一做，然后把一个CURD案例完整落成代码，那才算是把day02的内容真正消化掉了。下一篇会聊实体映射和数据库操作。到时候再看。