Spring Boot 自动装配的优雅延伸：自定义 Starter 开发全流程与生产级实践指南

flowchart TB
    A[应用启动] --> B[@EnableAutoConfiguration]
    B --> C[AutoConfigurationImportSelector]
    C --> D{扫描配置文件}
    D -->|Spring Boot 2.x| E[META-INF/spring.factories]
    D -->|Spring Boot 3.x| F[META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports]
    E & F --> G[加载 @Configuration 类]
    G --> H{条件过滤}
    H -->|@ConditionalOnClass| I[类路径中存在指定类?]
    H -->|@ConditionalOnProperty| J[配置项匹配?]
    H -->|@ConditionalOnMissingBean| K[容器中无同名 Bean?]
    I & J & K -->|通过| L[注册 Bean 到容器]
    I & J & K -->|未通过| M[跳过该配置类]

trace-id-spring-boot-starter/
├── build.gradle
└── src/main/
    ├── java/com/example/trace/
    │   ├── TraceIdAutoConfiguration.java
    │   ├── TraceIdProperties.java
    │   ├── TraceIdFilter.java
    │   └── TraceIdConstants.java
    └── resources/
        └── META-INF/spring/
            └── org.springframework.boot.autoconfigure.AutoConfiguration.imports

/**
 * Trace ID Starter 配置属性
 * 通过 @ConfigurationProperties 绑定前缀，提供类型安全的配置访问
 */
@ConfigurationProperties(prefix = "trace.id")
public class TraceIdProperties {
    /** 是否启用 Trace ID 自动注入，默认启用 */
    private boolean enabled = true;
    /** Trace ID 的 HTTP Header 名称 */
    private String headerName = "X-Trace-Id";
    /** MDC 中 Trace ID 的 key */
    private String mdcKey = "traceId";
    /** Trace ID 生成策略：UUID 或 SNOWFLAKE */
    private IdGenerator generator = IdGenerator.UUID;
    /** Trace ID 长度限制（仅对 SNOWFLAKE 策略有效） */
    private int idLength = 32;
    /** 当上游已携带 Trace ID 时，是否覆盖 */
    private boolean overrideExisting = false;
    // getter/setter 省略，实际开发中必须提供
    public enum IdGenerator {
        UUID, SNOWFLAKE
    }
}

/**
 * Trace ID 注入过滤器
 * 在请求入口处生成或提取 Trace ID，注入 MDC 供日志框架使用
 * 请求结束后清理 MDC，防止线程池复用导致的 ID 污染
 */
@Order(Ordered.HIGHEST_PRECEDENCE)
public class TraceIdFilter implements Filter {
    private final TraceIdProperties properties;
    public TraceIdFilter(TraceIdProperties properties) {
        this.properties = properties;
    }
    @Override
    public void doFilter(ServletRequest request, ServletResponse response,
                         FilterChain chain) throws IOException, ServletException {
        HttpServletRequest httpRequest = (HttpServletRequest) request;
        HttpServletResponse httpResponse = (HttpServletResponse) response;
        String traceId = resolveTraceId(httpRequest);
        // 注入 MDC，日志框架可通过 %X{traceId} 输出
        MDC.put(properties.getMdcKey(), traceId);
        // 写入响应 Header，便于前端或网关追踪
        httpResponse.setHeader(properties.getHeaderName(), traceId);
        try {
            chain.doFilter(request, response);
        } finally {
            // 必须在 finally 中清理，防止线程池复用导致 MDC 残留
            MDC.remove(properties.getMdcKey());
        }
    }
    /**
     * 解析 Trace ID：优先从上游 Header 获取，否则按策略生成
     */
    private String resolveTraceId(HttpServletRequest request) {
        String existingId = request.getHeader(properties.getHeaderName());
        if (existingId != null && !existingId.isEmpty() && !properties.isOverrideExisting()) {
            return existingId;
        }
        return generateTraceId();
    }
    private String generateTraceId() {
        if (properties.getGenerator() == TraceIdProperties.IdGenerator.SNOWFLAKE) {
            // 雪花算法生成有序 ID，便于日志排序
            return String.valueOf(SnowflakeIdGenerator.nextId());
        }
        return UUID.randomUUID().toString().replace("-", "");
    }
}

/**
 * Trace ID 自动装配配置类
 * 仅在 Web 环境且用户未自定义 TraceIdFilter 时生效
 */
@AutoConfiguration
@ConditionalOnWebApplication
@ConditionalOnProperty(name = "trace.id.enabled", havingValue = "true",
                       matchIfMissing = true)
@EnableConfigurationProperties(TraceIdProperties.class)
public class TraceIdAutoConfiguration {
    /**
     * 注册 Trace ID 过滤器
     * @ConditionalOnMissingBean 保证用户自定义的 Filter 优先
     */
    @Bean
    @ConditionalOnMissingBean(TraceIdFilter.class)
    public TraceIdFilter traceIdFilter(TraceIdProperties properties) {
        return new TraceIdFilter(properties);
    }
    /**
     * 注册异步场景的 Trace ID 传播装饰器
     * 确保 @Async 方法中也能获取到 Trace ID
     */
    @Bean
    @ConditionalOnMissingBean
    public TraceIdTaskDecorator traceIdTaskDecorator(TraceIdProperties properties) {
        return new TraceIdTaskDecorator(properties);
    }
}
/**
 * 异步任务装饰器：将父线程的 Trace ID 传播到子线程
 * 解决 @Async 场景下 MDC 丢失的问题
 */
public class TraceIdTaskDecorator implements TaskDecorator {
    private final TraceIdProperties properties;
    @Override
    public Runnable decorate(Runnable runnable) {
        // 捕获父线程的 Trace ID
        String traceId = MDC.get(properties.getMdcKey());
        return () -> {
            try {
                if (traceId != null) {
                    MDC.put(properties.getMdcKey(), traceId);
                }
                runnable.run();
            } finally {
                MDC.remove(properties.getMdcKey());
            }
        };
    }
}

# src/main/resources/META-INF/spring/
# org.springframework.boot.autoconfigure.AutoConfiguration.imports
com.example.trace.TraceIdAutoConfiguration