第一篇：入门篇 — 认识 Spring Boot 与基础开发

目标 ：能独立创建 Spring Boot 项目，写出基础 REST 接口
学习时长 ：1～2 周
前置要求：Java 基础、Maven/Gradle 基础、HTTP 协议了解

---

目录

1. [Spring Boot 是什么](#Spring Boot 是什么)
2. [Spring、Spring MVC、Spring Boot 的关系](#Spring、Spring MVC、Spring Boot 的关系)
3. [第一个 Spring Boot 项目](#第一个 Spring Boot 项目)
4. 项目结构说明
5. [application.yml 配置文件](#application.yml 配置文件)
6. [Controller、Service、Repository 分层](#Controller、Service、Repository 分层)
7. [REST API 开发基础](#REST API 开发基础)
8. 常用注解入门
9. [接口测试工具 Postman](#接口测试工具 Postman)
10. [简单 CRUD 实战](#简单 CRUD 实战)
11. 面试高频题

---

1. Spring Boot 是什么

Spring Boot 是由 Pivotal 团队开发的开箱即用的 Spring 应用快速构建框架，于 2014 年发布。

核心设计哲学

哲学	说明
约定优于配置	提供合理默认值，减少配置量
开箱即用	Starter 依赖自动装配，无需手动配置
独立运行	内嵌 Tomcat/Jetty，打成 Jar 直接运行
生产就绪	Actuator 提供健康检查、监控、指标等

Spring Boot 解决了什么问题

传统 Spring 项目的痛点：

- 繁重的 XML 配置（applicationContext.xml、web.xml）
- 依赖版本冲突
- 部署需要外部 Tomcat
- 环境搭建成本高

Spring Boot 的解决方案：

✅ 注解替代 XML，自动配置替代手动配置
✅ Starter BOM 统一管理依赖版本
✅ 内嵌服务器，jar 包一键启动
✅ Spring Initializr 30 秒生成项目骨架

---

2. Spring、Spring MVC、Spring Boot 的关系

┌─────────────────────────────────────────┐
│           Spring Boot                    │  ← 自动配置层（整合者）
│  ┌───────────────────────────────────┐  │
│  │         Spring MVC                │  │  ← Web 层框架
│  │  ┌─────────────────────────────┐ │  │
│  │  │       Spring Core           │ │  │  ← IoC/DI/AOP 核心
│  │  └─────────────────────────────┘ │  │
│  └───────────────────────────────────┘  │
└─────────────────────────────────────────┘

框架	定位	核心能力
Spring Core	基础框架	IoC 容器、DI 依赖注入、AOP 面向切面
Spring MVC	Web 框架	DispatcherServlet、Controller、视图解析
Spring Boot	整合框架	自动配置、Starter、内嵌服务器、Actuator

📌 一句话记忆：Spring 是地基，Spring MVC 是楼，Spring Boot 是装修好的精装房。

---

3. 第一个 Spring Boot 项目

方式一：Spring Initializr（推荐）

访问 https://start.spring.io：

Project：Maven
Language：Java
Spring Boot：3.2.x
Java：17
Dependencies：Spring Web、Lombok

方式二：IDEA 内置向导

File → New → Project → Spring Initializr

最简启动类

@SpringBootApplication  // = @Configuration + @EnableAutoConfiguration + @ComponentScan
public class DemoApplication {
    public static void main(String[] args) {
        SpringApplication.run(DemoApplication.class, args);
    }
}

Hello World Controller

@RestController  // = @Controller + @ResponseBody
public class HelloController {

    @GetMapping("/hello")
    public String hello(@RequestParam(defaultValue = "World") String name) {
        return "Hello, " + name + "!";
    }
}

启动验证

mvn spring-boot:run
# 访问：http://localhost:8080/hello?name=SpringBoot
# 返回：Hello, SpringBoot!

---

4. 项目结构说明

my-project/
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/example/demo/
│   │   │       ├── DemoApplication.java      ← 启动类（放在最外层包）
│   │   │       ├── controller/               ← 接收请求，参数校验
│   │   │       │   └── UserController.java
│   │   │       ├── service/                  ← 业务逻辑
│   │   │       │   ├── UserService.java      ← 接口
│   │   │       │   └── impl/
│   │   │       │       └── UserServiceImpl.java ← 实现类
│   │   │       ├── repository/               ← 数据访问
│   │   │       │   └── UserRepository.java
│   │   │       ├── entity/                   ← 数据库实体
│   │   │       │   └── User.java
│   │   │       ├── dto/                      ← 数据传输对象（入参）
│   │   │       ├── vo/                       ← 视图对象（出参）
│   │   │       └── config/                   ← 配置类
│   │   └── resources/
│   │       ├── application.yml               ← 主配置文件
│   │       ├── application-dev.yml           ← 开发环境配置
│   │       ├── application-prod.yml          ← 生产环境配置
│   │       ├── static/                       ← 静态资源（css/js/img）
│   │       └── templates/                    ← 模板文件（Thymeleaf）
│   └── test/
│       └── java/                             ← 单元测试
└── pom.xml                                   ← Maven 依赖管理

⚠️ 注意 ：启动类必须放在所有包的最外层 ，否则 @ComponentScan 扫描不到子包

---

5. application.yml 配置文件

基础配置

server:
  port: 8080                    # 服务端口
  servlet:
    context-path: /api          # 应用根路径

spring:
  application:
    name: my-service            # 应用名（服务注册、链路追踪会用到）

  datasource:
    url: jdbc:mysql://localhost:3306/mydb?useUnicode=true&characterEncoding=utf8
    username: root
    password: root123
    driver-class-name: com.mysql.cj.jdbc.Driver

  jpa:
    hibernate:
      ddl-auto: update          # none/validate/update/create/create-drop
    show-sql: true

logging:
  level:
    com.example: DEBUG          # 包级别日志
    org.hibernate.SQL: DEBUG    # 打印 SQL

Properties vs YAML 对比

# application.properties（传统写法）
server.port=8080
spring.datasource.url=jdbc:mysql://localhost:3306/db

# application.yml（层级结构，推荐）
server:
  port: 8080
spring:
  datasource:
    url: jdbc:mysql://localhost:3306/db

@Value 读取配置

@Value("${spring.application.name}")
private String appName;

@Value("${server.port:8080}")  // 有默认值
private int port;

@ConfigurationProperties 批量绑定（推荐）

@Data
@Component
@ConfigurationProperties(prefix = "app.oss")
public class OssProperties {
    private String endpoint;
    private String accessKey;
    private String secretKey;
    private String bucket;
}

app:
  oss:
    endpoint: https://oss-cn-hangzhou.aliyuncs.com
    access-key: LTAI5t...
    secret-key: abc123...
    bucket: my-bucket

---

6. Controller、Service、Repository 分层

三层架构职责

请求 → Controller → Service → Repository → Database
                ↑               ↑
            参数校验         业务逻辑        数据访问

层	注解	职责	禁止事项
Controller	@RestController	接收请求、参数校验、调用 Service	不写业务逻辑
Service	@Service	业务逻辑、事务控制	不写 SQL
Repository	@Repository	数据库访问	不写业务逻辑

标准代码结构

// Controller 层：只做参数校验和调用 Service
@RestController
@RequestMapping("/api/users")
@RequiredArgsConstructor
public class UserController {
    private final UserService userService;

    @PostMapping
    public Result<User> create(@Valid @RequestBody CreateUserDTO dto) {
        return Result.success(userService.createUser(dto));
    }
}

// Service 层：核心业务逻辑
@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {
    private final UserRepository userRepository;

    @Transactional
    public User createUser(CreateUserDTO dto) {
        // 业务校验
        if (userRepository.existsByEmail(dto.getEmail())) {
            throw new BusinessException("邮箱已存在");
        }
        // 转换 + 保存
        User user = BeanUtils.copyProperties(dto, User.class);
        return userRepository.save(user);
    }
}

// Repository 层：只做数据访问
public interface UserRepository extends JpaRepository<User, Long> {
    boolean existsByEmail(String email);
}

---

7. REST API 开发基础

HTTP 方法与 CRUD 对应关系

HTTP 方法	操作	示例	状态码
GET	查询	GET /users / GET /users/1	200
POST	新增	POST /users	201
PUT	全量更新	PUT /users/1	200
PATCH	部分更新	PATCH /users/1	200
DELETE	删除	DELETE /users/1	204

RESTful URL 设计规范

✅ 正确
GET    /api/v1/users          查询用户列表
GET    /api/v1/users/1        查询单个用户
POST   /api/v1/users          创建用户
PUT    /api/v1/users/1        更新用户
DELETE /api/v1/users/1        删除用户
GET    /api/v1/users/1/orders 查询用户的订单

❌ 错误（动词放在 URL 中）
GET /api/getUser?id=1
POST /api/createUser
POST /api/deleteUser?id=1

参数接收方式

// 1. 路径参数：/users/1
@GetMapping("/users/{id}")
public User getUser(@PathVariable Long id) { ... }

// 2. 查询参数：/users?page=1&size=10
@GetMapping("/users")
public Page<User> listUsers(
    @RequestParam(defaultValue = "0") int page,
    @RequestParam(defaultValue = "10") int size) { ... }

// 3. 请求体（JSON）：POST /users  Body: {...}
@PostMapping("/users")
public User createUser(@RequestBody @Valid CreateUserDTO dto) { ... }

// 4. 请求头
@GetMapping("/profile")
public User getProfile(@RequestHeader("Authorization") String token) { ... }

---

8. 常用注解入门

组件注解

注解	作用
@SpringBootApplication	启动类，组合注解（扫描+配置+自动装配）
@Component	通用组件，注册为 Bean
@Controller	Web 控制器，返回视图
@RestController	RESTful 控制器，返回 JSON
@Service	业务层组件
@Repository	数据访问层组件
@Configuration	配置类，等价于 XML 配置文件

注入注解

注解	作用
@Autowired	按类型注入（Spring 原生）
@Resource	按名称注入（JDK 标准）
@Qualifier	配合 @Autowired，指定 Bean 名称
@Value	注入配置文件的值

请求映射注解

注解	等效
@RequestMapping	通用映射
@GetMapping	@RequestMapping(method = GET)
@PostMapping	@RequestMapping(method = POST)
@PutMapping	@RequestMapping(method = PUT)
@DeleteMapping	@RequestMapping(method = DELETE)

---

9. 接口测试工具 Postman

基本使用

1. 下载安装：https://www.postman.com
2. 新建请求：New → HTTP Request
3. 选择方法（GET/POST/PUT/DELETE）
4. 输入 URL

发送 JSON 请求体

Method: POST
URL: http://localhost:8080/api/v1/users
Headers:
  Content-Type: application/json
Body (raw JSON):
{
  "username": "zhangsan",
  "email": "zhangsan@example.com",
  "age": 25
}

使用环境变量

Environment: dev
{{base_url}} = http://localhost:8080

请求 URL: {{base_url}}/api/v1/users

常用内置工具

• Swagger UI （推荐）：访问 http://localhost:8080/swagger-ui.html 在线测试
• IntelliJ HTTP Client ：.http 文件，直接在 IDEA 中测试
• curl：命令行测试

# GET 请求
curl http://localhost:8080/api/v1/users

# POST JSON
curl -X POST http://localhost:8080/api/v1/users \
  -H "Content-Type: application/json" \
  -d '{"username":"test","email":"test@example.com"}'

---

10. 简单 CRUD 实战

本章 Demo 对应 chapter01-quickstart 模块，实现了完整的用户 CRUD。

核心接口清单

方法	路径	描述
GET	/api/v1/users?page=0&size=10	分页查询用户
GET	/api/v1/users/{id}	查询单个用户
POST	/api/v1/users	创建用户
PUT	/api/v1/users/{id}	更新用户信息
DELETE	/api/v1/users/{id}	删除用户（软删除）
GET	/api/v1/users/search?keyword=xx	搜索用户

启动 Demo

cd springboot-demo/chapter01-quickstart
mvn spring-boot:run

# 访问 Swagger：http://localhost:8081/swagger-ui/index.html
# 访问 H2 控制台：http://localhost:8081/h2-console
#   JDBC URL: jdbc:h2:mem:chapter01db

---

11. 面试高频题

Q1：Spring Boot 和 Spring 的区别是什么？

Spring Boot 是对 Spring 的封装，提供自动配置、Starter 依赖管理和内嵌服务器，让开发者专注业务代码，无需写大量配置。

Q2：@SpringBootApplication 包含了哪些注解？

三个：@SpringBootConfiguration（等价于 @Configuration）、@EnableAutoConfiguration（开启自动装配）、@ComponentScan（包扫描）。

Q3：Spring Boot 支持哪些内嵌服务器？

默认 Tomcat，可以切换为 Jetty 或 Undertow，只需排除 Tomcat 依赖并引入对应 Starter。

Q4：@RestController 和 @Controller 的区别？

@RestController = @Controller + @ResponseBody，前者直接返回 JSON，后者用于返回视图（如 Thymeleaf 模板）。

Q5：Spring Boot 的 application.yml 和 application.properties 有什么区别？

功能相同，YAML 支持层级结构、列表更简洁，可读性更好，推荐使用 YAML。

Q6：如何读取 application.yml 中的配置？

有三种方式：@Value 单个注入、@ConfigurationProperties 批量绑定、Environment.getProperty() 编程式读取。

Q7：Spring Boot 的启动流程是什么？

SpringApplication.run() → 加载配置 → 创建 ApplicationContext → 刷新容器（Bean 实例化、自动配置）→ 触发 ApplicationReadyEvent → 启动完成。

Q8：@ComponentScan 默认扫描哪个包？

扫描启动类所在包及其所有子包，这也是为什么启动类要放在最外层包的原因。

Q9：@Autowired 和 @Resource 的区别？

@Autowired 是 Spring 注解，默认按类型注入；@Resource 是 JDK 标准注解，默认按名称注入。构造器注入推荐用 @RequiredArgsConstructor（Lombok）。

Q10：为什么推荐构造器注入而不是字段注入？

构造器注入：依赖不可变（final）、依赖不可为空、便于单元测试（不依赖 Spring 容器）、能发现循环依赖。字段注入隐藏了依赖关系，不利于测试。

---

下一篇：02_核心篇_SpringBoot常用开发能力.md

---

12. Spring Boot Actuator 详解（专家必知）

知识点 1：Actuator 是什么，能做什么

Spring Boot Actuator 提供了一套生产就绪的监控和管理端点，让运维和监控系统可以实时观察应用状态，无需改代码。

核心端点一览：

端点	地址	说明
health	/actuator/health	应用健康状态（含DB/Redis/MQ等组件）
info	/actuator/info	应用信息（版本、构建时间等）
metrics	/actuator/metrics	性能指标（JVM内存、GC、HTTP请求数）
env	/actuator/env	当前所有环境变量和配置
loggers	/actuator/loggers	动态修改日志级别（运行时无需重启）
threaddump	/actuator/threaddump	线程快照（排查死锁/阻塞）
heapdump	/actuator/heapdump	下载堆内存转储文件
prometheus	/actuator/prometheus	Prometheus格式指标（需引入依赖）

知识点 2：生产环境安全配置

⚠️ 默认只暴露 health 和 info，其余端点需显式配置。生产环境切勿全量暴露。

management:
  endpoints:
    web:
      exposure:
        # 生产推荐：只暴露必要端点
        include: "health,info,metrics,prometheus,loggers"
        # 开发调试时可以全部暴露
        # include: "*"
  endpoint:
    health:
      show-details: when-authorized  # 认证后才显示详情
      show-components: always
    loggers:
      enabled: true
  # Actuator 端口独立（不对外暴露）
  server:
    port: 9090

安全配置原则：

• heapdump 和 env 端点包含敏感信息，生产禁止对外暴露
• Actuator 端口（如9090）只对内网/监控系统开放
• 结合 Spring Security 对 Actuator 端点单独设置权限

知识点 3：自定义健康检查

/**
 * 自定义健康检查：检查第三方依赖的可用性
 * 访问 /actuator/health 时会聚合所有 HealthIndicator 的结果
 */
@Component
public class ExternalServiceHealthIndicator implements HealthIndicator {

    private final ExternalServiceClient client;

    public ExternalServiceHealthIndicator(ExternalServiceClient client) {
        this.client = client;
    }

    @Override
    public Health health() {
        try {
            boolean available = client.ping();
            if (available) {
                return Health.up()
                    .withDetail("service", "external-payment")
                    .withDetail("status", "reachable")
                    .build();
            }
            return Health.down()
                .withDetail("service", "external-payment")
                .withDetail("reason", "ping timeout")
                .build();
        } catch (Exception e) {
            return Health.down(e)
                .withDetail("service", "external-payment")
                .build();
        }
    }
}

健康状态聚合规则：

• 所有组件 UP → 整体 UP（HTTP 200）
• 任一组件 DOWN → 整体 DOWN（HTTP 503）
• Kubernetes 的 readinessProbe 就是调用此接口

知识点 4：自定义 Info 端点

# application.yml
info:
  app:
    name: "@project.artifactId@"    # 从 Maven pom.xml 读取
    version: "@project.version@"
    description: "订单服务"
  build:
    time: "@maven.build.timestamp@"

// 动态 Info 贡献者（运行时添加信息）
@Component
public class AppInfoContributor implements InfoContributor {
    @Override
    public void contribute(Info.Builder builder) {
        builder.withDetail("startup-time",
            ManagementFactory.getRuntimeMXBean().getStartTime());
        builder.withDetail("active-profiles",
            Arrays.toString(environment.getActiveProfiles()));
    }
}

知识点 5：Prometheus 指标接入（生产标配）

<!-- 引入 Prometheus 端点支持 -->
<dependency>
    <groupId>io.micrometer</groupId>
    <artifactId>micrometer-registry-prometheus</artifactId>
</dependency>

management:
  endpoints:
    web:
      exposure:
        include: "health,prometheus"
  metrics:
    tags:
      application: ${spring.application.name}  # 所有指标附带应用名标签
      environment: ${spring.profiles.active}

/actuator/prometheus 端点暴露后，Prometheus 可以定时采集，Grafana 订阅展示。

常用监控指标：

指标	含义
jvm_memory_used_bytes	JVM 堆/非堆内存使用
jvm_gc_pause_seconds	GC停顿时间分布
http_server_requests_seconds	HTTP 接口响应时间分布（含P99）
hikaricp_connections_active	连接池活跃连接数
process_cpu_usage	应用 CPU 使用率

---

13. Spring Boot 3.x 新特性与现代化实践

知识点 1：虚拟线程（JDK 21 + Spring Boot 3.2）

什么是虚拟线程 ：

JDK 21 引入的轻量级线程，由 JVM 调度（不是 OS 线程）。创建成本极低，可以创建数百万个，用于解决传统线程模型在高并发 I/O 场景下的瓶颈。

传统线程 vs 虚拟线程对比：

维度	传统平台线程	虚拟线程
创建成本	重（~1MB 栈内存）	轻（KB级别）
数量	通常数百个	可达数百万个
阻塞行为	阻塞OS线程（占资源）	仅挂起虚拟线程（不占OS线程）
适用场景	CPU密集型	I/O密集型（HTTP、数据库、文件）

Spring Boot 3.2 一行配置开启：

spring:
  threads:
    virtual:
      enabled: true  # 将 Tomcat/调度器切换到虚拟线程

开启后，每个 HTTP 请求都运行在独立的虚拟线程中，数据库调用阻塞时不占用平台线程，吞吐量显著提升。

注意事项：

• 虚拟线程不适合 CPU 密集型任务（如图像处理、加密运算），这类任务仍用平台线程池
• ThreadLocal 使用无问题，但建议用 ScopedValue（JDK 21 引入）替代

知识点 2：GraalVM 原生镜像

Spring Boot 3.x 原生支持编译成 GraalVM Native Image（本地可执行文件）：

# 编译为本地可执行文件（无需 JVM）
mvn -Pnative native:compile

# 编译结果：
# target/myapp（Linux 可执行文件，~50MB）
# 启动时间：< 100ms（对比 JVM 的 2-5秒）
# 内存占用：减少 50-80%

适用场景：Serverless / FaaS（函数计算）、容器化部署追求极速启动。

限制：不支持反射（需额外配置）、动态代理受限，Spring Boot 已内置大量 AOT 提示。

知识点 3：@HttpExchange 声明式 HTTP 客户端

Spring Boot 3.x 内置声明式 HTTP 客户端（类似 Feign，无需额外依赖）：

// 声明接口
@HttpExchange("https://api.github.com")
public interface GitHubClient {

    @GetExchange("/users/{username}")
    GitHubUser getUser(@PathVariable String username);

    @PostExchange("/repos/{owner}/{repo}/issues")
    Issue createIssue(
        @PathVariable String owner,
        @PathVariable String repo,
        @RequestBody CreateIssueRequest request
    );
}

// 注册为 Bean
@Configuration
public class HttpClientConfig {
    @Bean
    public GitHubClient gitHubClient() {
        WebClient webClient = WebClient.builder()
            .defaultHeader("Authorization", "Bearer " + token)
            .build();
        HttpServiceProxyFactory factory = HttpServiceProxyFactory
            .builderFor(WebClientAdapter.create(webClient))
            .build();
        return factory.createClient(GitHubClient.class);
    }
}

// 直接注入使用
@Service
@RequiredArgsConstructor
public class GitHubService {
    private final GitHubClient gitHubClient;

    public GitHubUser getUser(String username) {
        return gitHubClient.getUser(username);
    }
}

---

14. Spring Boot 启动流程深度解析

知识点 1：SpringApplication.run 做了什么

SpringApplication.run(MyApp.class, args)
    │
    ├── 1. 创建 SpringApplication 对象
    │       推断应用类型（SERVLET / REACTIVE / NONE）
    │       加载 ApplicationContextInitializer（从 spring.factories）
    │       加载 ApplicationListener（从 spring.factories）
    │       推断 mainApplicationClass（打印启动日志用）
    │
    ├── 2. run() 方法执行
    │       ① 创建 SpringApplicationRunListeners（启动事件广播）
    │       ② 发布 ApplicationStartingEvent
    │       ③ 准备环境（ConfigurableEnvironment）
    │          加载 application.yml / application.properties
    │          解析命令行参数、环境变量
    │          发布 ApplicationEnvironmentPreparedEvent
    │       ④ 创建 ApplicationContext（AnnotationConfigServletWebServerApplicationContext）
    │       ⑤ prepareContext()
    │          执行 ApplicationContextInitializer
    │          注册 mainApplicationClass 为 BeanDefinition
    │       ⑥ refreshContext()  ← 核心！完整 Spring IoC 容器初始化
    │          扫描 @ComponentScan 下的所有类
    │          执行自动配置（AutoConfiguration）
    │          启动内嵌 Tomcat（onRefresh 阶段）
    │       ⑦ afterRefresh()
    │          执行 ApplicationRunner / CommandLineRunner
    │       ⑧ 发布 ApplicationStartedEvent
    │       ⑨ 发布 ApplicationReadyEvent（应用就绪，可接收流量）
    │
    └── 返回 ConfigurableApplicationContext

知识点 2：如何在启动完成后执行初始化逻辑

有三种方式，执行顺序和使用场景不同：

// 方式1：@PostConstruct（Bean 级别，最早执行）
// 场景：单个 Bean 初始化自己的状态（如加载本地缓存）
@Component
@Slf4j
public class CacheInitializer {

    private final ProductRepository productRepository;
    private final Map<Long, Product> localCache = new ConcurrentHashMap<>();

    @PostConstruct  // 属性注入完成后立即执行
    public void init() {
        log.info("开始预热本地缓存...");
        productRepository.findAll().forEach(p -> localCache.put(p.getId(), p));
        log.info("本地缓存预热完成，共 {} 条", localCache.size());
    }
}

// 方式2：ApplicationRunner（应用就绪后执行）
// 场景：需要整个 Spring 容器就绪后才能执行的初始化
@Component
@Order(1)  // 多个 Runner 时控制顺序
@Slf4j
public class DatabaseHealthRunner implements ApplicationRunner {

    private final DataSource dataSource;

    @Override
    public void run(ApplicationArguments args) throws Exception {
        // 应用完全启动后再检查
        try (Connection conn = dataSource.getConnection()) {
            log.info("数据库连接正常：{}", conn.getMetaData().getDatabaseProductName());
        }
        // 可以访问命令行参数
        if (args.containsOption("init-data")) {
            log.info("检测到 --init-data 参数，执行数据初始化...");
        }
    }
}

// 方式3：CommandLineRunner（更简单的命令行参数访问）
@Component
@Order(2)
public class ReportRunner implements CommandLineRunner {

    @Override
    public void run(String... args) throws Exception {
        // args 是原始命令行参数数组
        for (String arg : args) {
            System.out.println("启动参数: " + arg);
        }
    }
}

执行顺序 ：@PostConstruct → ApplicationRunner/CommandLineRunner（按 @Order 排序）

---

15. 配置文件体系详解

知识点 1：YAML 高级语法

# 基础类型
name: 张三
age: 25
salary: 10000.50
active: true

# 字符串注意事项
simple: hello world       # 不需要引号
with-colon: "包含:冒号"   # 包含特殊字符需要引号
multiline: |              # | 保留换行符
  第一行
  第二行
folded: >                 # > 折叠换行为空格
  这是一段很长的文本
  会被折叠成一行

# List 写法
hobbies:
  - 阅读
  - 编程
  - 游泳
# 也可以写成：hobbies: [阅读, 编程, 游泳]

# Map 写法
address:
  province: 广东
  city: 深圳
  district: 南山区

# 嵌套
servers:
  - host: 192.168.1.1
    port: 8080
    name: 主服务器
  - host: 192.168.1.2
    port: 8081
    name: 备用服务器

# 多文档块（同一文件多个配置，用 --- 分隔）
---
spring:
  profiles: dev
server:
  port: 8080
---
spring:
  profiles: prod
server:
  port: 80

知识点 2：配置绑定的三种方式对比

// 方式1：@Value（简单值，支持 SpEL 表达式）
@RestController
public class DemoController {

    @Value("${server.port}")
    private int port;

    @Value("${app.name:默认应用名}")  // 有默认值
    private String appName;

    @Value("#{${app.servers}}")  // SpEL 解析 Map
    private Map<String, String> servers;

    @Value("${app.tags:}")  // 列表（逗号分隔）
    private List<String> tags;
}

// 方式2：@ConfigurationProperties（推荐，强类型，支持校验）
@Data
@Component
@ConfigurationProperties(prefix = "app")
@Validated  // 开启 JSR-303 校验
public class AppConfig {

    @NotEmpty
    private String name;

    @Min(1) @Max(65535)
    private int port = 8080;

    @NotNull
    private DatabaseConfig database = new DatabaseConfig();

    private List<String> admins = new ArrayList<>();

    @Data
    public static class DatabaseConfig {
        @NotBlank
        private String url;
        private int maxPoolSize = 10;
        private Duration timeout = Duration.ofSeconds(30);
    }
}

// 方式3：Environment（编程式获取，灵活但不推荐常用）
@Service
public class ConfigService {

    @Autowired
    private Environment env;

    public void printConfig() {
        String dbUrl = env.getProperty("spring.datasource.url");
        int port = env.getProperty("server.port", Integer.class, 8080);
        String[] profiles = env.getActiveProfiles();
    }
}

application.yml 配置示例：

app:
  name: 订单服务
  port: 9001
  admins:
    - admin@example.com
    - dev@example.com
  database:
    url: jdbc:mysql://localhost:3306/orders
    max-pool-size: 20
    timeout: 30s

知识点 3：配置优先级

优先级从高到低（高优先级覆盖低优先级）：

1. 命令行参数          java -jar app.jar --server.port=9090
2. 操作系统环境变量    SERVER_PORT=9090
3. JVM 系统属性       -Dserver.port=9090
4. application-{profile}.yml（激活的环境配置）
5. application.yml
6. @PropertySource 注解引入的配置文件
7. @SpringBootApplication 类所在包的默认配置

---

16. RESTful API 设计规范与最佳实践

知识点 1：REST 设计原则

REST（Representational State Transfer）六大约束：

1. 资源标识（URI）：
   ✅ GET /api/v1/users/123        ← 名词，复数
   ❌ GET /api/getUserById?id=123  ← 动词，不符合 REST

2. HTTP 方法语义：
   GET    → 查询（安全且幂等）
   POST   → 创建（非幂等）
   PUT    → 全量更新（幂等）
   PATCH  → 部分更新（幂等）
   DELETE → 删除（幂等）

3. 状态码语义：
   200 OK        → 成功
   201 Created   → 创建成功（POST 后返回）
   204 No Content → 成功但无响应体（DELETE 后返回）
   400 Bad Request → 参数错误
   401 Unauthorized → 未认证
   403 Forbidden → 已认证但无权限
   404 Not Found → 资源不存在
   409 Conflict  → 资源冲突（如用户名已存在）
   422 Unprocessable → 语义错误（校验失败）
   500 Internal Server Error → 服务端错误

4. API 版本管理：
   推荐方案：URI 路径版本  /api/v1/users  /api/v2/users
   次选方案：请求头版本   Accept: application/vnd.myapp.v2+json

知识点 2：统一返回结构

// 统一响应体
@Data
@NoArgsConstructor
@AllArgsConstructor
public class Result<T> {
    private int code;        // 业务状态码（200=成功，非200=失败）
    private String message;  // 描述信息
    private T data;          // 业务数据
    private long timestamp;  // 时间戳（便于排查问题）

    // 静态工厂方法
    public static <T> Result<T> success(T data) {
        return new Result<>(200, "success", data, System.currentTimeMillis());
    }

    public static <T> Result<T> success() {
        return success(null);
    }

    public static <T> Result<T> fail(int code, String message) {
        return new Result<>(code, message, null, System.currentTimeMillis());
    }

    public static <T> Result<T> fail(ResultCode resultCode) {
        return fail(resultCode.getCode(), resultCode.getMessage());
    }
}

// 业务状态码枚举
public enum ResultCode {
    SUCCESS(200, "操作成功"),
    BAD_REQUEST(400, "请求参数错误"),
    UNAUTHORIZED(401, "请先登录"),
    FORBIDDEN(403, "权限不足"),
    NOT_FOUND(404, "资源不存在"),
    CONFLICT(409, "数据冲突"),
    INTERNAL_ERROR(500, "服务器内部错误"),

    // 业务码（从1000开始，避免与HTTP状态码冲突）
    USER_NOT_FOUND(1001, "用户不存在"),
    USER_DISABLED(1002, "账号已被禁用"),
    PASSWORD_WRONG(1003, "密码错误"),
    STOCK_NOT_ENOUGH(2001, "库存不足"),
    ORDER_ALREADY_PAID(2002, "订单已支付");

    private final int code;
    private final String message;

    ResultCode(int code, String message) {
        this.code = code;
        this.message = message;
    }
    public int getCode() { return code; }
    public String getMessage() { return message; }
}

// 全局异常处理器
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    // 参数校验失败
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public Result<Map<String, String>> handleValidationException(
            MethodArgumentNotValidException e) {
        Map<String, String> errors = new LinkedHashMap<>();
        e.getBindingResult().getFieldErrors().forEach(err ->
            errors.put(err.getField(), err.getDefaultMessage()));
        log.warn("参数校验失败: {}", errors);
        return Result.fail(400, "参数校验失败: " + errors);
    }

    // 业务异常
    @ExceptionHandler(BusinessException.class)
    public Result<Void> handleBusinessException(BusinessException e) {
        log.warn("业务异常: code={}, message={}", e.getCode(), e.getMessage());
        return Result.fail(e.getCode(), e.getMessage());
    }

    // 兜底异常
    @ExceptionHandler(Exception.class)
    public Result<Void> handleException(Exception e, HttpServletRequest request) {
        log.error("未知异常 [{}] {}", request.getMethod(), request.getRequestURI(), e);
        return Result.fail(500, "服务器内部错误，请稍后重试");
    }
}

// 业务异常基类
@Getter
public class BusinessException extends RuntimeException {
    private final int code;

    public BusinessException(ResultCode resultCode) {
        super(resultCode.getMessage());
        this.code = resultCode.getCode();
    }

    public BusinessException(int code, String message) {
        super(message);
        this.code = code;
    }
}

// Controller 使用示例
@RestController
@RequestMapping("/api/v1/users")
@RequiredArgsConstructor
@Slf4j
public class UserController {

    private final UserService userService;

    @GetMapping("/{id}")
    public Result<UserDTO> getUser(@PathVariable Long id) {
        return Result.success(userService.findById(id));
    }

    @PostMapping
    @ResponseStatus(HttpStatus.CREATED)
    public Result<UserDTO> createUser(@RequestBody @Valid CreateUserRequest request) {
        return Result.success(userService.create(request));
    }

    @PutMapping("/{id}")
    public Result<UserDTO> updateUser(@PathVariable Long id,
                                       @RequestBody @Valid UpdateUserRequest request) {
        return Result.success(userService.update(id, request));
    }

    @DeleteMapping("/{id}")
    @ResponseStatus(HttpStatus.NO_CONTENT)
    public void deleteUser(@PathVariable Long id) {
        userService.delete(id);
    }

    @GetMapping
    public Result<Page<UserDTO>> listUsers(
            @RequestParam(defaultValue = "1") int page,
            @RequestParam(defaultValue = "10") @Max(100) int size,
            @RequestParam(required = false) String keyword) {
        return Result.success(userService.list(page, size, keyword));
    }
}

---

17. 单元测试与集成测试

知识点 1：Spring Boot Test 分层测试

测试分层策略：

单元测试（速度最快）：
  Mockito 模拟依赖，只测 Service 层业务逻辑
  不启动 Spring 容器

切片测试（中等速度）：
  @WebMvcTest    → 只启动 MVC 层（Controller、Filter）
  @DataJpaTest   → 只启动 JPA 层（Repository，内存数据库）
  @JsonTest      → 只测试 JSON 序列化

集成测试（最慢）：
  @SpringBootTest → 启动完整 Spring 容器
  配合 Testcontainers 使用真实数据库

知识点 2：Service 层单元测试（Mockito）

@ExtendWith(MockitoExtension.class)
class UserServiceTest {

    @Mock
    private UserRepository userRepository;

    @Mock
    private PasswordEncoder passwordEncoder;

    @InjectMocks  // 将 @Mock 注入到此对象
    private UserService userService;

    @Test
    @DisplayName("创建用户：正常流程")
    void createUser_success() {
        // Given（准备数据）
        CreateUserRequest request = new CreateUserRequest("test@email.com", "password123");
        User savedUser = new User(1L, "test@email.com", "encodedPwd");

        when(userRepository.existsByEmail(request.getEmail())).thenReturn(false);
        when(passwordEncoder.encode(request.getPassword())).thenReturn("encodedPwd");
        when(userRepository.save(any(User.class))).thenReturn(savedUser);

        // When（执行）
        UserDTO result = userService.create(request);

        // Then（断言）
        assertNotNull(result);
        assertEquals("test@email.com", result.getEmail());
        verify(userRepository).save(argThat(user ->
            user.getEmail().equals("test@email.com") &&
            user.getPassword().equals("encodedPwd")));
    }

    @Test
    @DisplayName("创建用户：邮箱已存在抛出异常")
    void createUser_emailExists_throwsException() {
        CreateUserRequest request = new CreateUserRequest("exists@email.com", "password");
        when(userRepository.existsByEmail(request.getEmail())).thenReturn(true);

        assertThrows(BusinessException.class, () -> userService.create(request));
        verify(userRepository, never()).save(any());  // 确保没有调用 save
    }
}

知识点 3：Controller 层切片测试（MockMvc）

@WebMvcTest(UserController.class)  // 只启动 MVC 层，不启动完整容器
class UserControllerTest {

    @Autowired
    private MockMvc mockMvc;

    @MockBean  // 在 Spring 容器中注册 Mock Bean
    private UserService userService;

    @Autowired
    private ObjectMapper objectMapper;

    @Test
    @DisplayName("GET /api/v1/users/{id} - 用户存在返回200")
    void getUser_exists_returns200() throws Exception {
        UserDTO user = new UserDTO(1L, "test@email.com");
        when(userService.findById(1L)).thenReturn(user);

        mockMvc.perform(get("/api/v1/users/1")
                .contentType(MediaType.APPLICATION_JSON))
            .andExpect(status().isOk())
            .andExpect(jsonPath("$.code").value(200))
            .andExpect(jsonPath("$.data.email").value("test@email.com"))
            .andDo(print());  // 打印请求/响应（调试用）
    }

    @Test
    @DisplayName("POST /api/v1/users - 参数校验失败返回400")
    void createUser_invalidRequest_returns400() throws Exception {
        CreateUserRequest request = new CreateUserRequest("invalid-email", ""); // 无效邮箱，空密码

        mockMvc.perform(post("/api/v1/users")
                .contentType(MediaType.APPLICATION_JSON)
                .content(objectMapper.writeValueAsString(request)))
            .andExpect(status().isBadRequest())
            .andExpect(jsonPath("$.code").value(400));
    }
}

知识点 4：集成测试（Testcontainers）

// 使用真实 MySQL 容器进行集成测试
@SpringBootTest
@Testcontainers
@Transactional  // 每个测试后回滚
class UserRepositoryIntegrationTest {

    @Container
    static MySQLContainer<?> mysql = new MySQLContainer<>("mysql:8.0")
        .withDatabaseName("test_db")
        .withUsername("test")
        .withPassword("test");

    // 动态注入容器的连接信息
    @DynamicPropertySource
    static void configureDataSource(DynamicPropertyRegistry registry) {
        registry.add("spring.datasource.url", mysql::getJdbcUrl);
        registry.add("spring.datasource.username", mysql::getUsername);
        registry.add("spring.datasource.password", mysql::getPassword);
    }

    @Autowired
    private UserRepository userRepository;

    @Test
    void findByEmail_exists_returnsUser() {
        User user = new User("test@email.com", "password");
        userRepository.save(user);

        Optional<User> found = userRepository.findByEmail("test@email.com");
        assertTrue(found.isPresent());
        assertEquals("test@email.com", found.get().getEmail());
    }
}