【阶段 2】Spring Boot 入门：自动配置与配置管理

# 确认 JDK 版本
java -version
# openjdk version "17.0.10" 2024-01-16

# 确认 Maven 版本
mvn -version
# Apache Maven 3.9.6

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <!-- 关键：继承 Spring Boot 父 POM，统一管理所有依赖版本 -->
    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>demo</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <name>demo</name>
    <description>Spring Boot basics tutorial</description>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <!-- Web：内嵌 Tomcat + Spring MVC + Jackson -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>

        <!-- 校验：@Validated / @NotBlank 等 JSR-380 注解需要它 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>

        <!-- 测试：JUnit 5 + MockMvc -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <!-- 打可执行 fat jar 的关键插件（第 6 章详解） -->
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

package com.example.demo.controller;

import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController                       // = @Controller + @ResponseBody，方法返回值直接写进响应体
@RequestMapping("/api/hello")
public class HelloController {

    @GetMapping
    public String hello() {
        // 先返回最简字符串，下一节再换成统一响应体 ApiResult
        return "Hello, Spring Boot!";
    }
}

package com.example.demo;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

@SpringBootApplication
public class DemoApplication {
    public static void main(String[] args) {
        // run 方法做了三件事：创建容器 → 触发自动配置 → 启动内嵌 Tomcat
        SpringApplication.run(DemoApplication.class, args);
    }
}

# 在项目根目录
mvn spring-boot:run

# 另开一个终端验证
curl http://localhost:8080/api/hello
# 输出：Hello, Spring Boot!

@SpringBootConfiguration        // ① 本质是 @Configuration，把启动类标记为配置类
@EnableAutoConfiguration        // ② 开启自动配置（本篇核心，第 2 章详解）
@ComponentScan                  // ③ 组件扫描
public @interface SpringBootApplication {
    // ...
}

@Target(ElementType.TYPE)
@Retention(RetentionPolicy.RUNTIME)
@Documented
@Configuration                  // 注意：它本身就是被 @Configuration 标注的
@Indexed
public @interface SpringBootConfiguration {
}

package com.example.demo.common;

import lombok.Data;
import org.slf4j.MDC;

@Data
public class ApiResult<T> {
    private int code;        // 0=成功，非 0=错误码
    private String message;  // 提示信息
    private T data;          // 业务数据
    private String traceId;  // 链路追踪 id

    public static <T> ApiResult<T> ok(T data) {
        ApiResult<T> r = new ApiResult<>();
        r.setCode(ErrorCode.SUCCESS.getCode());
        r.setMessage(ErrorCode.SUCCESS.getMessage());
        r.setData(data);
        r.setTraceId(MDC.get("traceId"));
        return r;
    }
    public static <T> ApiResult<T> ok() {
        return ok(null);
    }
    public static <T> ApiResult<T> fail(int code, String message) {
        ApiResult<T> r = new ApiResult<>();
        r.setCode(code);
        r.setMessage(message);
        r.setTraceId(MDC.get("traceId"));
        return r;
    }
    public static <T> ApiResult<T> fail(ErrorCode ec) {
        return fail(ec.getCode(), ec.getMessage());
    }
}

package com.example.demo.common;

/** 统一错误码（基础码数值全系列固定不变，各篇可扩展） */
public enum ErrorCode {
    SUCCESS(0, "success"),
    PARAM_ERROR(40001, "参数错误"),
    UNAUTHORIZED(40101, "未登录或登录已过期"),
    FORBIDDEN(40301, "无权限访问"),
    USER_NOT_FOUND(40401, "用户不存在"),
    SYSTEM_ERROR(50000, "系统繁忙，请稍后重试"),
    ;

    private final int code;
    private final String message;

    ErrorCode(int code, String message) {
        this.code = code;
        this.message = message;
    }

    public int getCode() { return code; }
    public String getMessage() { return message; }
}

package com.example.demo.exception;

import com.example.demo.common.ErrorCode;

/** 统一业务异常：业务代码主动抛出，由 GlobalExceptionHandler 统一转成 ApiResult */
public class BizException extends RuntimeException {
    private final int code;

    public BizException(ErrorCode ec) {
        super(ec.getMessage());
        this.code = ec.getCode();
    }

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

    public int getCode() { return code; }
}

package com.example.demo.exception;

import com.example.demo.common.ApiResult;
import com.example.demo.common.ErrorCode;
import lombok.extern.slf4j.Slf4j;
import org.springframework.web.bind.MethodArgumentNotValidException;
import org.springframework.web.bind.annotation.ExceptionHandler;
import org.springframework.web.bind.annotation.RestControllerAdvice;

/** 全局异常处理器：统一把异常转成 ApiResult，避免堆栈直接暴露给前端 */
@RestControllerAdvice
@Slf4j
public class GlobalExceptionHandler {

    // 业务异常：code/message 透传给前端
    @ExceptionHandler(BizException.class)
    public ApiResult<Void> handleBiz(BizException e) {
        log.warn("业务异常 code={}, message={}", e.getCode(), e.getMessage());
        return ApiResult.fail(e.getCode(), e.getMessage());
    }

    // 参数校验异常：取第一个校验失败的字段提示
    @ExceptionHandler(MethodArgumentNotValidException.class)
    public ApiResult<Void> handleValid(MethodArgumentNotValidException e) {
        String msg = e.getBindingResult().getFieldErrors().stream()
            .findFirst()
            .map(f -> f.getField() + " " + f.getDefaultMessage())
            .orElse(ErrorCode.PARAM_ERROR.getMessage());
        return ApiResult.fail(ErrorCode.PARAM_ERROR.getCode(), msg);
    }

    // 兜底异常：对外返回模糊提示，详细堆栈只进日志，防止泄露内部结构
    @ExceptionHandler(Exception.class)
    public ApiResult<Void> handleOther(Exception e) {
        log.error("系统异常", e);
        return ApiResult.fail(ErrorCode.SYSTEM_ERROR);
    }
}

@RestController
@RequestMapping("/api/hello")
public class HelloController {

    @GetMapping
    public ApiResult<String> hello() {
        return ApiResult.ok("Hello, Spring Boot!");
    }
}

{"code":0,"message":"success","data":"Hello, Spring Boot!","traceId":null}

# 找到 spring-boot-autoconfigure 的 jar，解压后看这个文件
jar xf spring-boot-autoconfigure-3.2.5.jar 
    META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports

cat META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports
# 输出片段：
# org.springframework.boot.autoconfigure.web.servlet.WebMvcAutoConfiguration
# org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration
# org.springframework.boot.autoconfigure.jackson.JacksonAutoConfiguration
# ...（约 140+ 行）

@AutoConfiguration
@ConditionalOnWebApplication(type = Type.SERVLET)       // ① 是 Servlet Web 环境
@ConditionalOnClass({ Servlet.class, DispatcherServlet.class, WebMvcConfigurer.class }) // ② 相关类在 classpath
@ConditionalOnMissingBean(WebMvcConfigurationSupport.class) // ③ 用户没自己定义 WebMvcConfigurationSupport
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE + 10)
public class WebMvcAutoConfiguration {
    // ...
    @Bean
    @ConditionalOnMissingBean
    public ViewResolver mvcViewResolver(...) { /* 默认视图解析器 */ }

    @Bean
    @ConditionalOnMissingBean
    public ObjectMapper jacksonObjectMapper(...) { /* 默认 JSON 序列化器 */ }
}

# 方式一：命令行参数
java -jar app.jar --debug

# 方式二：mvn 启动时
mvn spring-boot:run -Dspring-boot.run.arguments=--debug

# 方式三：写进 application.yml（会一直打印，生产不建议常开）
debug: true

package com.example.demo.config;

import lombok.extern.slf4j.Slf4j;
import org.springframework.boot.autoconfigure.condition.ConditionalOnClass;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;
import org.springframework.data.redis.core.RedisOperations;

@Configuration
@Slf4j
public class DemoConditionConfig {

    // 只有当 classpath 存在 RedisOperations（即引了 redis starter）、
    // 且容器里还没有同名 Bean、且 demo.redis.enabled 为 true 时，才注册
    @Bean
    @ConditionalOnClass(RedisOperations.class)
    @ConditionalOnMissingBean(name = "demoRedisMarker")
    @ConditionalOnProperty(prefix = "demo.redis", name = "enabled", havingValue = "true", matchIfMissing = true)
    public String demoRedisMarker() {
        log.info("demoRedisMarker 已注册：说明 redis 条件满足");
        return "redis-present";
    }
}

// 方式一：注解排除（精确到类）
@SpringBootApplication(exclude = DataSourceAutoConfiguration.class)
public class DemoApplication {
    // ...
}

# 方式二：配置排除（不用改代码，运维可临时禁用）
spring:
  autoconfigure:
    exclude:
      - org.springframework.boot.autoconfigure.jdbc.DataSourceAutoConfiguration
      - org.springframework.boot.autoconfigure.data.redis.RedisAutoConfiguration

// 方式三：@EnableAutoConfiguration 上排除（与方式一等效，写法不同）
@EnableAutoConfiguration(exclude = DataSourceAutoConfiguration.class)

@AutoConfiguration
@AutoConfigureOrder(Ordered.HIGHEST_PRECEDENCE)          // 数字越小越先加载
@AutoConfigureBefore(WebMvcAutoConfiguration.class)      // 声明自己必须在某类之前
@AutoConfigureAfter(DataSourceAutoConfiguration.class)   // 声明自己必须在某类之后
public class MyAutoConfiguration {
    // ...
}

# ① 层级用缩进表示（不能用 Tab，必须空格，且缩进一致）
server:
  port: 8080          # 冒号后必须有一个空格

# ② 三种值类型
app:
  name: order-service      # 字符串
  thread-pool: 16          # 数字（会被绑定成 int）
  feature-enabled: true    # 布尔

# ③ 数组写法（两种等价）
app:
  tags:
    - java
    - spring
  # 或行内：tags: [java, spring]

# ④ 占位符引用
app:
  desc: "服务 ${app.name} 的配置"    # 引用同文件里的值

# ⑤ 多行字符串（保留换行）
app:
  banner: |
    第一行
    第二行

# application.yml 里写 server.port: 8080
# 用命令行参数覆盖成 9090
mvn spring-boot:run -Dspring-boot.run.arguments=--server.port=9090
# 或直接
java -jar app.jar --server.port=9090

# 观察启动日志：Tomcat started on port 9090

export SERVER_PORT=7070
java -jar app.jar        # 此时命令行 > 环境变量，但这里没传命令行，所以是 7070

@Service
public class OssService {

    @Value("${app.oss.endpoint}")      // 散落、无校验、类型不安全
    private String endpoint;

    @Value("${app.oss.max-size:1048576}")  // 冒号后面是默认值
    private int maxSize;               // 若配置写成了 "abc"，启动直接报 NumberFormatException

    // 若某个 key 忘配且没默认值，启动直接 fail-fast
}

package com.example.demo.properties;

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import jakarta.validation.constraints.NotNull;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

/**
 * 绑定 application.yml 中 app.oss.* 前缀的配置。
 * 用 @Validated + JSR-380 注解，启动时校验，配置错了 fail-fast 而不是运行时才炸。
 */
@Data
@Validated
@ConfigurationProperties(prefix = "app.oss")
public class OssProperties {

    /** 对象存储 endpoint，必填 */
    @NotBlank(message = "app.oss.endpoint 不能为空")
    private String endpoint;

    /** accessKey，必填 */
    @NotBlank(message = "app.oss.access-key 不能为空")
    private String accessKey;

    /** secretKey 属于敏感信息，必填但生产从环境变量注入（见 3.6） */
    @NotBlank(message = "app.oss.secret-key 不能为空")
    private String secretKey;

    /** bucket 名，必填 */
    @NotBlank
    private String bucket;

    /** 上传超时（秒），给默认值并限制范围 */
    @Min(1)
    @Max(60)
    private int timeoutSeconds = 10;

    /** 是否启用（功能开关） */
    private boolean enabled = true;

    /** 连接池大小，必填且不小于 1 */
    @NotNull
    @Min(1)
    private Integer poolSize = 8;
}

package com.example.demo.config;

import com.example.demo.properties.OssProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

/**
 * 方式一：用 @EnableConfigurationProperties 显式注册配置类。
 * 好处：配置类不需要加 @Component，职责更纯粹，也便于测试时选择性启用。
 */
@Configuration
@EnableConfigurationProperties(OssProperties.class)
public class AppConfig {
}

// 方式二（等效）：在配置类上加 @ConfigurationPropertiesScan，
// 会自动扫描指定包下所有 @ConfigurationProperties 类
// @Configuration
// @ConfigurationPropertiesScan("com.example.demo.properties")
// public class AppConfig { }

app:
  oss:
    endpoint: https://oss-cn-hangzhou.aliyuncs.com
    access-key: ${OSS_ACCESS_KEY}        # 从环境变量读，避免硬编码
    secret-key: ${OSS_SECRET_KEY}        # 敏感信息外部化
    bucket: my-bucket
    timeout-seconds: 20
    pool-size: 16

package com.example.demo.service;

import com.example.demo.properties.OssProperties;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor    // 生成包含 final 字段的构造器，实现构造器注入
@Slf4j
public class OssService {

    private final OssProperties ossProperties;   // 构造器注入，保证依赖不可变

    public String buildUploadUrl() {
        // 使用配置拼出上传地址
        return ossProperties.getEndpoint() + "/" + ossProperties.getBucket();
    }

    public void printConfig() {
        // 日志里绝不打印 secretKey 这类敏感字段
        log.info("OSS 配置：endpoint={}, bucket={}, timeout={}s, enabled={}",
                ossProperties.getEndpoint(),
                ossProperties.getBucket(),
                ossProperties.getTimeoutSeconds(),
                ossProperties.isEnabled());
    }
}

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

# application.yml（所有环境共享的公共配置 + 默认激活哪个环境）
spring:
  profiles:
    active: dev          # 默认 dev；生产用环境变量 SPRING_PROFILES_ACTIVE 覆盖
  application:
    name: demo

server:
  port: 8080

# application-dev.yml（开发环境）
server:
  port: 8080
logging:
  level:
    com.example: DEBUG       # 开发环境业务包打 DEBUG，便于排查

# application-prod.yml（生产环境）
server:
  port: 8080
logging:
  level:
    com.example: INFO        # 生产只打 INFO，减少日志量
app:
  oss:
    endpoint: https://oss-prod.example.com

# 方式一：yml 里 active（默认 dev）
# 方式二：命令行
java -jar app.jar --spring.profiles.active=prod
# 方式三：环境变量（生产标准做法，运维不改文件）
export SPRING_PROFILES_ACTIVE=prod
java -jar app.jar

# ❌ 错误示范：硬编码
spring:
  datasource:
    password: "MyP@ssw0rd123"

# ✅ 正确做法一：占位符引用环境变量
spring:
  datasource:
    password: ${DB_PASSWORD}

# ✅ 正确做法二：引用 JVM 系统属性
spring:
  datasource:
    password: ${db.password}

# 环境变量注入
export DB_PASSWORD='MyP@ssw0rd123'
java -jar app.jar

# 或命令行参数注入（优先级最高，但会出现在进程列表里，需权衡）
java -jar app.jar --spring.datasource.password='MyP@ssw0rd123'

# 或 JVM 系统属性
java -jar -Ddb.password='MyP@ssw0rd123' app.jar

package com.example.demo.properties;

import jakarta.validation.constraints.NotBlank;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

/**
 * 构造器绑定的不可变配置类。
 * Spring Boot 3.x 中：只要类只有一个构造器，就自动启用构造器绑定，无需 @ConstructorBinding。
 */
@Validated
@ConfigurationProperties(prefix = "app.oss")
public class ImmutableOssProperties {

    private final String endpoint;
    private final String accessKey;
    private final String bucket;
    private final int timeoutSeconds;

    // 校验注解直接打在构造参数上，绑定 + 校验一步完成
    public ImmutableOssProperties(@NotBlank String endpoint,
                                  @NotBlank String accessKey,
                                  @NotBlank String bucket,
                                  int timeoutSeconds) {
        this.endpoint = endpoint;
        this.accessKey = accessKey;
        this.bucket = bucket;
        this.timeoutSeconds = timeoutSeconds <= 0 ? 10 : timeoutSeconds; // 缺省兜底
    }

    public String getEndpoint() { return endpoint; }
    public String getAccessKey() { return accessKey; }
    public String getBucket() { return bucket; }
    public int getTimeoutSeconds() { return timeoutSeconds; }
}

app:
  oss:
    endpoint: https://oss.example.com
    retry:
      max-attempts: 3
      backoff-ms: 1000

@Data
@ConfigurationProperties(prefix = "app.oss")
@Validated
public class NestedOssProperties {

    @NotBlank
    private String endpoint;

    /** 嵌套对象：必须给默认实例，否则配置缺失时 retry 为 null */
    @Valid
    private Retry retry = new Retry();

    @Data
    public static class Retry {
        @Min(1)
        @Max(10)
        private int maxAttempts = 3;   // 默认重试 3 次
        @Min(0)
        private long backoffMs = 1000; // 退避 1 秒
    }
}

# application.yml
spring:
  config:
    import:
      - "optional:file:/etc/app/oss-secret.yml"   # optional: 文件不存在也不报错
      - "classpath:common.yml"                     # 引入 classpath 下另一个配置文件

app:
  oss:
    access-key: AK-XXXX
    secret-key: SK-XXXX

logging:
  level:
    root: INFO                       # 全局默认级别
    com.example.demo: DEBUG          # 自己的包打 DEBUG
    org.springframework: WARN        # 第三方框架降噪，只打 WARN
  file:
    name: logs/demo.log              # 输出到文件（简单场景够用）

<?xml version="1.0" encoding="UTF-8"?>
<configuration>

    <!-- 定义两个可复用变量：日志目录和文件名 -->
    <property name="LOG_DIR" value="logs"/>
    <property name="APP_NAME" value="demo"/>

    <!-- ① 控制台输出：开发时人眼查看 -->
    <appender name="CONSOLE" class="ch.qos.logback.core.ConsoleAppender">
        <encoder>
            <!-- traceId 从 MDC 取；%X{traceId} 输出链路追踪 id -->
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{50} - %msg%n</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <!-- ② 滚动文件：按日期 + 大小切分，生产回溯靠它 -->
    <appender name="FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_DIR}/${APP_NAME}.log</file>
        <!-- 按时间滚动，一天一个文件，超过 200MB 再切一个 .%i 序号文件 -->
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_DIR}/${APP_NAME}-%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>200MB</maxFileSize>
            <maxHistory>30</maxHistory>          <!-- 保留 30 天 -->
            <totalSizeCap>10GB</totalSizeCap>    <!-- 总大小上限，防磁盘打满 -->
        </rollingPolicy>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{50} - %msg%n</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <!-- ③ 错误日志单独归档：方便快速定位 ERROR -->
    <appender name="ERROR_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${LOG_DIR}/${APP_NAME}-error.log</file>
        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>ERROR</level>
        </filter>
        <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
            <fileNamePattern>${LOG_DIR}/${APP_NAME}-error-%d{yyyy-MM-dd}.%i.log.gz</fileNamePattern>
            <maxFileSize>100MB</maxFileSize>
            <maxHistory>30</maxHistory>
        </rollingPolicy>
        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} [%thread] [%X{traceId}] %-5level %logger{50} - %msg%n</pattern>
            <charset>UTF-8</charset>
        </encoder>
    </appender>

    <!-- ④ 按包隔离级别：自己的包 DEBUG，第三方框架降噪 -->
    <logger name="com.example.demo" level="DEBUG"/>
    <logger name="org.springframework" level="WARN"/>
    <logger name="org.apache.tomcat" level="WARN"/>

    <!-- ⑤ 根 logger：默认 INFO，同时挂控制台和文件 -->
    <root level="INFO">
        <appender-ref ref="CONSOLE"/>
        <appender-ref ref="FILE"/>
        <appender-ref ref="ERROR_FILE"/>
    </root>

    <!-- ⑥ 按环境切换：开发环境控制台打详细，生产环境不打控制台（交给采集器） -->
    <springProfile name="dev">
        <root level="INFO">
            <appender-ref ref="CONSOLE"/>
            <appender-ref ref="FILE"/>
        </root>
    </springProfile>
</configuration>

package com.example.demo.common;

import jakarta.servlet.FilterChain;
import jakarta.servlet.ServletException;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.slf4j.MDC;
import org.springframework.core.Ordered;
import org.springframework.core.annotation.Order;
import org.springframework.stereotype.Component;
import org.springframework.web.filter.OncePerRequestFilter;

import java.io.IOException;
import java.util.UUID;

/**
 * 给每个请求生成唯一 traceId 并放入 MDC。
 * MDC 是线程本地（ThreadLocal）的，同一请求的所有日志自动带上该 id，
 * 从而能把一条请求链路的所有日志串起来。
 */
@Component
@Order(Ordered.HIGHEST_PRECEDENCE)   // 最高优先级，保证最先进入、最后清理
public class TraceIdFilter extends OncePerRequestFilter {

    private static final String TRACE_ID = "traceId";

    @Override
    protected void doFilterInternal(HttpServletRequest request,
                                    HttpServletResponse response,
                                    FilterChain filterChain)
            throws ServletException, IOException {
        try {
            // 优先沿用上游传入的 traceId（网关/调用方），没有则自己生成
            String traceId = request.getHeader("X-Trace-Id");
            if (traceId == null || traceId.isBlank()) {
                traceId = UUID.randomUUID().toString().replace("-", "");
            }
            MDC.put(TRACE_ID, traceId);
            // 把 traceId 回写到响应头，方便前端/调用方联调时对应
            response.setHeader("X-Trace-Id", traceId);
            filterChain.doFilter(request, response);
        } finally {
            // 关键：请求结束必须清理，否则线程复用（Tomcat 线程池）会串号
            MDC.remove(TRACE_ID);
        }
    }
}

@RestController
@RequestMapping("/api/hello")
@Slf4j
public class HelloController {

    @GetMapping
    public ApiResult<String> hello() {
        log.info("收到 hello 请求");       // 这条日志会自动带上 traceId
        return ApiResult.ok("Hello, Spring Boot!");
    }
}

{"code":0,"message":"success","data":"Hello, Spring Boot!","traceId":"3f2a9c..."}

<!-- 在已有 FILE appender 基础上包一层异步 -->
<appender name="ASYNC_FILE" class="ch.qos.logback.classic.AsyncAppender">
    <!-- 队列满时的策略：不丢弃 INFO 以下（discardingThreshold=0 表示不丢弃），避免丢关键日志 -->
    <discardingThreshold>0</discardingThreshold>
    <queueSize>512</queueSize>
    <includeCallerData>false</includeCallerData>
    <!-- 实际落盘仍交给同步的 FILE appender -->
    <appender-ref ref="FILE"/>
</appender>

<appender name="JSON_FILE" class="ch.qos.logback.core.rolling.RollingFileAppender">
    <file>${LOG_DIR}/${APP_NAME}.json.log</file>
    <rollingPolicy class="ch.qos.logback.core.rolling.SizeAndTimeBasedRollingPolicy">
        <fileNamePattern>${LOG_DIR}/${APP_NAME}-%d{yyyy-MM-dd}.%i.json.log.gz</fileNamePattern>
        <maxFileSize>200MB</maxFileSize>
        <maxHistory>7</maxHistory>
    </rollingPolicy>
    <encoder class="net.logstash.logback.encoder.LogstashEncoder"/>
</appender>

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>id-generator-spring-boot-starter</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <!-- 自动配置核心：提供 @AutoConfiguration、@ConditionalOnXxx 等注解 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-autoconfigure</artifactId>
        </dependency>

        <!-- 校验注解（@Validated 等），scope provided 表示由使用方决定 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
            <optional>true</optional>
        </dependency>

        <!-- 生成 yml 自动补全元数据，optional 不打进使用者运行时 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-configuration-processor</artifactId>
            <optional>true</optional>
        </dependency>
    </dependencies>
</project>

package com.example.idgenerator;

import jakarta.validation.constraints.Max;
import jakarta.validation.constraints.Min;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

/**
 * id.generator.* 配置项。
 * 全部给默认值，使用者「零配置」也能跑，想调再覆盖。
 */
@Data
@Validated
@ConfigurationProperties(prefix = "id.generator")
public class IdGeneratorProperties {

    /** 是否启用（功能总开关） */
    private boolean enabled = true;

    /** 雪花算法的工作机器 id（0~1023），多实例部署时每台必须不同 */
    @Min(0)
    @Max(1023)
    private long workerId = 1;

    /** 数据中心 id（0~31） */
    @Min(0)
    @Max(31)
    private long datacenterId = 1;
}

package com.example.idgenerator;

/** 对外暴露的 ID 生成接口 */
public interface IdGenerator {
    /** 生成全局唯一、趋势递增的 64 位 ID */
    long nextId();
}

package com.example.idgenerator;

/**
 * 雪花算法（Snowflake）简化教学版。
 * 64 位结构：1 位符号位 + 41 位时间戳 + 5 位数据中心 + 5 位机器 + 12 位序列号。
 * 注意：生产环境的时钟回拨处理、跨机房唯一性，阶段 10 再展开。
 */
public class SnowflakeIdGenerator implements IdGenerator {

    private static final long EPOCH = 1704067200000L;  // 起始时间戳（2024-01-01），可自定义
    private static final long WORKER_ID_BITS = 5L;
    private static final long DATACENTER_ID_BITS = 5L;
    private static final long SEQUENCE_BITS = 12L;

    private static final long MAX_WORKER_ID = ~(-1L << WORKER_ID_BITS);       // 31
    private static final long MAX_DATACENTER_ID = ~(-1L << DATACENTER_ID_BITS); // 31
    private static final long SEQUENCE_MASK = ~(-1L << SEQUENCE_BITS);        // 4095

    private static final long WORKER_ID_SHIFT = SEQUENCE_BITS;                                   // 12
    private static final long DATACENTER_ID_SHIFT = SEQUENCE_BITS + WORKER_ID_BITS;              // 17
    private static final long TIMESTAMP_SHIFT = SEQUENCE_BITS + WORKER_ID_BITS + DATACENTER_ID_BITS; // 22

    private final long workerId;
    private final long datacenterId;
    private long sequence = 0L;
    private long lastTimestamp = -1L;

    public SnowflakeIdGenerator(long workerId, long datacenterId) {
        if (workerId > MAX_WORKER_ID || workerId < 0) {
            throw new IllegalArgumentException("workerId 必须在 0~" + MAX_WORKER_ID + " 之间");
        }
        if (datacenterId > MAX_DATACENTER_ID || datacenterId < 0) {
            throw new IllegalArgumentException("datacenterId 必须在 0~" + MAX_DATACENTER_ID + " 之间");
        }
        this.workerId = workerId;
        this.datacenterId = datacenterId;
    }

    @Override
    public synchronized long nextId() {
        long timestamp = System.currentTimeMillis();
        // 时钟回拨保护：若当前时间小于上次时间，直接抛异常（生产需更完善策略，阶段 10 讲）
        if (timestamp < lastTimestamp) {
            throw new IllegalStateException("时钟回拨 " + (lastTimestamp - timestamp) + "ms，拒绝生成 ID");
        }
        if (timestamp == lastTimestamp) {
            // 同一毫秒内序列号自增，超 4095 则自旋等下一毫秒
            sequence = (sequence + 1) & SEQUENCE_MASK;
            if (sequence == 0) {
                timestamp = tilNextMillis(lastTimestamp);
            }
        } else {
            sequence = 0L;
        }
        lastTimestamp = timestamp;
        // 位移拼装出 64 位 ID
        return ((timestamp - EPOCH) << TIMESTAMP_SHIFT)
                | (datacenterId << DATACENTER_ID_SHIFT)
                | (workerId << WORKER_ID_SHIFT)
                | sequence;
    }

    private long tilNextMillis(long lastTimestamp) {
        long timestamp = System.currentTimeMillis();
        while (timestamp <= lastTimestamp) {
            timestamp = System.currentTimeMillis();
        }
        return timestamp;
    }
}

package com.example.idgenerator;

import org.springframework.boot.autoconfigure.AutoConfiguration;
import org.springframework.boot.autoconfigure.condition.ConditionalOnMissingBean;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Bean;

/**
 * ID 生成器的自动配置类。
 * 三个条件注解层层把关：
 *  - @ConditionalOnProperty：配置开关 id.generator.enabled 为 true 才生效（默认 true）
 *  - @ConditionalOnMissingBean：使用者已自定义 IdGenerator 时让位，绝不覆盖
 */
@AutoConfiguration
@EnableConfigurationProperties(IdGeneratorProperties.class)
@ConditionalOnProperty(prefix = "id.generator", name = "enabled", havingValue = "true", matchIfMissing = true)
public class IdGeneratorAutoConfiguration {

    @Bean
    @ConditionalOnMissingBean(IdGenerator.class)
    public IdGenerator idGenerator(IdGeneratorProperties properties) {
        // 用配置里的 workerId / datacenterId 构造默认雪花实现
        return new SnowflakeIdGenerator(properties.getWorkerId(), properties.getDatacenterId());
    }
}

cd id-generator-spring-boot-starter
mvn clean install
# 安装到本地 ~/.m2，其他项目即可引用

<dependency>
    <groupId>com.example</groupId>
    <artifactId>id-generator-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

id:
  generator:
    worker-id: 2          # 多实例部署时每台不同
    datacenter-id: 1

@Service
@RequiredArgsConstructor
@Slf4j
public class OrderService {

    private final IdGenerator idGenerator;   // 构造器注入 starter 提供的 Bean

    public long createOrder() {
        long orderId = idGenerator.nextId();
        log.info("生成订单号 {}", orderId);
        return orderId;
    }
}

@AutoConfiguration
@ConditionalOnClass(IdGenerator.class)      // 类级条件：classpath 有 IdGenerator 才解析整类
@EnableConfigurationProperties(IdGeneratorProperties.class)
public class IdGeneratorAutoConfiguration {

    // 方法级条件：仅控制"雪花实现"这个 Bean 是否注册
    @Bean
    @ConditionalOnProperty(prefix = "id.generator", name = "impl", havingValue = "snowflake", matchIfMissing = true)
    @ConditionalOnMissingBean(IdGenerator.class)
    public IdGenerator snowflakeIdGenerator(IdGeneratorProperties p) {
        return new SnowflakeIdGenerator(p.getWorkerId(), p.getDatacenterId());
    }

    // 方法级条件：配置成 uuid 时，改用 UUID 实现（另一个 Bean）
    @Bean
    @ConditionalOnProperty(prefix = "id.generator", name = "impl", havingValue = "uuid")
    @ConditionalOnMissingBean(IdGenerator.class)
    public IdGenerator uuidIdGenerator() {
        return () -> UUID.randomUUID().getMostSignificantBits() & Long.MAX_VALUE;
    }
}

mvn clean package

# 基础运行
java -jar target/demo-0.0.1-SNAPSHOT.jar

# 指定环境
java -jar target/demo-0.0.1-SNAPSHOT.jar --spring.profiles.active=prod

# 覆盖任意配置（优先级最高）
java -jar target/demo-0.0.1-SNAPSHOT.jar 
     --server.port=9090 
     --spring.datasource.password='xxx'

# 后台运行 + 日志重定向（注意 nohup 与 &）
nohup java -jar target/demo-0.0.1-SNAPSHOT.jar > app.out.log 2>&1 &

mvn clean package                         # 只打一个通用包
SPRING_PROFILES_ACTIVE=prod java -jar target/demo-0.0.1-SNAPSHOT.jar

<!-- pom.xml 里定义 Maven profile -->
<profiles>
    <profile>
        <id>prod</id>
        <properties>
            <!-- 打包时激活 prod 环境 -->
            <spring.profiles.active>prod</spring.profiles.active>
        </properties>
    </profile>
</profiles>

mvn clean package -Pprod        # 打出的 jar 内置 prod 配置

# application.yml
server:
  shutdown: graceful                # 开启优雅停机
spring:
  lifecycle:
    timeout-per-shutdown-phase: 30s # 最多等 30 秒让存量请求处理完

# 用 kill 发 SIGTERM（不要用 kill -9，-9 无法优雅停机）
kill <pid>
# 或 systemd 管理时
systemctl stop demo

# 1. 确认打的包正确（不是 .jar.original）
ls -lh target/*.jar

# 2. 本地用生产配置试跑，观察启动日志无 ERROR
SPRING_PROFILES_ACTIVE=prod java -jar target/demo-0.0.1-SNAPSHOT.jar

# 3. 用 --debug 抽查关键自动配置是否按预期生效/失效
java -jar target/demo-0.0.1-SNAPSHOT.jar --debug 2>&1 | grep -A5 "Positive matches"

# 4. 验证敏感信息来自环境变量而非硬编码
grep -r "password" src/main/resources/   # 应只有 ${...} 占位符

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-actuator</artifactId>
</dependency>

# application.yml
management:
  endpoints:
    web:
      exposure:
        include: health,info      # 只暴露 health 和 info，不要全开（安全）
  endpoint:
    health:
      show-details: when-authorized  # 详情需授权，默认不泄露内部信息

# 存活探针：容器编排用它判断要不要重启
curl http://localhost:8080/actuator/health
# {"status":"UP"}

# 就绪探针（组件齐全才 UP，优雅停机时会先变 DOWN，K8s 据此摘流量）
curl http://localhost:8080/actuator/health/readiness
# {"status":"UP"}

# 存活探针
curl http://localhost:8080/actuator/health/liveness
# {"status":"UP"}

# 用 JRE 而非 JDK，镜像更小、攻击面更小
FROM eclipse-temurin:17-jre

# 创建非 root 用户，避免容器内以 root 运行（安全最佳实践）
RUN groupadd -r app && useradd -r -g app app

WORKDIR /app
# 只 COPY 最终 fat jar
COPY target/order-service-1.0.0.jar app.jar

USER app
# ENTRYPOINT 形式：容器内 PID 1 就是 java 进程，能正确收到 SIGTERM 触发优雅停机
ENTRYPOINT ["java", "-jar", "/app/app.jar"]

# 构建并运行
docker build -t order-service:1.0.0 .
docker run -d -p 8080:8080 
  -e SPRING_PROFILES_ACTIVE=prod 
  -e DB_PASSWORD='xxx' 
  --name order-service order-service:1.0.0

# 优雅停机验证：docker stop 默认发 SIGTERM，会走优雅停机
docker stop order-service

<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         https://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <parent>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-parent</artifactId>
        <version>3.2.5</version>
        <relativePath/>
    </parent>

    <groupId>com.example</groupId>
    <artifactId>order-service</artifactId>
    <version>1.0.0</version>

    <properties>
        <java.version>17</java.version>
    </properties>

    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-web</artifactId>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-validation</artifactId>
        </dependency>
        <!-- 自定义 starter：引入即拥有 IdGenerator Bean -->
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>id-generator-spring-boot-starter</artifactId>
            <version>1.0.0</version>
        </dependency>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-test</artifactId>
            <scope>test</scope>
        </dependency>
    </dependencies>

    <build>
        <plugins>
            <plugin>
                <groupId>org.springframework.boot</groupId>
                <artifactId>spring-boot-maven-plugin</artifactId>
            </plugin>
        </plugins>
    </build>
</project>

package com.example.order;

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;

/** 启动类位于根包 com.example.order，保证默认组件扫描覆盖所有子包 */
@SpringBootApplication
public class OrderApplication {
    public static void main(String[] args) {
        SpringApplication.run(OrderApplication.class, args);
    }
}

package com.example.order.properties;

import jakarta.validation.constraints.Min;
import jakarta.validation.constraints.NotBlank;
import lombok.Data;
import org.springframework.boot.context.properties.ConfigurationProperties;
import org.springframework.validation.annotation.Validated;

/** 订单服务的业务配置，绑定 app.* 前缀 */
@Data
@Validated
@ConfigurationProperties(prefix = "app")
public class AppProperties {

    /** 服务名（会出现在日志里，便于多实例区分） */
    @NotBlank
    private String name;

    /** 下单超时时间（秒） */
    @Min(1)
    private int orderTimeoutSeconds = 30;

    /** 订单号生成策略 */
    @NotBlank
    private String idStrategy = "snowflake";
}

package com.example.order.config;

import com.example.order.properties.AppProperties;
import org.springframework.boot.context.properties.EnableConfigurationProperties;
import org.springframework.context.annotation.Configuration;

/** 注册配置类：配置类不碰 @Component，职责纯粹，便于测试 */
@Configuration
@EnableConfigurationProperties(AppProperties.class)
public class AppConfig {
}

package com.example.order.service;

import com.example.idgenerator.IdGenerator;
import com.example.order.properties.AppProperties;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.stereotype.Service;

@Service
@RequiredArgsConstructor
@Slf4j
public class OrderService {

    private final IdGenerator idGenerator;      // 来自自定义 starter
    private final AppProperties appProperties;  // 类型安全配置

    /** 创建订单：生成订单号并记录关键日志 */
    public long createOrder(String sku) {
        long orderId = idGenerator.nextId();
        // 记录关键业务节点：谁、买了什么、订单号多少
        log.info("创建订单成功 orderId={}, sku={}, strategy={}",
                orderId, sku, appProperties.getIdStrategy());
        return orderId;
    }
}

package com.example.order.controller;

import com.example.order.common.ApiResult;
import com.example.order.service.OrderService;
import jakarta.validation.constraints.NotBlank;
import lombok.RequiredArgsConstructor;
import lombok.extern.slf4j.Slf4j;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.GetMapping;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RequestParam;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/api/order")
@RequiredArgsConstructor
@Validated
@Slf4j
public class OrderController {

    private final OrderService orderService;

    @GetMapping("/create")
    public ApiResult<Long> create(@RequestParam @NotBlank(message = "sku 不能为空") String sku) {
        long orderId = orderService.createOrder(sku);
        return ApiResult.ok(orderId);
    }
}