Spring Cloud 多模块公共 Bean 启动报错排查，揭秘 @ConditionalOnProperty 的妙用

在基于 Spring Cloud + Spring Boot 3 的微服务架构中，为了代码的高效复用，我们通常会将工具类封装到 common-base 等公共模块中。但在实际开发中，如果不理清模块依赖与配置文件的关系，这种“复用”极易引发无差别的启动崩溃。

📌 问题背景与模块结构

在近期的项目重构中，项目的模块依赖与配置文件存在如下结构关系：

1. 模块依赖关系： 网关服务（gateway-server）和认证服务（auth-server）都在 pom.xml 中引入了公共模块 common-base。而 common-base 中包含了一个用于 JWT 生成与解析的公共组件 JwtUtil（并且加了 @Component 注解）。

2. Nacos 配置导入关系（引发血案的伏笔）：

   • 我们将公共的 JWT 密钥配置（jwt.secret-key）统一抽离写在了 Nacos 的共享配置文件 application-dev.yml 中。

   • auth-server：在其自身的 yml 文件中，明确导入（import / include）了共享配置 application-dev.yml，因此它能读到 JWT 配置。

   • gateway-server：作为纯粹的路由网关，本身不需要生成和校验具体的业务 Token，因此在它的 yml 中没有导入 application-dev.yml。

触发的灾难： 当启动 gateway-server 时，项目直接崩溃报错，控制台提示 JwtUtil Bean 创建/初始化失败。

🔍 核心痛点与报错原因

问题的根本原因在于 Spring 的自动化扫描机制与微服务配置隔离 产生了冲突：

1. JwtUtil 因为加了 @Component，Spring 容器只要扫描到了它，就会无差别地尝试在所有引入了 common-base 的微服务中去实例化它。

2. 实例化 JwtUtil 时，它的 @PostConstruct 初始化方法需要读取 jwt.secret-key 属性来生成加密对象。

3. 此时，auth-server 因为导入了共享配置，顺利启动；而 gateway-server 没有导入 application-dev.yml，读不到 JWT 密钥，导致初始化遭遇空指针或底层异常，最终将整个网关项目拖垮。

💡 破局之道：@ConditionalOnProperty 条件装配

为了解决这个问题，我们不能简单粗暴地让网关去导入一份对它毫无用处的 JWT 共享配置。最优雅的解法是引入 Spring Boot 的核心机制——按需加载。

只需要在 JwtUtil 类上添加 @ConditionalOnProperty 注解，就能让这个公共组件拥有“自动判断”的能力：

package cn.okcl.utils;

import cn.okcl.properties.JwtProperties;
import io.jsonwebtoken.security.Keys;
import jakarta.annotation.PostConstruct;
import org.springframework.boot.autoconfigure.condition.ConditionalOnProperty;
import org.springframework.stereotype.Component;

import javax.crypto.SecretKey;
import java.nio.charset.StandardCharsets;

@Component
// 🚨 核心注解：只有当当前环境/配置文件中存在 jwt.secret-key 属性时，当前 Bean 才会被实例化
@ConditionalOnProperty(prefix = "jwt", name = "secret-key")
public class JwtUtil {
    
    private final JwtProperties jwtProperties;
    private SecretKey key;

    public JwtUtil(JwtProperties jwtProperties) {
        this.jwtProperties = jwtProperties;
    }

    @PostConstruct
    public void init() {
        // 只有 Bean 被成功实例化时，才会执行密钥初始化逻辑
        this.key = Keys.hmacShaKeyFor(jwtProperties.getSecretKey().getBytes(StandardCharsets.UTF_8));
    }

    // ... 省略具体的 createToken、parseToken 业务逻辑 ...
}

🎯 这个注解到底起了什么作用？

@ConditionalOnProperty(prefix = "jwt", name = "secret-key") 就像是一个前置的安检闸机：

• 当 Spring 准备创建 JwtUtil 时，会先去检查当前微服务的环境中是否加载了 jwt.secret-key 这个配置。

• 在 auth-server 中：因为它导入了 application-dev.yml，配置存在，条件成立，Spring 正常创建该 Bean 并完成初始化。

• 在 gateway-server 中：因为它没有导入该共享配置，条件不成立。Spring Boot 会直接跳过 JwtUtil 的创建。

既然网关中根本没有创建 JwtUtil 这个 Bean，自然就不会触发后续缺少配置导致的报错了。通过这一行注解，我们完美实现了公共 Bean 的解耦与按需加载！

⚠️ 附赠避坑指南：JWT 密钥必须 ≥ 32 字节

在较新的 jjwt 库（如 0.12.x 版本）中，官方对安全规范进行了强制升级。

代码中 Keys.hmacShaKeyFor(bytes) 方法底层使用的是 HMAC-SHA256 算法，该算法在密码学规范上要求：密钥长度必须大于等于 256 bits，即至少 32 个字节（32个字符）。

如果你在共享 YAML 中配置的密钥长度不足 32 位：

jwt:
  # ❌ 错误示范：长度不够，启动时 jjwt 会直接抛出 WeakKeyException 安全异常
  secret-key: my-secret
  
  # ✅ 正确示范：使用长度超过 32 位的复杂随机串
  secret-key: okcl-power-mall-secret-key-88888888 

长度不足时，即使 Bean 被允许加载，项目在执行 @PostConstruct 初始化逻辑时也会抛出 WeakKeyException 并拒绝启动，配置时务必注意。