ServerOptions 配置

在快速开始中，我们用默认配置启动了服务。但在实际开发中，你需要根据场景调整端口、线程数、缓冲区大小等参数。本章介绍 Feat 提供的所有配置选项。

两种配置方式

Feat 提供两种配置 ServerOptions 的方式：

OptionsDemo.java

import tech.smartboot.feat.Feat;
import tech.smartboot.feat.core.server.ServerOptions;

public class OptionsDemo {
    public static void main(String[] args) {
        // 方式 1：Lambda 配置（推荐）
        Feat.httpServer(options -> {
            options.port(9090);
            options.threadNum(8);
            options.debug(true);
        }).listen();

        // 方式 2：直接创建配置对象
        ServerOptions options = new ServerOptions();
        options.port(9090);
        options.threadNum(8);
        Feat.httpServer(options).listen();
    }
}

两种方式完全等价，Lambda 方式更简洁，是推荐的写法。

基础配置

端口与主机

PortHostDemo.java

import tech.smartboot.feat.Feat;

public class PortHostDemo {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            // 监听端口，默认 8080
            options.port(9090);
            // 监听地址，默认 "0.0.0.0"（所有网卡）
            options.host("127.0.0.1");
        }).httpHandler(req -> {
            req.getResponse().write("Server running on 127.0.0.1:9090");
        }).listen();
    }
}

验证：

curl http://127.0.0.1:9090

Tip

host("127.0.0.1") 表示只接受本机连接，适合开发环境。生产环境通常保持默认 "0.0.0.0"。

性能配置

线程数

ThreadConfigDemo.java

import tech.smartboot.feat.Feat;

public class ThreadConfigDemo {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            // 设置服务线程数为 8
            // 默认值为 CPU 核心数（至少为 2）
            options.threadNum(8);
        }).httpHandler(req -> {
            req.getResponse().write("Thread config demo");
        }).listen();
    }
}

线程数的选择建议：

应用类型	建议线程数	说明
IO 密集型	CPU 核数 × 2-4	等待网络/数据库时线程可切换处理其他请求
CPU 密集型	CPU 核数 × 1-2	避免过多线程导致上下文切换开销
混合场景	从默认值开始压测调整	根据实际负载测试确定最佳值

缓冲区大小

BufferConfigDemo.java

import tech.smartboot.feat.Feat;

public class BufferConfigDemo {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            // 读缓冲区大小，默认 8KB
            options.readBufferSize(16 * 1024);
            // 写缓冲区大小，默认 8KB
            options.writeBufferSize(16 * 1024);
        }).httpHandler(req -> {
            req.getResponse().write("Buffer config demo");
        }).listen();
    }
}

Caution

读缓冲区大小至少要能容纳一个完整的 URL 或 Header 值，否则将触发异常。处理大请求体（如文件上传）时需要适当增大。

安全与限制配置

请求大小限制

RequestLimitDemo.java

import tech.smartboot.feat.Feat;

public class RequestLimitDemo {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            // 最大请求报文大小，默认 Integer.MAX_VALUE
            // 这里限制为 10MB
            options.setMaxRequestSize(10 * 1024 * 1024);

            // HTTP 请求头数量上限，默认 100
            options.headerLimiter(50);
        }).httpHandler(req -> {
            req.getResponse().write("Request limit demo");
        }).listen();
    }
}

连接超时

TimeoutDemo.java

import tech.smartboot.feat.Feat;

public class TimeoutDemo {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            // 连接闲置超时时间（毫秒），默认 60000（1分钟）
            options.setIdleTimeout(30000); // 30秒
        }).httpHandler(req -> {
            req.getResponse().write("Timeout demo");
        }).listen();
    }
}

调试配置

启用调试模式

DebugDemo.java

import tech.smartboot.feat.Feat;

public class DebugDemo {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            // 启用调试模式，控制台会打印请求和响应详情
            options.debug(true);
        }).httpHandler(req -> {
            req.getResponse().write("Debug mode enabled");
        }).listen();
    }
}

启动后，控制台会输出类似：

[DEBUG] Request: GET / HTTP/1.1
[DEBUG] Headers: {Host=localhost:8080, User-Agent=curl/7.64.1}
[DEBUG] Response: HTTP/1.1 200 OK

Caution

生产环境务必关闭调试模式，避免性能下降和敏感信息泄露。

高级配置

代理协议支持

当服务器部署在 Nginx、HAProxy 等代理后面时，启用此选项可以获取客户端真实 IP：

ProxyProtocolDemo.java

import tech.smartboot.feat.Feat;

public class ProxyProtocolDemo {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            // 启用代理协议支持
            options.proxyProtocolSupport();
        }).httpHandler(req -> {
            // 可以通过 req.getRemoteAddr() 获取真实客户端 IP
            req.getResponse().write("Real client IP: " + req.getRemoteAddr());
        }).listen();
    }
}

低内存模式

在资源受限环境（如嵌入式设备）中启用：

LowMemoryDemo.java

import tech.smartboot.feat.Feat;

public class LowMemoryDemo {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            // 启用低内存模式
            options.setLowMemory(true);
        }).httpHandler(req -> {
            req.getResponse().write("Low memory mode");
        }).listen();
    }
}

关闭钩子

ShutdownHookDemo.java

import tech.smartboot.feat.Feat;

public class ShutdownHookDemo {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            // 设置服务器关闭钩子
            options.shutdownHook(() -> {
                System.out.println("Server is shutting down...");
                // 执行资源清理、状态保存等操作
            });
        }).httpHandler(req -> {
            req.getResponse().write("Shutdown hook demo");
        }).listen();
    }
}

配置参数速查表

配置项	方法	默认值	说明
端口	port(int)	8080	服务监听端口
主机	host(String)	”0.0.0.0”	服务监听地址
线程数	threadNum(int)	CPU 核心数	IO 处理线程数
读缓冲区	readBufferSize(int)	8192 (8KB)	请求数据缓冲区
写缓冲区	writeBufferSize(int)	8192 (8KB)	响应数据缓冲区
最大请求大小	setMaxRequestSize(long)	Integer.MAX_VALUE	请求体大小限制
Header 数量限制	headerLimiter(int)	100	请求头数量上限
连接超时	setIdleTimeout(long)	60000ms	连接闲置超时
调试模式	debug(boolean)	false	打印请求响应详情
低内存模式	setLowMemory(boolean)	false	减少内存占用
代理协议	proxyProtocolSupport()	-	获取真实客户端 IP

场景化配置建议

开发环境

Feat.httpServer(options -> {
    options.port(8080);
    options.debug(true);  // 开启调试便于排查问题
})

生产环境（通用）

Feat.httpServer(options -> {
    options.port(80);
    options.threadNum(Runtime.getRuntime().availableProcessors() * 2);
    options.setMaxRequestSize(10 * 1024 * 1024);  // 10MB 请求限制
    options.headerLimiter(100);
    // debug 保持默认 false
})

高并发场景

Feat.httpServer(options -> {
    options.port(8080);
    options.threadNum(32);  // 根据压测结果调整
    options.readBufferSize(32 * 1024);   // 增大缓冲区
    options.writeBufferSize(32 * 1024);
    options.setIdleTimeout(60000);  // 保持长连接
})

嵌入式/IoT 设备

Feat.httpServer(options -> {
    options.port(8080);
    options.threadNum(2);  // 减少线程数
    options.setLowMemory(true);  // 启用低内存模式
    options.readBufferSize(2048);   // 减小缓冲区
    options.writeBufferSize(2048);
})

常见问题

端口被占用

Exception in thread "main" java.net.BindException: Address already in use

解决方案：更换端口或查找占用进程：

# 查找占用 8080 端口的进程
lsof -i :8080
# 或更换端口
Feat.httpServer(options -> options.port(9090)).listen();

请求体过大被截断

增大 setMaxRequestSize 的值，特别是处理文件上传时：

options.setMaxRequestSize(100 * 1024 * 1024);  // 100MB

Header 数量超限

如果收到 400 Bad Request，可能是 Header 数量超过限制：

options.headerLimiter(200);  // 增大限制

调试模式没有输出

确保在 httpHandler 之前配置 debug(true)：

Feat.httpServer(options -> options.debug(true))  // 先配置
    .httpHandler(...)                           // 再设置处理器
    .listen();