Spring Boot Starter 自定义开发与企业级组件库构建

Spring Boot Starter 自定义开发与企业级组件库构建 | 极客日志

<!-- 好的命名 -->
<artifactId>spring-boot-starter-data-redis</artifactId>
<artifactId>redis-spring-boot-starter</artifactId>
<!-- 第三方可以这样 -->
<!-- 坏的命名 -->
<artifactId>my-redis-starter</artifactId>
<!-- 没有 spring-boot 前缀 -->
<artifactId>redis-starter-spring-boot</artifactId>
<!-- 顺序不对 -->

<!-- 公司级组件 -->
<artifactId>company-spring-boot-starter-distributed-lock</artifactId>
<!-- 团队级组件 -->
<artifactId>payment-spring-boot-starter-audit</artifactId>
<!-- 通用工具 -->
<artifactId>common-spring-boot-starter-id-generator</artifactId>

// Spring Boot 2.7 之前：用 spring.factories
// META-INF/spring.factories
org.springframework.boot.autoconfigure.EnableAutoConfiguration=\
com.example.MyAutoConfiguration

// Spring Boot 2.7 之后：推荐用@AutoConfiguration
// src/main/resources/META-INF/spring/
// └── org.springframework.boot.autoconfigure.AutoConfiguration.imports
// 文件内容：
com.example.MyAutoConfiguration

// 对应的 Java 代码
@AutoConfiguration
@EnableConfigurationProperties(MyProperties.class)
@ConditionalOnClass(SomeClass.class)
public class MyAutoConfiguration {
    // 配置内容
}

distributed-lock-spring-boot-starter/
├── pom.xml
├── src/
│   ├── main/
│   │   ├── java/
│   │   │   └── com/
│   │   │       └── example/
│   │   │           └── lock/
│   │   │               ├── LockProperties.java # 配置属性
│   │   │               ├── DistributedLock.java # 核心接口
│   │   │               ├── RedisDistributedLock.java # Redis 实现
│   │   │               ├── ZkDistributedLock.java # ZK 实现
│   │   │               ├── LockAutoConfiguration.java # 自动配置
│   │   │               ├── LockAspect.java # AOP 切面
│   │   │               └── annotation/
│   │   │                   └── Lockable.java # 锁注解
│   │   └── resources/
│   │       ├── META-INF/
│   │       │   └── spring/
│   │       │       └── org.springframework.boot.autoconfigure.AutoConfiguration.imports
│   │       └── application-lock.yml # 默认配置
│   └── test/ # 测试代码
└── README.md

@ConfigurationProperties(prefix = "example.lock")
@Validated
public class LockProperties {
    /**
     * 锁类型：redis、zookeeper、database
     */
    @NotEmpty(message = "锁类型不能为空")
    private String type = "redis";

    /**
     * 默认超时时间（毫秒）
     */
    @Min(value = 1, message = "超时时间必须大于 0")
    private long defaultTimeout = 30000;

    /**
     * 默认等待时间（毫秒）
     */
    @Min(value = 0, message = "等待时间不能小于 0")
    private long defaultWaitTime = 10000;

    /**
     * 重试次数
     */
    @Min(value = 0, message = "重试次数不能小于 0")
    private int retryTimes = 3;

    /**
     * Redis 配置（当 type=redis 时生效）
     */
    private RedisConfig redis = new RedisConfig();

    /**
     * Zookeeper 配置（当 type=zookeeper 时生效）
     */
    private ZkConfig zookeeper = new ZkConfig();

    // 嵌套配置类
    @Data
    public static class RedisConfig {
        private String address = "redis://localhost:6379";
        private String password;
        private int database = 0;
        private int connectionPoolSize = 64;
        private int connectionMinimumIdleSize = 24;
    }

    @Data
    public static class ZkConfig {
        private String servers = "localhost:2181";
        private int sessionTimeout = 30000;
        private int connectionTimeout = 15000;
        private String namespace = "example-lock";
    }

    // Getter/Setter省略...
}

public interface DistributedLock {
    /**
     * 获取锁
     * @param lockKey 锁的 key
     * @param timeout 超时时间（毫秒）
     * @param waitTime 等待时间（毫秒）
     * @return 是否获取成功
     */
    boolean tryLock(String lockKey, long timeout, long waitTime);

    /**
     * 获取锁（使用默认配置）
     */
    default boolean tryLock(String lockKey) {
        // 实际项目中这里会从 ThreadLocal 或配置中获取默认值
        return tryLock(lockKey, 30000, 10000);
    }

    /**
     * 释放锁
     */
    void unlock(String lockKey);

    /**
     * 续期锁（防止锁过期）
     */
    boolean renewLock(String lockKey, long expireTime);

    /**
     * 锁监控指标
     */
    LockStats getStats();

    @Data
    class LockStats {
        private long totalAcquireAttempts; // 总获取尝试次数
        private long successfulAcquisitions; // 成功获取次数
        private long failedAcquisitions; // 失败获取次数
        private long averageAcquireTime; // 平均获取时间 (ms)
        private Map<String, Long> keyStats; // 按 key 统计
    }
}

@Slf4j
public class RedisDistributedLock implements DistributedLock {
    private final RedissonClient redissonClient;
    private final LockProperties properties;
    private final ConcurrentHashMap<String, RLock> lockCache = new ConcurrentHashMap<>();
    private final LockStats stats = new LockStats();
    private final AtomicLong totalAcquireAttempts = new AtomicLong();
    private final AtomicLong successfulAcquisitions = new AtomicLong();

    public RedisDistributedLock(LockProperties properties) {
        this.properties = properties;
        Config config = new Config();
        RedisConfig redisConfig = properties.getRedis();
        config.useSingleServer()
                .setAddress(redisConfig.getAddress())
                .setPassword(redisConfig.getPassword())
                .setDatabase(redisConfig.getDatabase())
                .setConnectionPoolSize(redisConfig.getConnectionPoolSize())
                .setConnectionMinimumIdleSize(redisConfig.getConnectionMinimumIdleSize());
        this.redissonClient = Redisson.create(config);
    }

    @Override
    public boolean tryLock(String lockKey, long timeout, long waitTime) {
        totalAcquireAttempts.incrementAndGet();
        long startTime = System.currentTimeMillis();
        try {
            RLock lock = lockCache.computeIfAbsent(lockKey, key -> redissonClient.getLock(key));
            boolean acquired = lock.tryLock(waitTime, timeout, TimeUnit.MILLISECONDS);
            if (acquired) {
                successfulAcquisitions.incrementAndGet();
                long costTime = System.currentTimeMillis() - startTime;
                // 记录监控指标
                synchronized (stats) {
                    stats.setAverageAcquireTime(
                            (stats.getAverageAcquireTime() * (successfulAcquisitions.get() - 1) + costTime) / successfulAcquisitions.get()
                    );
                    stats.getKeyStats().merge(lockKey, 1L, Long::sum);
                }
                log.debug("成功获取锁：{}, 耗时：{}ms", lockKey, costTime);
            } else {
                log.warn("获取锁失败：{}, 等待时间：{}ms", lockKey, waitTime);
            }
            return acquired;
        } catch (InterruptedException e) {
            Thread.currentThread().interrupt();
            log.error("获取锁被中断：{}", lockKey, e);
            return false;
        } catch (Exception e) {
            log.error("获取锁异常：{}", lockKey, e);
            return false;
        } finally {
            stats.setTotalAcquireAttempts(totalAcquireAttempts.get());
            stats.setSuccessfulAcquisitions(successfulAcquisitions.get());
            stats.setFailedAcquisitions(totalAcquireAttempts.get() - successfulAcquisitions.get());
        }
    }

    @Override
    public void unlock(String lockKey) {
        try {
            RLock lock = lockCache.get(lockKey);
            if (lock != null && lock.isHeldByCurrentThread()) {
                lock.unlock();
                log.debug("释放锁：{}", lockKey);
            }
        } catch (Exception e) {
            log.error("释放锁异常：{}", lockKey, e);
        }
    }

    // 其他方法实现省略...
}

@AutoConfiguration
@EnableConfigurationProperties(LockProperties.class)
@ConditionalOnClass(RedissonClient.class)
@ConditionalOnProperty(prefix = "example.lock", name = "enabled", havingValue = "true", matchIfMissing = true)
@AutoConfigureAfter(RedisAutoConfiguration.class)
public class LockAutoConfiguration {
    private static final Logger log = LoggerFactory.getLogger(LockAutoConfiguration.class);

    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnProperty(prefix = "example.lock", name = "type", havingValue = "redis", matchIfMissing = true)
    public DistributedLock redisDistributedLock(LockProperties properties) {
        log.info("初始化 Redis 分布式锁，地址：{}", properties.getRedis().getAddress());
        return new RedisDistributedLock(properties);
    }

    @Bean
    @ConditionalOnMissingBean
    @ConditionalOnProperty(prefix = "example.lock", name = "type", havingValue = "zookeeper")
    @ConditionalOnClass(value = {CuratorFramework.class, InterProcessMutex.class})
    public DistributedLock zookeeperDistributedLock(LockProperties properties) {
        log.info("初始化 Zookeeper 分布式锁，servers: {}", properties.getZookeeper().getServers());
        return new ZkDistributedLock(properties);
    }

    @Bean
    @ConditionalOnMissingBean
    public LockAspect lockAspect(DistributedLock distributedLock) {
        return new LockAspect(distributedLock);
    }

    @Bean
    public LockHealthIndicator lockHealthIndicator(DistributedLock distributedLock) {
        return new LockHealthIndicator(distributedLock);
    }

    @Bean
    public LockMetrics lockMetrics(DistributedLock distributedLock) {
        return new LockMetrics(distributedLock);
    }
}

@Aspect
@Component
@ConditionalOnBean(DistributedLock.class)
public class LockAspect {
    private final DistributedLock distributedLock;

    public LockAspect(DistributedLock distributedLock) {
        this.distributedLock = distributedLock;
    }

    @Around("@annotation(lockable)")
    public Object aroundLock(ProceedingJoinPoint joinPoint, Lockable lockable) throws Throwable {
        String lockKey = generateLockKey(joinPoint, lockable);
        try {
            // 尝试获取锁
            boolean acquired = distributedLock.tryLock(
                    lockKey, lockable.timeout(), lockable.waitTime()
            );
            if (!acquired) {
                throw new LockAcquireException("获取锁失败：" + lockKey);
            }
            // 执行业务方法
            return joinPoint.proceed();
        } finally {
            // 释放锁
            distributedLock.unlock(lockKey);
        }
    }

    private String generateLockKey(ProceedingJoinPoint joinPoint, Lockable lockable) {
        MethodSignature signature = (MethodSignature) joinPoint.getSignature();
        Method method = signature.getMethod();
        // 支持 SpEL 表达式
        if (StringUtils.hasText(lockable.key())) {
            return evaluateSpel(lockable.key(), joinPoint);
        }
        // 默认生成规则：类名 + 方法名 + 参数 hash
        String className = method.getDeclaringClass().getSimpleName();
        String methodName = method.getName();
        String argsHash = Arrays.hashCode(joinPoint.getArgs()) + "";
        return String.format("%s.%s.%s", className, methodName, argsHash);
    }

    private String evaluateSpel(String expression, ProceedingJoinPoint joinPoint) {
        // SpEL 表达式解析实现
        // ...
        return expression;
    }
}

@Component
public class LockHealthIndicator implements HealthIndicator {
    private final DistributedLock distributedLock;

    public LockHealthIndicator(DistributedLock distributedLock) {
        this.distributedLock = distributedLock;
    }

    @Override
    public Health health() {
        DistributedLock.LockStats stats = distributedLock.getStats();
        // 计算成功率
        double successRate = stats.getTotalAcquireAttempts() > 0 ?
                (double) stats.getSuccessfulAcquisitions() / stats.getTotalAcquireAttempts() * 100 : 0;
        Map<String, Object> details = new HashMap<>();
        details.put("successRate", String.format("%.2f%%", successRate));
        details.put("totalAttempts", stats.getTotalAcquireAttempts());
        details.put("successCount", stats.getSuccessfulAcquisitions());
        details.put("avgAcquireTime", stats.getAverageAcquireTime() + "ms");
        if (successRate < 95.0) {
            return Health.down()
                    .withDetail("message", "锁获取成功率过低")
                    .withDetails(details)
                    .build();
        }
        return Health.up()
                .withDetails(details)
                .build();
    }
}

// additional-spring-configuration-metadata.json
{
  "properties": [
    {
      "name": "example.lock.enabled",
      "type": "java.lang.Boolean",
      "description": "是否启用分布式锁",
      "defaultValue": true
    },
    {
      "name": "example.lock.type",
      "type": "java.lang.String",
      "description": "锁类型：redis 或 zookeeper",
      "defaultValue": "redis"
    },
    {
      "name": "example.lock.default-timeout",
      "type": "java.lang.Long",
      "description": "默认锁超时时间（毫秒）",
      "defaultValue": 30000,
      "sourceType": "com.example.lock.LockProperties"
    },
    {
      "name": "example.lock.redis.address",
      "type": "java.lang.String",
      "description": "Redis 地址",
      "defaultValue": "redis://localhost:6379"
    },
    {
      "name": "example.lock.zookeeper.servers",
      "type": "java.lang.String",
      "description": "Zookeeper 服务器地址",
      "defaultValue": "localhost:2181"
    }
  ],
  "hints": [
    {
      "name": "example.lock.type",
      "values": [
        {
          "value": "redis",
          "description": "基于 Redis 的分布式锁"
        },
        {
          "value": "zookeeper",
          "description": "基于 Zookeeper 的分布式锁"
        }
      ]
    }
  ]
}

# 分布式锁默认配置
example:
  lock:
    enabled: true
    type: redis
    default-timeout: 30000
    default-wait-time: 10000
    retry-times: 3
    redis:
      address: ${REDIS_HOST:redis://localhost:6379}
      password: ${REDIS_PASSWORD:}
      database: 0
      connection-pool-size: 64
      connection-minimum-idle-size: 24
    zookeeper:
      servers: ${ZK_HOST:localhost:2181}
      session-timeout: 30000
      connection-timeout: 15000
      namespace: example-lock

<dependency>
    <groupId>com.example</groupId>
    <artifactId>distributed-lock-spring-boot-starter</artifactId>
    <version>1.0.0</version>
</dependency>

# application.yml
example:
  lock:
    type: redis
    redis:
      address: redis://prod-redis:6379
    default-timeout: 60000 # 生产环境可以设长一点

@Service
public class OrderService {
    @Lockable(key = "'order:' + #orderId", timeout = 30000)
    public Order createOrder(String orderId, OrderRequest request) {
        // 业务逻辑，自动加锁
        return orderRepository.save(convertToOrder(request));
    }

    @Lockable(key = "'inventory:' + #productId", waitTime = 5000)
    public void reduceInventory(String productId, int quantity) {
        // 最多等待 5 秒获取锁
        inventoryService.reduce(productId, quantity);
    }
}

@Service
public class PaymentService {
    @Autowired
    private DistributedLock distributedLock;

    public void processPayment(String paymentId) {
        String lockKey = "payment:" + paymentId;
        try {
            if (distributedLock.tryLock(lockKey)) {
                // 执行业务逻辑
                paymentProcessor.process(paymentId);
            } else {
                throw new BusinessException("系统繁忙，请稍后重试");
            }
        } finally {
            distributedLock.unlock(lockKey);
        }
    }
}

<!-- 版本号规范 -->
<version>主版本。次版本。修订版本 - 里程碑</version>
<!-- 例如：1.2.3-RELEASE -->
<!-- 实际例子 -->
<version>1.0.0</version> <!-- 第一个稳定版 -->
<version>1.1.0</version> <!-- 新增功能，向后兼容 -->
<version>2.0.0</version> <!-- 破坏性变更 -->

public interface DistributedLock {
    // v1.0 的方法
    boolean tryLock(String lockKey, long timeout, long waitTime);

    // v1.1 新增的方法（默认实现保证兼容）
    default boolean tryLock(String lockKey, LockOptions options) {
        return tryLock(lockKey, options.getTimeout(), options.getWaitTime());
    }

    // v1.0 的方法，v2.0 计划删除
    @Deprecated(since = "2.0.0", forRemoval = true)
    boolean oldMethod(String param);
}

@Bean
@Lazy // 只有实际使用时才初始化
public DistributedLock distributedLock(LockProperties properties) {
    // 初始化逻辑
}

@Configuration
public class LockAutoConfiguration {
    @Bean
    @ConditionalOnMissingBean
    public RedissonClient redissonClient(LockProperties properties) {
        // 如果应用中已经有 RedissonClient，直接复用
        // 避免创建多个连接池
    }
}

public class RedisDistributedLock {
    // 使用 WeakHashMap，避免内存泄漏
    private final Map<String, WeakReference<RLock>> lockCache = Collections.synchronizedMap(new WeakHashMap<>());
}

@Component
public class LockMetrics implements MeterBinder {
    private final DistributedLock distributedLock;

    public LockMetrics(DistributedLock distributedLock) {
        this.distributedLock = distributedLock;
    }

    @Override
    public void bindTo(MeterRegistry registry) {
        Gauge.builder("example.lock.success.rate", () -> calculateSuccessRate())
                .description("锁获取成功率")
                .baseUnit("percent")
                .register(registry);
        Timer.builder("example.lock.acquire.time")
                .description("锁获取耗时")
                .publishPercentiles(0.5, 0.95, 0.99) // 50%, 95%, 99%分位
                .register(registry);
    }

    private double calculateSuccessRate() {
        DistributedLock.LockStats stats = distributedLock.getStats();
        if (stats.getTotalAcquireAttempts() == 0) {
            return 100.0;
        }
        return (double) stats.getSuccessfulAcquisitions() / stats.getTotalAcquireAttempts() * 100;
    }
}

groups:
  - name: lock_alerts
    rules:
      - alert: LockSuccessRateLow
        expr: example_lock_success_rate < 95
        for: 5m
        labels:
          severity: warning
        annotations:
          summary: "锁获取成功率过低"
          description: "锁获取成功率低于 95%，当前值：{{ $value }}%"

@ExtendWith(MockitoExtension.class)
class RedisDistributedLockTest {
    @Mock
    private RedissonClient redissonClient;

    @Mock
    private RLock rLock;

    private RedisDistributedLock distributedLock;

    @BeforeEach
    void setUp() {
        LockProperties properties = new LockProperties();
        properties.setType("redis");
        when(redissonClient.getLock(anyString())).thenReturn(rLock);
        // 通过反射设置 redissonClient
        distributedLock = new RedisDistributedLock(properties);
        setField(distributedLock, "redissonClient", redissonClient);
    }

    @Test
    void testTryLock_Success() throws InterruptedException {
        // given
        when(rLock.tryLock(anyLong(), anyLong(), any())).thenReturn(true);
        // when
        boolean result = distributedLock.tryLock("test-key", 30000, 10000);
        // then
        assertTrue(result);
        verify(rLock).tryLock(10000, 30000, TimeUnit.MILLISECONDS);
    }

    @Test
    void testTryLock_Timeout() throws InterruptedException {
        // given
        when(rLock.tryLock(anyLong(), anyLong(), any())).thenReturn(false);
        // when
        boolean result = distributedLock.tryLock("test-key", 30000, 10000);
        // then
        assertFalse(result);
    }
}

@SpringBootTest
@AutoConfigureMockMvc
@Testcontainers // 使用 Testcontainers 启动真实 Redis
class DistributedLockIntegrationTest {
    @Container
    static RedisContainer redis = new RedisContainer("redis:6.2")
            .withExposedPorts(6379);

    @DynamicPropertySource
    static void redisProperties(DynamicPropertyRegistry registry) {
        registry.add("example.lock.redis.address", () -> String.format("redis://%s:%d", redis.getHost(), redis.getFirstMappedPort()));
    }

    @Autowired
    private DistributedLock distributedLock;

    @Test
    void testDistributedLockInRealRedis() {
        // given
        String lockKey = "integration-test-key";
        // when
        boolean acquired = distributedLock.tryLock(lockKey, 5000, 1000);
        // then
        assertTrue(acquired);
        // 再次获取应该失败
        boolean acquiredAgain = distributedLock.tryLock(lockKey, 5000, 1000);
        assertFalse(acquiredAgain);
        // 释放后可以再次获取
        distributedLock.unlock(lockKey);
        boolean acquiredAfterRelease = distributedLock.tryLock(lockKey, 5000, 1000);
        assertTrue(acquiredAfterRelease);
    }
}

@SpringBootTest
@Tag("performance")
class DistributedLockPerformanceTest {
    @Autowired
    private DistributedLock distributedLock;

    @Test
    @RepeatedTest(10) // 重复 10 次
    void testLockAcquirePerformance() {
        // warm up
        IntStream.range(0, 1000).parallel().forEach(i -> {
            distributedLock.tryLock("perf-" + i, 1000, 100);
        });
        // actual test
        long startTime = System.nanoTime();
        IntStream.range(0, 10000).parallel().forEach(i -> {
            distributedLock.tryLock("perf-" + i, 1000, 100);
        });
        long duration = System.nanoTime() - startTime;
        double avgTime = duration / 10000.0 / 1_000_000.0; // 转换为毫秒
        System.out.printf("平均获取锁时间：%.3f ms%n", avgTime);
        // 断言：平均时间应小于 1ms
        assertTrue(avgTime < 1.0, "锁获取时间过长：" + avgTime + "ms");
    }
}

<!-- pom.xml 配置 -->
<project>
    <modelVersion>4.0.0</modelVersion>
    <groupId>com.example</groupId>
    <artifactId>distributed-lock-spring-boot-starter</artifactId>
    <version>1.0.0</version>
    <packaging>jar</packaging>
    <name>Example Distributed Lock Starter</name>
    <description>Spring Boot Starter for distributed lock</description>
    <!-- 许可证信息 -->
    <licenses>
        <license>
            <name>Apache License, Version 2.0</name>
            <url>https://www.apache.org/licenses/LICENSE-2.0</url>
        </license>
    </licenses>
    <!-- SCM 信息 -->
    <scm>
        <url>https://github.com/example/distributed-lock-starter</url>
        <connection>scm:git:git://github.com/example/distributed-lock-starter.git</connection>
        <developerConnection>scm:git:ssh://github.com/example/distributed-lock-starter.git</developerConnection>
    </scm>
    <!-- 开发者信息 -->
    <developers>
        <developer>
            <name>Your Name</name>
            <email>[email protected]</email>
            <organization>Example Inc.</organization>
        </developer>
    </developers>
    <!-- 发布到 Maven 仓库的配置 -->
    <distributionManagement>
        <repository>
            <id>example-releases</id>
            <url>https://maven.example.com/repository/releases</url>
        </repository>
        <snapshotRepository>
            <id>example-snapshots</id>
            <url>https://maven.example.com/repository/snapshots</url>
        </snapshotRepository>
    </distributionManagement>
</project>

<dependencyManagement>
    <dependencies>
        <!-- 统一管理 Spring Boot 版本 -->
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>${spring-boot.version}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>
<dependencies>
    <!-- 必须的依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
        <scope>compile</scope>
        <!-- 注意：不要带版本号，由 dependencyManagement 管理 -->
    </dependency>
    <!-- 可选依赖：用户想用 Redis 锁时才需要 -->
    <dependency>
        <groupId>org.redisson</groupId>
        <artifactId>redisson-spring-boot-starter</artifactId>
        <scope>provided</scope>
        <!-- 关键！provided 作用域 -->
        <optional>true</optional>
        <!-- 标记为可选 -->
    </dependency>
    <!-- 测试依赖 -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-test</artifactId>
        <scope>test</scope>
    </dependency>
</dependencies>

example-spring-boot-starters/
# 父项目
├── example-spring-boot-starter-parent # 父 pom，统一管理
├── example-spring-boot-starter-lock # 分布式锁
├── example-spring-boot-starter-id # ID 生成器
├── example-spring-boot-starter-mq # 消息队列
├── example-spring-boot-starter-cache # 缓存
├── example-spring-boot-starter-trace # 链路追踪
└── example-spring-boot-starter-all # 全家桶（可选）

<!-- example-spring-boot-starter-cache 的 pom.xml -->
<dependencies>
    <!-- 内部依赖：先于其他 Starter 发布 -->
    <dependency>
        <groupId>com.example</groupId>
        <artifactId>example-spring-boot-starter-lock</artifactId>
        <version>${project.version}</version>
        <optional>true</optional>
    </dependency>
</dependencies>

// 公共配置类
@ConfigurationProperties(prefix = "example")
public class ExampleCommonProperties {
    /**
     * 公共 Redis 配置
     */
    private RedisCommonConfig redis = new RedisCommonConfig();

    /**
     * 公共 Zookeeper 配置
     */
    private ZkCommonConfig zookeeper = new ZkCommonConfig();

    /**
     * 监控配置
     */
    private MonitorConfig monitor = new MonitorConfig();

    @Data
    public static class RedisCommonConfig {
        private String address = "redis://localhost:6379";
        private String password;
        private int database = 0;
    }

    // 其他配置类...
}

// 在各个 Starter 中引用
@ConfigurationProperties(prefix = "example.lock")
public class LockProperties {
    @Autowired
    private ExampleCommonProperties commonProperties;

    // 优先使用专属配置，没有则用公共配置
    public String getRedisAddress() {
        return StringUtils.hasText(redis.getAddress()) ? redis.getAddress() : commonProperties.getRedis().getAddress();
    }
}

# 启动时加参数查看自动配置报告
java -jar app.jar --debug
# 或者在代码中获取
@Autowired
private List<String> autoConfigurations;

@Bean
@ConditionalOnMissingBean // 关键：用户有自定义时，不用我们的
public SomeBean someBean() {
    return new SomeBean();
}

// 或者用@Primary 指定优先级
@Bean
@Primary
public SomeBean defaultSomeBean() {
    return new SomeBean();
}

// 在 Starter 中添加配置验证
@PostConstruct
public void validateConfig() {
    if (!isValid(config)) {
        throw new IllegalStateException("配置无效：" + config);
    }
}

// 在自动配置类中加断点
@AutoConfiguration
public class MyAutoConfiguration {
    public MyAutoConfiguration() {
        // 这里加断点，可以看到什么时候被加载
        System.out.println("MyAutoConfiguration 被加载");
    }
}

@SpringBootApplication
public class Application {
    public static void main(String[] args) {
        SpringApplication app = new SpringApplication(Application.class);
        // 添加监听器，输出条件评估报告
        app.addListeners(new ApplicationListener<ApplicationPreparedEvent>() {
            @Override
            public void onApplicationEvent(ApplicationPreparedEvent event) {
                ConditionEvaluationReport report = ConditionEvaluationReport.get(event.getApplicationContext().getBeanFactory());
                // 打印报告到文件
                try (PrintWriter writer = new PrintWriter("condition-report.txt")) {
                    report.getConditionAndOutcomesBySource().forEach((source, outcomes) -> {
                        writer.println(source);
                        outcomes.forEach(outcome -> {
                            writer.println(" " + outcome.getOutcome());
                        });
                    });
                }
            }
        });
        app.run(args);
    }
}

# application.yml
management:
  endpoints:
    web:
      exposure:
        include: conditions,beans,configprops

Spring Boot Starter 自定义开发与企业级组件库构建

Spring Boot Starter 自定义开发指南

1. 别急着写代码，先想清楚这几个问题

1.1 什么样的组件适合做成 Starter？

✅ 标准一：跨项目复用性强

✅ 标准二：配置复杂但模式固定

✅ 标准三：需要统一管理和升级

1.2 Starter 的命名规范：别瞎起名

2. Starter 的核心架构：不只是@Configuration

2.1 一个完整 Starter 的组成

2.2 自动装配的原理再深入一点

3. 实战：手把手写一个分布式锁 Starter

3.1 需求分析：我们要解决什么问题？

3.2 项目结构设计

3.3 核心代码实现

第一步：定义配置属性

第二步：定义核心接口

第三步：实现 Redis 分布式锁

第四步：自动配置类

第五步：AOP 切面支持注解式锁

第六步：健康检查

3.4 配置元数据：让 IDE 智能提示

3.5 默认配置文件

4. Starter 的使用：简单到哭

4.1 Maven 依赖

4.2 配置（可选）

4.3 使用方式

方式一：注解式（推荐）

方式二：编程式

4.4 监控查看

5. 企业级 Starter 的高级特性

5.1 多版本兼容：向前向后都要考虑

版本策略

兼容性保证

5.2 性能优化：Starter 不能拖慢应用

优化点一：懒加载

优化点二：连接池复用

优化点三：缓存优化

5.3 监控告警：出了问题要知道

6. Starter 的测试策略

6.1 单元测试：保证代码质量

6.2 集成测试：验证真实环境

6.3 性能测试：确保不影响应用性能

7. Starter 的发布与治理

7.1 Maven 发布配置

7.2 版本管理策略

7.3 依赖管理

8. 企业级 Starter 架构演进

8.1 从单一 Starter 到 Starter 套件

8.2 Starter 的依赖关系管理

8.3 配置的统一管理

9. 故障排查与调试

9.1 常见问题排查清单

问题 1：自动配置不生效

问题 2：Bean 冲突

问题 3：配置属性不生效

9.2 调试技巧

技巧 1：在 IDE 中调试自动配置

技巧 2：查看条件评估报告

技巧 3：使用 Spring Boot Actuator 端点

10. 最后的话：Starter 开发的"道"与"术"

📚 推荐阅读

官方文档

源码学习

最佳实践

工具资源

微信扫一扫，关注极客日志

更多推荐文章

相关免费在线工具