Spring Boot 应用配置指南

1. 概述

Spring Boot 功能强大，开箱即用。本文聚焦几个实用且高频使用的配置项，帮你快速掌握核心配置技巧。这些内容在实际项目中经常踩坑，掌握后能省下不少调试时间。

2. 修改服务端口

Spring Boot 默认使用 8080 作为内嵌服务器端口。如果端口冲突或需要自定义，可以通过配置快速修改。

✅ 方式一：properties 配置

server.port=8083

✅ 方式二：YAML 配置（推荐）

server:
  port: 8083

✅ 方式三：编程式配置

适用于动态端口或复杂逻辑场景：

@Component
public class CustomizationBean implements WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> {
 
    @Override
    public void customize(ConfigurableServletWebServerFactory container) {
        container.setPort(8083);
    }
}

⚠️ 注意：WebServerFactoryCustomizer 是通用扩展点，后续多个配置都会用到它。

3. 设置应用上下文路径（Context Path）

默认情况下，应用根路径是 /。但生产环境通常需要加上 context path，比如 /api 或 /app。

✅ properties 配置

server.servlet.contextPath=/springbootapp

✅ YAML 配置

server:
  servlet:
    contextPath: /springbootapp

✅ 编程式设置

@Component
public class CustomizationBean implements WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> {
 
    @Override
    public void customize(ConfigurableServletWebServerFactory container) {
        container.setContextPath("/springbootapp");
    }
}

✅ 效果：原本访问 http://localhost:8080/hello 的接口，现在需访问 http://localhost:8080/springbootapp/hello

4. 自定义错误页面（替换白标签页）

Spring Boot 默认提供一个“白标签错误页”（Whitelabel Error Page），适合开发阶段。但生产环境必须替换为友好提示。

默认情况下，Spring Boot 会自动注册 BasicErrorController。我们可以通过实现 ErrorController 接口来自定义逻辑。

@RestController
public class MyCustomErrorController implements ErrorController {
 
    private static final String PATH = "/error";
    
    @GetMapping(value = PATH)
    public String error() {
        return "Error haven";
    }

    @Override
    public String getErrorPath() {
        return PATH;
    }
}

❌ 注意：Spring Boot 2.3+ 已废弃 ErrorController 接口，推荐使用 @ControllerAdvice 或错误页面机制（见下节）。

5. 精细化错误处理配置

除了替换默认错误页，还可以按 HTTP 状态码注册不同的错误页面，实现更细粒度控制。

✅ 使用 WebServerFactoryCustomizer 注册错误页：

@Component
public class CustomizationBean implements WebServerFactoryCustomizer<ConfigurableServletWebServerFactory> {
 
    @Override
    public void customize(ConfigurableServletWebServerFactory container) {        
        container.addErrorPages(new ErrorPage(HttpStatus.BAD_REQUEST, "/400"));
        container.addErrorPages(new ErrorPage("/errorHaven"));
    }
}

上述配置表示：

所有 400 错误跳转到 /400
其他错误统一跳转到 /errorHaven

✅ 实现目标接口：

@GetMapping("/errorHaven")
public String errorHeaven() {
    return "You have reached the haven of errors!!!";
}

输出结果：

You have reached the haven of errors!!!

✅ 提示：更现代的做法是使用 src/main/resources/templates/error/400.html 这类模板文件，由 ErrorMvcAutoConfiguration 自动处理。

6. 编程式关闭应用

有时候需要在特定条件下优雅关闭 Spring Boot 应用，比如健康检查失败、接收到特殊信号等。

✅ 使用 SpringApplication.exit() 方法：

@Autowired
private ApplicationContext applicationContext;

public void shutDown(ExitCodeGenerator exitCodeGenerator) {
    SpringApplication.exit(applicationContext, exitCodeGenerator);
}

✅ 示例：返回特定退出码

@Bean
public ExitCodeGenerator exitCodeGenerator() {
    return () -> 42;
}

✅ 调用 SpringApplication.exit() 会触发 Spring 的关闭钩子（shutdown hooks），释放资源，比 System.exit() 更优雅。

7. 配置日志级别

日志是排查问题的第一道防线。Spring Boot 支持在配置文件中直接调整包级别的日志级别。

✅ properties 配置示例：

logging.level.org.springframework.web=DEBUG
logging.level.org.hibernate=ERROR
logging.level.com.yourcompany=INFO

✅ 支持的日志系统：

Logback（默认）
Log4j2
JUL（Java Util Logging）

只需引入对应依赖并提供配置文件（如 logback-spring.xml），Spring Boot 会自动切换。

✅ 推荐使用 logback-spring.xml 而非 logback.xml，可利用 Spring Profile 动态切换日志配置。

8. 注册自定义 Servlet

虽然现在主流是使用 Spring MVC 的 @Controller，但在集成老系统或特殊场景下，仍可能需要注册原生 Servlet。

✅ 方式一：直接注册 Servlet 类为 Bean

@Bean
public HelloWorldServlet helloWorld() {
    return new HelloWorldServlet();
}

⚠️ 注意：这种方式无法设置 URL 映射和初始化参数。

✅ 方式二：使用 ServletRegistrationBean（推荐）

@Bean
public ServletRegistrationBean<SpringHelloWorldServlet> servletRegistrationBean() {
    ServletRegistrationBean<SpringHelloWorldServlet> bean = 
        new ServletRegistrationBean<>(
            new SpringHelloWorldServlet(), 
            "/springHelloWorld/*"
        );
    bean.setLoadOnStartup(1);
    bean.addInitParameter("message", "SpringHelloWorldServlet special message");
    return bean;
}

✅ 优势：完全控制 Servlet 的注册行为，包括路径、启动顺序、初始化参数等。

9. 切换内嵌服务器：Jetty 或 Undertow

Spring Boot 默认使用 Tomcat 作为内嵌服务器。但在高并发或低内存场景下，Jetty 或 Undertow 可能更合适。

✅ 配置 Jetty

Maven 依赖调整：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-jetty</artifactId>
</dependency>

自定义 Jetty 配置：

@Bean
public JettyEmbeddedServletContainerFactory jettyEmbeddedServletContainerFactory() {
    JettyEmbeddedServletContainerFactory jettyContainer = 
        new JettyEmbeddedServletContainerFactory();
    
    jettyContainer.setPort(9000);
    jettyContainer.setContextPath("/springbootapp");
    return jettyContainer;
}

✅ 配置 Undertow

Maven 依赖：

<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-web</artifactId>
    <exclusions>
        <exclusion>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-starter-tomcat</artifactId>
        </exclusion>
    </exclusions>
</dependency>
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-undertow</artifactId>
</dependency>

自定义 Undertow 配置：

@Bean
public UndertowEmbeddedServletContainerFactory embeddedServletContainerFactory() {
    UndertowEmbeddedServletContainerFactory factory = 
        new UndertowEmbeddedServletContainerFactory();
    
    factory.addBuilderCustomizers(new UndertowBuilderCustomizer() {
        @Override
        public void customize(io.undertow.Undertow.Builder builder) {
            builder.addHttpListener(8080, "0.0.0.0");
        }
    });
    
    return factory;
}

✅ 对比建议：

Tomcat：稳定通用，适合大多数场景

Jetty：轻量灵活，适合嵌入式或复杂路由

Undertow：性能强劲，适合高并发微服务

10. 总结

本文覆盖了 Spring Boot 中几个高频且关键的配置项，包括端口、上下文路径、错误处理、日志、Servlet 注册及服务器切换。这些配置看似简单，但在实际项目中经常成为“隐形坑”。

✅ 核心要点回顾：

配置优先级：命令行 > properties/yaml > 编程式
WebServerFactoryCustomizer 是底层扩展利器
生产环境务必替换白标签错误页
日志级别要合理设置，避免过度输出
内嵌服务器可根据场景灵活替换

所有示例代码已整理至 GitHub 仓库：https://github.com/techblog/spring-boot-config-demo
欢迎 star 和贡献。

Persistence

REST

Security