Spring Boot Banner

本文源码仓库地址：Gitee

一、前言

在日常开发中，我们经常会看到各种各样的启动画面。例如以下几种：

1. Spring Boot项目启动
   
2. MyBatis-Plus启动
   
3. RuoYi项目启动
   
   这些好看的启动画面叫什么？又是如何制作的呢？请往下看。

二、SpringBoot Banner

（一）概述

Banner，即横幅，是在SpringBoot应用启动时显示的一段文字、图像或其他形式的展示内容。默认情况下，SpringBoot在启动时会显示一个包含Spring标志的ASCII图案，配以版本信息。这不仅为开发者提供了应用启动的视觉反馈，也为项目增添了一份独特的标识。
Banner 是 Spring Boot 提供的一个小但有趣的功能，可以让应用程序启动时更具个性也显得更高级。

（二）作用

在启动项目时打印logo，并提示项目已经启动完成、项目环境、使用框架等信息。

（三）优点

• 品牌标识：通过在启动时显示自定义 ASCII 艺术和信息，你可以为你的项目增加独特的标识，提高用户体验。
• 欢迎信息：Banner 可以包含欢迎信息，用于向用户或团队成员传达有关应用程序的信息。
• 版本号和作者信息：你可以在 Banner 中包含应用程序的版本号和作者信息，以便更容易地识别应用程序的版本和负责人。

（三）适用场景

• 项目品牌标识：当你希望为项目增加独特的标识并提供友好的欢迎信息时，可以使用自定义 Banner。
• 版本管理：在多个环境中部署应用程序时，通过在 Banner 中包含版本号，可以轻松区分不同的版本。
• 项目团队：如果你想在 Banner 中显示项目的作者信息或开发团队信息，可以使用自定义 Banner。

（四）实现原理

SpringBoot的Banner是通过org.springframework.boot.Banner接口来实现的。SpringBoot在启动过程中，会查找可用的Banner资源，并按照一定的优先级进行加载：

1. 自定义Banner实现：开发者可以通过实现Banner接口，提供自定义的Banner逻辑。
2. Banner文本文件：SpringBoot会查找项目中的banner.txt文件，作为启动时的Banner展示内容。
3. 默认Banner：如果以上两种方式均未提供Banner，SpringBoot将使用内置的默认Banner。

在加载Banner的过程中，SpringBoot会优先级排序，确保开发者的自定义Banner能够覆盖默认设置。

（五）在线生成工具

复杂的banner需要借助一些在线工具来辅助生成，下面是一些常用的网站（排名不分先后）：

1. Text to ASCII Art Generator: Create ASCII Art from Text
   
2. 英文ASCII艺术字，Spring Boot自定义启动Banner在线生成工具
3. ASCll Generator
4. IMG2TXT: ASCII Art Made Easy!（支持根据在线图片来转换和生成彩色的）
   
5. 图片转字符画（也支持根据上传图片生成）
6. Online Spring Boot Banner Generator (with FIGlet Fonts)

三、自定义Banner

（一）自定义Banner类型

SpringBoot提供了几种内置的Banner类型，以满足不同的定制需求：

1. 文本文件Banner

通过在项目资源目录下添加banner.txt文件，可以定义纯文本或ASCII图案的Banner。

1. 创建banner.txt文件：通常是在类路径的根目录下（即：src/main/resources目录）下创建一个名为banner.txt的文件。

   • 默认banner文件：banner.txt/banner.gif/banner.jpg/banner.png
   • banner文件的文件名称默认为“banner.txt”，这是在源码SpringApplication.java中定义的
     
   • 可以在application.yml或application.properties配置文件中配置banner文件的位置和文件名称（若banner文件不在类路径的根目录下或者文件名不是banner则需要配置此项）

2. 编写Banner内容：在banner.txt中添加你想要展示的文本或ASCII图案。（可以使用在线工具来生成 ASCII 艺术，确保文件内容符合你的项目需求）

   我的SpringBoot应用 *
   Version 1.0.0 *
   

3. 启动应用：运行SpringBoot应用时，新的Banner将取代默认Banner进行显示。
   

2. 代码Banner

若需要更复杂的Banner，如动态内容或图形化展示，可以通过实现Banner接口进行自定义。通过实现Banner接口，可以完全自定义Banner的生成逻辑，包括动态内容的展示。

// *********************** 创建自定义Banner类 ***********************
import org.springframework.boot.Banner;
import org.springframework.core.env.Environment;
import java.io.PrintStream;/*** 通过代码自定义Banner*/
public class CustomBanner implements Banner {@Overridepublic void printBanner(Environment environment, Class<?> sourceClass, PrintStream out) {out.println("*************************************");out.println("*      欢迎使用我的SpringBoot应用     *");out.println("*           Version " + environment.getProperty("application.version") + "          *");out.println("*************************************");}
}// *********************** 在主启动类中设置 ***********************
import com.custom.banner.demos.CustomBanner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;/*** 主启动类*/
@SpringBootApplication
public class CustomBannerApplication {public static void main(String[] args) {SpringApplication app = new SpringApplication(CustomBannerApplication.class);app.setBanner(new CustomBanner());app.run(args);}
}

3. 图片Banner

支持使用图片作为Banner，需要借助第三方库将图片转换为ASCII字符。

（二）自定义Banner颜色

1. 使用枚举类

Banner默认是黑白的启动界面，但SpringBoot提供了枚举类来控制Banner的颜色显示：

• AnsiColor：设置字符的前景色
• AnsiBackground：设置字符的背景色
• AnsiStyle：设置加粗、斜体、下划线等

只需要在banner文件的第一行添加${枚举类.颜色}即可将Banner输出为指定颜色。比如：${AnsiColor.BRIGHT_YELLOW}可以将Banner变成金黄色。

如果添加了${AnsiColor.BRIGHT_YELLOW}但是并没有改变颜色，那可能是由于版本原因导致，可以在配置文件中添加配置以支持Banner改变颜色

# application.yml
spring:output:ansi:enabled: always

2. 使用 jansi 库

<!-- 支持ANSI颜色码 -->
<dependency><groupId>org.fusesource.jansi</groupId><artifactId>jansi</artifactId><version>1.18</version>
</dependency>

// *********************** 创建彩色Banner类 ***********************
import org.fusesource.jansi.Ansi;
import org.springframework.boot.Banner;
import org.springframework.core.env.Environment;import java.io.PrintStream;/*** 彩色Banner类*/
public class ColorfulBanner implements Banner {@Overridepublic void printBanner(Environment environment, Class<?> sourceClass, PrintStream out) {String banner = Ansi.ansi().fg(Ansi.Color.CYAN).a("*************************************\n").fg(Ansi.Color.GREEN).a("*      欢迎使用彩色SpringBoot应用      *\n").fg(Ansi.Color.YELLOW).a("*           Version 1.0.0           *\n").fg(Ansi.Color.CYAN).a("*************************************").reset().toString();out.println(banner);}
}// *********************** 在主启动类中设置 ***********************
import com.custom.banner.demos.ColorfulBanner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;/*** 主启动类*/
@SpringBootApplication
public class CustomBannerApplication {public static void main(String[] args) {SpringApplication app = new SpringApplication(CustomBannerApplication.class);// 彩色Bannerapp.setBanner(new ColorfulBanner());app.run(args);}
}

（三）Banner其他设置

除了基本设置外，还可以在banner.txt文件中加入一些其他的属性：

• ${application.version}：获取MANIDEST.MF文件中版本号
• ${application.formatted-version}：格式化后的{application.version}版本信息
• ${spring-boot.version}：SpringBoot的版本号
• ${spring-boot.formatted-version}：格式化后的{spring-boot.version}版本信息

（四）禁用Banner

如果不喜欢banner这种信息，想要关闭它，可以通过修改入口类的main方法或者配置文件来实现

1. 代码实现

/*** 主启动类*/
@SpringBootApplication
public class CustomBannerDemoApplication {public static void main(String[] args) {SpringApplication app = new SpringApplication(CustomBannerDemoApplication.class);/*关闭 Banner 模式，默认CONSOLE。支持：- OFF：关闭打印banner- CONSOLE：打印到System.out- LOG：打印到log文件*/app.setBannerMode(Banner.Mode.OFF);app.run(args);}
}

2. 配置实现

# application.yml
spring:main:banner-mode: off

（五）配置属性支持

spring:main:#设置显示banner模式，默认CONSOLE。支持 OFF：关闭打印banner、CONSOLE：打印到System.out、LOG：打印到log文件banner-mode: consolebanner:# 设置banner的字符编码，默认utf-8charset: UTF-8# 设置banner文本资源的位置，默认classpath:banner.txt。支持 classpath*:、classpath:、file:、http://和https://location: classpath:banner.txt# 设置banner图片的位置，默认classpath:banner.gif（jpg和png也适用）
#    location: classpath:banner.jpgimage:# 设置ANSI颜色的位深度，默认4。支持 4：16色、8：256色bitdepth: 4# 设置banner图像的高度(单位字符)，默认图像高度height: 20# 设置banner图像的宽度，默认76width: 100# 是否为暗色系背景图片反转颜色，默认falseinvert: false# 设置banner图片左边空白间隔，默认2margin: 10# 设置渲染图像时使用的像素模式，支持 TEXT：使用文本字符、BLOCK：使用unicode块字符pixelmode: TEXT

三、高级进阶

在某些场景下，Banner内容需要根据不同的环境或配置进行动态调整。

（一）基于环境变量动态展示Banner

在自定义Banner类中，根据Environment对象获取不同的环境变量，调整Banner内容。

// *********************** 创建基于环境变量的Banner类 ***********************
import org.fusesource.jansi.Ansi;
import org.springframework.boot.Banner;
import org.springframework.core.env.Environment;import java.io.PrintStream;/*** 基于环境变量动态展示Banner*/
public class DynamicBanner implements Banner {@Overridepublic void printBanner(Environment environment, Class<?> sourceClass, PrintStream out) {String profile = environment.getActiveProfiles().length > 0 ? environment.getActiveProfiles()[0] : "default";String version = environment.getProperty("application.version", "1.0.0");String banner = Ansi.ansi().fg(Ansi.Color.CYAN).a("*******************************\n").fg(Ansi.Color.GREEN).a("*    SpringBoot " + profile.toUpperCase() + " 环境    *\n").fg(Ansi.Color.YELLOW).a("*      Version " + version + "       *\n").fg(Ansi.Color.CYAN).a("*******************************").reset().toString();out.println(banner);}
}// *********************** 在主启动类中设置 ***********************
import com.custom.banner.demos.DynamicBanner;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;/*** 主启动类*/
@SpringBootApplication
public class CustomBannerApplication {public static void main(String[] args) {SpringApplication app = new SpringApplication(CustomBannerApplication.class);// 基于环境变量动态展示Bannerapp.setBanner(new DynamicBanner());app.run(args);}
}

• 配置不同环境的Banner展示：根据不同的Spring profile，Banner会自动调整显示内容。例如，在开发环境中显示“DEV”，在生产环境中显示“PROD”。
• 启动应用并切换环境：通过--spring.profiles.active=prod参数启动应用，可以看到不同环境下的Banner内容变化。

（二）使用 SpEL 表达式

如果想在Banner中动态表示比如应用名称、版本号等这类信息，可以使用Spring Expression Language (SpEL) 表达式。在banner.txt文件中使用${application.name}这样的占位符，然后在application.properties或application.yml中定义这些属性。
例如：在application.yml中添加：

application: name: My Awesome Appversion: @project.version@

然后在banner.txt中使用这些值

  _______                    __  _/ ____(_)____ ___  ___  ___/ /_(_)___  ____  _____
/ /_  / / ___/ _ \/ _ \/ _  / __/ / _ \/ __ \/ ___/
/ __/ / /__/  __/  __/ /_/ / /_/ /  __/ / / / /
/_/   \___/\___/\___/\__,_/\__/_/\___/_/ /_/_/
Version: ${application.version}

（三）使用条件化的 Banner

根据不同的环境或条件显示不同的 Banner。Spring Boot 允许使用条件化的 Banner。要实现这一点，你可以创建多个 Banner 文件，并使用条件来选择要显示的 Banner。例如，你可以创建banner-prod.txt和banner-dev.txt文件，然后在配置文件中指定要使用的 Banner 文件：

spring: profiles: active: prodbanner: location: classpath:banner-prod.txt

当激活的 Spring Profile 为 “prod” 时，将显示banner-prod.txt文件中的 Banner。

四、常见问题与解决方案

（一）Banner文件不生效

• 确认banner.txt文件位于src/main/resources目录下。
• 检查文件编码，确保为UTF-8格式。
• 确认spring.banner.enabled属性未在配置文件中被禁用。

（二）自定义Banner中的颜色不显示

• 确保终端支持ANSI颜色码。
• 引入jansi库并正确配置自定义Banner类。
• 检查代码逻辑，确保颜色码正确嵌入。

（三）如何在Banner中显示动态信息，如版本号

• 在自定义Banner类中，通过Environment对象获取所需的动态信息。
• 确保相关配置项（如application.version）在application.properties或其他配置文件中正确设置。

五、总结

通过本文的详细解析，相信你已经掌握了SpringBoot中Banner打印的实现原理及多种自定义方法。从简单的文本Banner到复杂的彩色和动态Banner，SpringBoot提供了灵活的方式让开发者根据需求自由发挥。自定义Banner不仅能提升应用的专业形象，还能增强开发者的使用体验。