Что такое встроенный сервер Spring Boot и как настроить порт сервера?

Встроенный сервер в Spring Boot

Spring Boot включает Tomcat, Jetty или Undertow прямо в fat-jar. При запуске java -jar app.jar EmbeddedWebServerFactoryCustomizerAutoConfiguration создаёт и стартует встроенный контейнер — никакого внешнего сервера приложений не нужно. Это упрощает деплой в Docker: образ содержит только JRE и jar.

Настройка порта

# application.yml
server:
  port: 8080                # основной HTTP-порт приложения

management:
  server:
    port: 8081              # отдельный порт для Spring Boot Actuator
  endpoints:
    web:
      exposure:
        include: health,metrics,info

Можно передать порт через аргумент командной строки (приоритет выше, чем у файла):

java -jar app.jar --server.port=9090
# или через переменную окружения:
SERVER_PORT=9090 java -jar app.jar

Случайный порт для тестов

# application-test.yml
server:
  port: 0   # Spring выберет свободный порт автоматически

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class UserControllerTest {

    @LocalServerPort
    private int port;

    @Autowired
    private TestRestTemplate restTemplate;

    @Test
    void healthEndpointReturnsOk() {
        ResponseEntity<String> response = restTemplate
            .getForEntity("http://localhost:" + port + "/actuator/health", String.class);
        assertThat(response.getStatusCode()).isEqualTo(HttpStatus.OK);
    }
}

Программная настройка через WebServerFactoryCustomizer

@Component
public class TomcatCustomizer
        implements WebServerFactoryCustomizer<TomcatServletWebServerFactory> {

    @Override
    public void customize(TomcatServletWebServerFactory factory) {
        factory.setPort(8080);
        factory.setConnectionTimeout(Duration.ofSeconds(20));
        // добавить HTTPS-коннектор:
        factory.addAdditionalTomcatConnectors(createHttpsConnector());
    }
}

Подводные камни

• server.port=0 в application.yml (не тестовом профиле) запустит приложение на случайном порту — в production это катастрофа; убедитесь, что порт задан явно через переменную окружения или секрет.
• При наличии management.server.port Actuator поднимается на отдельном WebServer — @LocalServerPort вернёт основной порт, а не порт Actuator; для тестов Actuator используйте @Value("${local.management.port}").
• Если переменная окружения SERVER_PORT установлена в Docker Compose, она имеет приоритет над application.yml — это нужно учитывать при локальной разработке.
• SSL-сертификат через server.ssl.key-store и HTTP на том же порту несовместимы — нужен отдельный коннектор или reverse proxy (nginx).
• WebServerFactoryCustomizer вызывается до старта сервера, но после загрузки application.properties — порядок бинов важен при наличии нескольких кастомайзеров.
• В тестах с WebEnvironment.DEFINED_PORT конфликт портов между параллельными тестами приводит к BindException; предпочитайте RANDOM_PORT.

• Путать термин «embedded server port» с соседним механизмом Spring Boot.
• Не называть границу lifecycle, transaction, thread или request для «embedded server port».
• Игнорировать production-эффекты «embedded server port»: latency, SQL shape, memory, security или observability.

• Попросить объяснить механизм «embedded server port» на минимальном примере.
• Проверить, видит ли кандидат failure mode и диагностику для «embedded server port».
• Уточнить, какие настройки или API меняют «embedded server port» в реальном сервисе.