很多初学SpringBoot的小伙伴，在做黑马点评等实战项目时，经常搞不懂项目各个文件夹的作用、分包逻辑，以及海量注解的使用场景。
本文以黑马点评hm-dianping项目为例，完整梳理SpringBoot Maven项目的根目录、源码分包结构、资源文件作用，同时分类详解实战高频注解，搭配代码示例和使用场景，新手可直接收藏复用，也可作为项目复盘笔记。
一、SpringBoot Maven项目根目录&核心文件
首先带大家看懂项目最外层根目录的所有文件和文件夹，清楚每一部分的作用，避免开发中误删、误改文件。
hm‑dianping
├── .idea/ # IDEA本地配置，不要提交git，存IDE设置
├── src/ # 源代码核心目录（开发核心）
├── target/ # 编译输出目录，mvn编译后自动生成
├── .gitignore # git忽略配置文件
└── pom.xml # Maven核心配置文件（最重要）
1. pom.xml（核心配置文件 ⭐）
Maven项目的核心配置文件，整个项目的依赖、版本、打包规则全部由它管控，是SpringBoot项目的核心文件。
- 依赖管理：通过
<dependency>标签引入项目所需所有依赖，例如Spring-web、MyBatis-Plus、Redis、MySQL驱动、Lombok等 - 版本管控：统一项目框架、插件、依赖的版本，避免版本冲突
- 打包配置：定义项目打包方式（jar/war）、编译插件、运行插件
- 自动下载依赖：IDEA读取该文件后，自动远程下载对应Jar包到本地仓库
小提示：文件出现黄色漏洞警告，仅为第三方依赖版本存在潜在漏洞，学习实战项目无需处理，生产环境需升级对应依赖版本修复。
2. .gitignore
Git版本控制忽略文件，用于配置不需要提交到代码仓库的文件/文件夹，避免提交本地冗余、配置文件。
常规忽略配置：target编译目录、.idea IDE配置、*.iml本地配置、本地环境配置文件等。
3. target目录
项目编译输出目录，执行mvn compile、mvn package等Maven命令后自动生成。
内部存放编译后的.class字节码文件、测试报告、打包后的Jar包等。
核心特点：可直接删除，重新编译项目会自动生成，禁止手动修改该目录下任何代码。
二、src源码核心目录结构详解
src是项目开发的核心目录，分为main业务源码目录和test单元测试目录，标准实战项目结构如下：
src
├── main # 项目核心业务代码
│ ├── java # Java源代码目录
│ │ └── com.hmdp # 项目根包
│ │ ├── config # 全局配置类包
│ │ ├── controller # 接口控制层
│ │ ├── service # 业务逻辑层（接口+实现类）
│ │ ├── mapper # 数据库持久层
│ │ ├── dto # 数据传输对象
│ │ ├── entity # 数据库实体类
│ │ ├── utils # 通用工具类
│ │ └── HmDianPingApplication.java # 项目启动类⭐
│ └── resources # 静态资源+配置文件目录
│ ├── application.yaml # 全局核心配置文件⭐
│ ├── mapper/ # MyBatis SQL映射文件
│ ├── db/ # 数据库初始化SQL脚本
│ └── unLock.lua # Redis Lua脚本文件
└── test # 单元测试代码目录
└── java/com.hmdp # 项目测试类存放位置
1. src/main/java 分包功能详解
标准三层架构分包，各司其职，是企业级项目通用规范，彻底解耦代码。
| 包名 | 核心作用 |
|---|---|
| controller | 控制层：接收前端所有HTTP请求，解析请求参数，调用对应业务层Service，最终将处理结果封装为JSON返回给前端，所有接口均写在此层 |
| service | 业务逻辑层：核心业务代码编写位置，规范分为业务接口和接口实现类。所有复杂逻辑、数据校验、事务控制、Redis缓存操作、秒杀核心逻辑均在此实现 |
| mapper | 持久层（DAO层） ：基于MyBatis/MyBatis-Plus操作数据库，定义数据库增删改查方法，直接与数据库交互，不处理业务逻辑 |
| entity | 数据库实体类：与数据库数据表一一映射，类的成员变量对应数据表字段，用于封装数据库查询数据 |
| dto | 数据传输对象：专门用于前后端数据交互，区别于entity。可自定义字段，适配前端传参、响应数据格式，无需与数据库表字段一致 |
| config | 全局配置类：存放所有自定义配置，包括Redis配置、MyBatis配置、拦截器配置、WebMvc配置、线程池配置等，统一管理项目全局组件 |
| utils | 通用工具类：存放与业务无关、可全局复用的工具代码，如Redis分布式锁工具、验证码工具、密码加密工具、日期工具等 |
2. src/main/resources 资源文件详解
① application.yaml（核心配置文件 ⭐）
SpringBoot全局配置文件，优先级高于默认配置，用于自定义项目所有环境配置，支持yaml层级缩进格式，常用配置包括端口、数据库、Redis、日志、线程池等。
spring:
# 数据库配置
datasource:
url: jdbc:mysql://localhost:3306/hm_dianping?useSSL=false&serverTimezone=UTC
username: root
password: 123456
# Redis配置
redis:
host: localhost
port: 6379
② mapper/ 目录
存放MyBatis的XML映射文件，用于编写复杂SQL语句（多表联查、分页、复杂条件查询），与mapper接口方法一一对应，实现数据库操作绑定。
③ db/ 目录
存放项目数据库初始化SQL脚本，包含建表语句、基础测试数据插入语句，用于项目初始化部署。
④ 自定义脚本文件
如项目中的unLock.lua，是Redis Lua脚本文件，用于实现分布式锁解锁逻辑，保证并发操作原子性。
3. test测试目录
专门用于编写单元测试代码，可单独测试mapper数据库查询、service业务逻辑、Redis缓存操作等功能，不影响项目正常业务运行，是开发调试的重要工具。
三、SpringBoot实战高频注解大全（核心重点）
本文将实战中99%用到的注解按场景分类，搭配代码示例和使用场景，适配黑马点评秒杀、缓存、分布式锁等核心业务。
1. 项目启动与组件注册注解
@SpringBootApplication
作用：SpringBoot项目启动类专属注解，项目入口标识。
底层组合：@Configuration + @EnableAutoConfiguration + @ComponentScan
使用场景：仅用于项目主启动类，程序通过该类的main方法启动运行。
@Configuration
作用：标记当前类为配置类，交给Spring容器管理，可通过@Bean注册自定义组件。
使用场景：config包下所有自定义配置类。
@Bean
作用：作用于方法上，将方法返回的对象交给Spring容器托管，全局可自动注入使用。
使用场景：配置类中注册第三方组件（RedisTemplate、线程池等）。
@Configuration
public class RedisConfig {
@Bean
public RedisTemplate<String,Object> redisTemplate(){
// 自定义RedisTemplate配置并返回
return new RedisTemplate<>();
}
}
@Component 通用组件注解
将普通类交给Spring容器管理，无专属分层。衍生三个专用分层注解：
@RestController：控制层专用（Web接口）@Service：业务层专用，标记ServiceImpl实现类@Repository：持久层专用（MyBatis项目基本用@Mapper替代）
2. Web接口开发注解（Controller层核心）
@RestController
组合注解：@Controller + @ResponseBody
作用：标记当前类为接口控制层，类中所有方法返回值自动转为JSON格式响应前端，后端接口开发必用。
@RequestMapping / @GetMapping / @PostMapping
@RequestMapping("/xxx")：通用接口路径配置，支持所有请求方式@GetMapping("/xxx")：仅接收GET查询请求@PostMapping("/xxx")：仅接收POST提交请求（新增、登录、秒杀）
参数接收三大核心注解
@RequestParam：接收URL拼接参数（?key=value）
// 访问路径：/user?name=张三
@GetMapping("/user")
public Result getUser(@RequestParam String name){}
@PathVariable：接收路径占位符参数（RESTful风格）
// 访问路径：/user/1001
@GetMapping("/user/{id}")
public Result getUserById(@PathVariable Long id){}
@RequestBody：接收前端JSON请求体（最常用）
用于POST请求，自动将前端JSON数据封装为Java对象。
@PostMapping("/login")
public Result login(@RequestBody LoginFormDTO dto){}
3. MyBatis/MyBatis-Plus数据库注解
@Mapper
作用于mapper接口上，告诉MyBatis当前接口为持久层接口，自动生成代理类，实现数据库操作。
@TableName("表名")
作用于entity实体类，绑定实体类对应的数据库数据表名，解决类名与表名不一致问题。
@TableName("tb_voucher")
public class Voucher {}
@TableId
标记实体类主键字段，常用配置主键自增策略。
@TableId(type = IdType.AUTO)
private Long id;
@Param("参数名")
作用于mapper接口方法参数，为参数起别名，方便XML文件中引用参数。
4. 事务核心注解（秒杀业务重点）
@Transactional
核心作用：开启数据库事务，保证方法内所有数据库操作要么全部成功，要么全部回滚，避免脏数据。
使用场景：黑马点评秒杀下单、订单创建、数据更新等一致性要求高的业务。
注意事项：仅对public修饰的方法生效。
@Service
public class VoucherOrderServiceImpl implements IVoucherOrderService {
@Override
@Transactional
public Result seckillVoucher(Long voucherId) {
// 秒杀核心业务，保证事务一致性
}
}
5. 依赖注入与配置读取注解
@Autowired
自动从Spring容器中匹配对应类型的Bean，完成自动注入，无需手动new对象。
@Autowired
private StringRedisTemplate stringRedisTemplate;
小提示：企业开发推荐构造器注入，IDEA会默认提示优化。
@Value
读取yaml/properties配置文件中的单个配置，注入到成员变量。
@Value("${spring.redis.host}")
private String redisHost;
@ConfigurationProperties
批量读取配置文件中指定前缀的配置，绑定到实体类，适合批量配置管理。
6. Lombok简化代码注解（开发必备）
@Data
作用于实体类，编译期自动生成getter、setter、toString、equals、hashCode方法，彻底简化实体类代码。
配套常用注解：@NoArgsConstructor（无参构造）、@AllArgsConstructor（全参构造）。
@Slf4j
作用于类上，自动创建日志对象，可直接使用log.info()、log.error()打印日志，无需手动声明Logger。
@Slf4j
@Service
public class UserServiceImpl {
public void test(){
log.info("业务执行成功");
}
}
7. AOP与测试注解
@Aspect：标记切面类，用于实现日志记录、权限拦截、方法监控@Before/@After/@Around：切面前置、后置、环绕通知注解@Test：Junit单元测试注解，标记测试方法
8. Spring缓存注解
@Cacheable：查询缓存，优先从缓存取值@CachePut：更新缓存，同步更新缓存数据@CacheEvict：清除缓存，删除过期缓存数据
四、核心总结
-
项目分层核心思想：Controller接收请求 → Service处理业务 → Mapper操作数据库，层层解耦，符合企业开发规范；
-
根目录中
pom.xml和application.yaml是项目两大核心配置文件，掌控项目依赖和环境； -
所有注解各司其职：启动注解管理项目入口、Web注解处理接口请求、数据库注解操作数据、事务注解保证数据一致性、Lombok注解简化开发；
-
黑马点评秒杀、缓存、分布式锁等核心功能，均基于本文目录结构和高频注解实现，掌握后可快速上手所有SpringBoot实战项目。
