Spring Boot项目启动时Banner自定义无效的配置加载顺序解析 - 智猿学院-前后端，数据库，人工智能，云计算等领域前沿技术讲座

Spring Boot Banner 自定义失效问题深度解析：配置加载顺序与优先级

大家好，今天我们来深入探讨一个在 Spring Boot 开发中经常遇到的问题：Banner 自定义失效。很多开发者尝试自定义 Spring Boot 启动时的 Banner，但最终却未能如愿，要么显示默认 Banner，要么根本没有任何 Banner 显示。这通常与 Spring Boot 的配置加载顺序和优先级有关。本次讲座将详细解析 Spring Boot Banner 的工作机制，分析可能导致自定义失效的原因，并提供切实可行的解决方案。

1. Spring Boot Banner 的工作机制

Spring Boot 启动时，会在控制台输出一段 Banner 信息，默认情况下是 Spring Boot 的 Logo 和版本号。这个 Banner 可以通过多种方式进行自定义。Spring Boot 寻找 Banner 的顺序如下：

在 classpath 下查找 banner.txt 文件。
在 classpath 下查找 banner.gif、banner.jpg 或 banner.png 文件。
如果以上文件都没有找到，则使用默认的 Spring Boot Banner。

这个查找过程实际上遵循了 Spring Boot 的配置加载顺序，理解这个顺序是解决问题的关键。

2. Banner 配置的几种方式

自定义 Banner 主要有以下几种方式：

banner.txt 文件： 这是最常用的方式，将自定义的 ASCII Art 文本内容放入 banner.txt 文件中，Spring Boot 会读取并显示。
图片文件： Spring Boot 支持 banner.gif、banner.jpg 和 banner.png 格式的图片作为 Banner。图片会被转换为 ASCII Art 显示。
编程方式： 通过实现 Banner 接口，可以编写自定义的 Banner 生成逻辑。
spring.main.banner-mode 配置： 通过设置 spring.main.banner-mode 属性，可以控制 Banner 的显示模式。

3. 常见问题与原因分析

尽管自定义 Banner 的方式看似简单，但在实际应用中，却常常遇到以下问题：

自定义 banner.txt 不生效： 这是最常见的问题，原因可能有很多，包括文件位置错误、编码问题、配置优先级冲突等。
图片 Banner 显示效果不佳： 由于图片会被转换为 ASCII Art，因此显示效果可能与预期不符。
编程方式自定义 Banner 不生效： 可能由于 Bean 没有被正确加载，或者配置优先级较低。
Banner 完全不显示： 可能是由于 spring.main.banner-mode 配置不正确，或者存在其他导致 Banner 输出被禁用的配置。

接下来，我们将逐一分析这些问题，并提供相应的解决方案。

4. 配置加载顺序与优先级

Spring Boot 遵循一套严格的配置加载顺序和优先级规则。理解这些规则对于解决 Banner 自定义失效问题至关重要。Spring Boot 配置的加载顺序如下（优先级由高到低）：

命令行参数
来自 java:comp/env 的 JNDI 属性
JVM 系统属性 (System.getProperties())
操作系统环境变量
RandomValuePropertySource 生成的随机值
Profile-specific 的 application properties 文件（application-{profile}.properties 或 application-{profile}.yml）
application properties 文件（application.properties 或 application.yml）
通过 @PropertySource 注解配置的 properties 文件
默认属性（通过 SpringApplication.setDefaultProperties 指定）

请注意，上面加粗的两项与 banner.txt 的加载密切相关。

5. banner.txt 不生效的详细原因分析与解决方案

文件位置错误：

banner.txt 必须位于 classpath 的根目录下。这意味着，在 Maven 项目中，它应该放在 src/main/resources 目录下。如果放在其他位置，Spring Boot 将无法找到它。

解决方案： 确保 banner.txt 文件位于 src/main/resources 目录下。
编码问题：

banner.txt 应该使用 UTF-8 编码。如果使用其他编码，可能会导致乱码或者无法正确解析。

解决方案： 使用文本编辑器（如 Notepad++、Sublime Text 或 IntelliJ IDEA）将 banner.txt 保存为 UTF-8 编码。
配置优先级冲突：

如果 application.properties 或 application.yml 中定义了 spring.main.banner-mode 属性，并且将其设置为 off，则会禁用 Banner 输出。

解决方案： 检查 application.properties 和 application.yml 文件，确保 spring.main.banner-mode 属性没有被设置为 off。如果存在，将其删除或设置为 console（默认值）。

示例：
```
# 禁用 Banner 输出
# spring.main.banner-mode=off

# 启用 Banner 输出 (默认)
spring.main.banner-mode=console
```
缓存问题：

在某些情况下，IDE 或构建工具可能会缓存旧的 banner.txt 文件。

解决方案： 清理项目并重新构建。在 IntelliJ IDEA 中，可以使用 "Build" -> "Rebuild Project" 命令。在 Maven 项目中，可以使用 mvn clean install 命令。
多模块项目问题：

如果项目是多模块结构，确保 banner.txt 位于启动模块的 src/main/resources 目录下。

解决方案： 确认启动模块的 src/main/resources 目录下存在 banner.txt。
资源过滤问题：

Maven 的 pom.xml 文件中可能配置了资源过滤，导致 banner.txt 文件被错误处理。

解决方案： 检查 pom.xml 文件中 <resources> 标签的配置，确保 banner.txt 文件没有被排除在外。

示例：
```
<build>
    <resources>
        <resource>
            <directory>src/main/resources</directory>
            <includes>
                <include>**/*</include>
            </includes>
        </resource>
    </resources>
</build>
```

6. 图片 Banner 显示效果不佳的解决方案

由于图片会被转换为 ASCII Art 显示，因此显示效果可能与预期不符。可以尝试以下方法优化显示效果：

选择合适的图片： 选择线条简单、对比度高的图片。
调整图片大小： 尝试不同的图片大小，找到最佳的显示效果。
使用专业的 ASCII Art 生成工具： 使用专业的 ASCII Art 生成工具将图片转换为文本，然后保存为 banner.txt 文件。

7. 编程方式自定义 Banner 不生效的解决方案

如果使用编程方式自定义 Banner，需要确保以下几点：

实现 Banner 接口： 创建一个类，实现 org.springframework.boot.Banner 接口。
注册为 Spring Bean： 使用 @Component 或 @Configuration 注解将该类注册为 Spring Bean。
配置优先级： 确保自定义 Banner 的配置优先级高于默认配置。

示例代码：

import org.springframework.boot.Banner;
import org.springframework.core.env.Environment;
import org.springframework.stereotype.Component;
import java.io.PrintStream;

@Component
public class MyBanner implements Banner {

    @Override
    public void printBanner(Environment environment, Class<?> sourceClass, PrintStream out) {
        out.println("****************************************");
        out.println("*          My Custom Banner              *");
        out.println("****************************************");
    }
}

如果使用了 @Configuration 类来定义 Banner Bean，请确保该配置类被 Spring Boot 正确扫描到。可以在启动类上添加 @ComponentScan 注解，指定要扫描的包。

import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.ComponentScan;

@SpringBootApplication
@ComponentScan("com.example") // 替换为你的包名
public class MyApplication {

    public static void main(String[] args) {
        SpringApplication.run(MyApplication.class, args);
    }
}

8. Banner 完全不显示的解决方案

如果 Banner 完全不显示，可能是由于以下原因：

spring.main.banner-mode 设置为 off： 检查 application.properties 或 application.yml 文件，确保 spring.main.banner-mode 属性没有被设置为 off。
日志级别设置过高： 如果日志级别设置为 ERROR 或 FATAL，可能会导致 Banner 信息被忽略。
使用了非控制台环境： 在某些非控制台环境中（例如，在 Web 服务器中运行），Banner 可能不会显示。
自定义 ApplicationContextInitializer 干扰： 如果使用了自定义的 ApplicationContextInitializer，并且在初始化过程中禁用了 Banner 输出，则会导致 Banner 不显示。

9. 使用 SpringApplicationBuilder 自定义 Banner

可以使用 SpringApplicationBuilder 在代码中更灵活地自定义 Banner。

import org.springframework.boot.builder.SpringApplicationBuilder;
import org.springframework.boot.Banner;
import org.springframework.core.env.Environment;

import java.io.PrintStream;

public class CustomBannerApplication {

    public static void main(String[] args) {
        new SpringApplicationBuilder()
                .sources(CustomBannerApplication.class)
                .banner(new Banner() {
                    @Override
                    public void printBanner(Environment environment, Class<?> sourceClass, PrintStream out) {
                        out.println("****************************************");
                        out.println("*          Custom Banner with Builder   *");
                        out.println("****************************************");
                    }
                })
                .run(args);
    }
}

10. 不同环境下的 Banner 配置

在不同的环境下，可能需要使用不同的 Banner。可以使用 Spring Boot 的 Profile 功能来实现。

创建不同的 application-{profile}.properties 或 application-{profile}.yml 文件，例如 application-dev.properties 和 application-prod.properties。
在不同的文件中配置不同的 spring.config.location 属性，指向不同的 banner.txt 文件。
使用 -Dspring.profiles.active={profile} 参数启动应用程序，指定要使用的 Profile。

示例：

application-dev.properties：

spring.config.location=classpath:banner-dev.txt

application-prod.properties：

spring.config.location=classpath:banner-prod.txt

启动命令：

java -Dspring.profiles.active=dev -jar myapp.jar

或者

java -Dspring.profiles.active=prod -jar myapp.jar

使用表格总结各种配置方式的优先级和适用场景：

配置方式	优先级	适用场景
命令行参数	最高	临时修改配置，不建议长期使用
JVM 系统属性	较高	与命令行参数类似，不建议长期使用
操作系统环境变量	较高	适用于配置一些全局性的环境变量
Profile-specific properties 文件	中等	适用于不同环境下使用不同的配置，例如开发环境、测试环境和生产环境
application properties 文件	中等	适用于配置一些通用的配置
`@PropertySource` 注解配置的 properties 文件	较低	适用于配置一些特定的配置，例如第三方库的配置
默认属性	最低	适用于配置一些默认的配置
`banner.txt` 文件	中等偏下	常用的 Banner 自定义方式，简单易用
编程方式	中等	适用于需要动态生成 Banner 的场景，或者需要访问 Spring 上下文的场景

11. 常见错误配置示例

以下列举一些常见的错误配置，以及如何避免这些错误：

错误示例 1：banner.txt 文件不在 classpath 根目录下。

src/main/java/com/example/myapp/banner.txt  // 错误
src/main/resources/banner.txt            // 正确

错误示例 2：spring.main.banner-mode 设置为 off。
```
spring.main.banner-mode=off  // 错误
```
错误示例 3：多模块项目中，banner.txt 文件放在了非启动模块下。

确保 banner.txt 位于启动模块的 src/main/resources 目录下。
错误示例 4：忘记了清理项目和重新构建。

在修改 banner.txt 文件后，务必清理项目并重新构建，以确保新的 Banner 生效。
错误示例 5：使用了错误的编码格式保存了banner.txt文件
确保banner.txt文件使用UTF-8编码格式保存。

一些经验总结

解决 Spring Boot Banner 自定义失效问题，需要理解 Spring Boot 的配置加载顺序和优先级规则，仔细检查 banner.txt 文件的位置和编码，并确保没有其他配置干扰 Banner 的显示。通过以上步骤，相信大家能够成功自定义 Spring Boot 的 Banner，让应用程序启动时更加个性化。

Spring Boot Banner 自定义失效问题深度解析：配置加载顺序与优先级

发表回复 取消回复

发表回复取消回复