Netty 配置

infra-web-netty-server 模块提供了基于 Netty 的嵌入式 Web 服务器实现。 它可以通过 infra-starter-netty-server 启动器自动配置，也可以通过直接使用 NettyWebServerFactory 进行编程式配置。

依赖引入

要使用 Netty 作为嵌入式容器，您需要添加 infra-starter-netty-server 依赖：

dependencies {
  implementation 'cn.taketoday:infra-starter-netty-server'
}

配置属性

您可以通过 server.netty 前缀的配置属性来定制 Netty 服务器的行为。 以下是一些常用的配置项：

属性名 描述 默认值

server.netty.worker-threads

用于处理 I/O 操作的工作线程数 (Child EventLoopGroup)。

核心数 * 2

server.netty.acceptor-threads

用于接收连接的线程数 (Parent EventLoopGroup)。

1

server.netty.max-connection

允许的最大连接数 (SOMAXCONN)。

系统默认值 (Windows: 200, 其他: 128)

server.netty.max-content-length

请求体的最大长度。超过此限制将返回错误。

100MB

server.netty.max-chunk-size

最大分块大小。

8KB

server.netty.initial-buffer-size

HTTP 请求解码的初始缓冲区大小。

128B

server.netty.max-header-size

HTTP 头的最大大小。

8KB

server.netty.max-initial-line-length

HTTP 请求行（第一行）的最大长度。

4096

server.netty.validate-headers

是否启用头验证，以防止请求/响应拆分攻击。

true

server.netty.connection-timeout

连接超时时间。

无

server.netty.leak-detection

资源泄漏检测级别 (DISABLED, SIMPLE, ADVANCED, PARANOID)。

DISABLED

server.netty.writer-auto-flush

是否在每次写入操作后自动刷新 PrintWriter。

false

server.netty.data-received-queue-capacity

用于存储接收数据块的队列容量。

256

server.netty.auto-read

是否自动从通道读取数据。

true

server.netty.auto-ack-ping-frame

是否自动确认 PING 帧。

true

server.netty.auto-ack-settings-frame

是否自动确认 SETTINGS 帧。

true

server.netty.http2-graceful-shutdown-timeout

HTTP/2 连接的优雅关闭超时时间。

30s

server.netty.chunked-supported

是否支持 Transfer-Encoding: Chunked。

true

server.netty.allow-partial-chunks

是否允许分块被拆分为多个消息。

true

server.netty.allow-duplicate-content-lengths

是否允许超过一个 Content-Length 头。

false

此外，还有一些通用的服务器配置属性，位于 server 前缀下：

属性名 描述 默认值

server.port

服务器 HTTP 端口。

8080

server.address

服务器绑定的网络地址。

0.0.0.0 (所有接口)

server.use-virtual-thread-service-executor

是否使用虚拟线程作为服务执行器 (Java 21+)。

false

server.forward-headers-strategy

处理 X-Forwarded-* 头的策略 (NATIVE, FRAMEWORK, NONE)。

无 (暂未实现)

server.shutdown

服务器支持的关闭类型 (IMMEDIATE, GRACEFUL)。

GRACEFUL

线程池配置

您可以自定义工作线程和接收线程的名称：

server:
  netty:
    worker-pool-name: "infra-netty-worker"
    acceptor-pool-name: "infra-netty-acceptor"

优雅停机

Netty 服务器支持优雅停机，可以通过 server.netty.shutdown 配置相关参数。 优雅停机可确保在关闭服务器之前，不会提交新任务，但会允许正在进行的任务在“静默期”内完成。

属性名 描述 默认值

server.netty.shutdown.quiet-period

静默期（秒），在此期间如果没有新任务提交，则关闭。如果在此期间有任务提交，则静默期重新开始。

1s

server.netty.shutdown.timeout

最大等待时间（秒），无论是否有任务提交，超过此时间强制关闭。

10s

server.netty.shutdown.unit

quiet-period 和 timeout 的时间单位。

SECONDS

 
server:
  netty:
    shutdown:
      quiet-period: 2 # 静默期（秒）
      timeout: 15     # 最大等待时间（秒）
      unit: SECONDS   # 时间单位

HTTP/2 配置

可以通过 server.http2 前缀配置 HTTP/2：

server:
  http2:
    enabled: true # 启用 HTTP/2

SSL 配置

可以通过 server.ssl 前缀配置 SSL：

server:
  ssl:
    enabled: true
    key-store: classpath:keystore.p12
    key-store-password: changeit
    key-store-type: PKCS12
    key-alias: tomcat

压缩配置（暂未实现）

可以通过 server.compression 前缀配置响应压缩：

server:
  compression:
    enabled: true
    mime-types: text/html,text/xml,text/plain,text/css,text/javascript,application/javascript,application/json,application/xml
    min-response-size: 2048

Multipart 配置

可以通过 server.multipart 前缀配置 Multipart 请求处理：

server:
  multipart:
    max-fields: 128
    max-header-size: 512B
    field-size-threshold: 16KB
    parsing-buffer-size: 4KB
    default-charset: UTF-8
    temp-base-dir: /tmp/uploads

编程式配置

如果您需要更细粒度的控制，可以注册一个 WebServerFactoryCustomizer bean 来定制 NettyWebServerFactory：

@Bean
public WebServerFactoryCustomizer<NettyWebServerFactory> nettyCustomizer() {
  return factory -> {
    factory.setPort(8088);
    factory.setWorkerThreadCount(10);
  };
}

@Bean
public ServerBootstrapCustomizer serverBootstrapCustomizer(){
  return bootstrap -> {
    bootstrap.option(ChannelOption.AUTO_READ, false);
  };
}

请求配置定制

您还可以通过 NettyRequestConfigCustomizer 定制请求配置：

@Bean
public NettyRequestConfigCustomizer requestConfigCustomizer() {
  return builder -> {
    builder.maxContentLength(DataSize.ofMegabytes(50).toBytes())
            .writerAutoFlush(false);
  };
}