ServerOptions 配置指南

ServerOptions 是 Feat HTTP 服务的运行时配置入口。高质量的用法不是把所有选项都改一遍，而是按场景只动那些真正影响行为的项。

什么时候需要看这页

你已经能跑起 Feat Core 快速入门
现在要改端口、线程数、调试模式、上传大小或 HTTPS
你希望按部署场景建立一套可复用的配置模板

最常用的配置项

配置项	方法	默认值	什么时候改
端口	`port(int)`	`8080`	本机端口冲突、多服务并行
监听地址	`host(String)`	`0.0.0.0`	只允许本机访问、绑定特定网卡
线程数	`threadNum(int)`	`max(CPU, 2)`	压测后需要调优吞吐或资源占用
读缓冲区	`readBufferSize(int)`	`8 * 1024`	请求头大、上传大、长 URL
写缓冲区	`writeBufferSize(int)`	`8 * 1024`	响应体较大、推送较多
空闲超时	`setIdleTimeout(long)`	`60000` ms	长连接或慢客户端场景
Header 限制	`headerLimiter(int)`	`100`	防止异常请求头滥用
最大请求体	`setMaxRequestSize(long)`	`Integer.MAX_VALUE`	上传、表单、反序列化安全
调试模式	`debug(boolean)`	`false`	本地排查协议和流量问题
Banner	`bannerEnabled(boolean)`	`true`	生产环境减少无关输出
低内存模式	`setLowMemory(boolean)`	`false`	容器或资源受限环境

场景 1：本地开发

本地开发最常见的需求是避免端口冲突，同时打开调试输出。

import tech.smartboot.feat.Feat;

public class LocalDevServer {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            options.port(8081);
            options.debug(true);
            options.bannerEnabled(true);
        }).listen();
    }
}

这里最重要的三个点：

port(8081)：避免和其他本地服务抢 8080
debug(true)：把协议收发打印出来，适合排查请求问题
bannerEnabled(true)：保留启动信息，便于本地确认版本和启动状态

场景 2：生产环境的基础模板

生产环境通常要关注的是“少暴露、少噪音、行为稳定”。

import tech.smartboot.feat.Feat;

public class ProductionServer {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            options.host("0.0.0.0");
            options.port(8080);
            options.bannerEnabled(false);
            options.threadNum(Runtime.getRuntime().availableProcessors() * 2);
            options.setIdleTimeout(60000);
            options.headerLimiter(100);
        }).listen();
    }
}

这套模板的意义在于：

显式声明监听地址和端口，避免环境歧义
关闭 Banner，减少控制台噪音
保持一个保守而合理的线程数起点
对连接闲置和 Header 数量设置明确边界

场景 3：处理上传或大请求

如果你的服务要接收较大的 JSON、表单或上传内容，最关键的是请求体上限和读缓冲区。

import tech.smartboot.feat.Feat;

public class UploadServer {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            options.port(8080);
            options.readBufferSize(16 * 1024);
            options.writeBufferSize(16 * 1024);
            options.setIdleTimeout(120000);
            options.setMaxRequestSize(20L * 1024 * 1024);
        }).listen();
    }
}

这里的配置重点：

readBufferSize(...)：适合更大的请求头或更复杂的请求
writeBufferSize(...)：适合较大的响应输出
setIdleTimeout(...)：给慢上传或长处理链路更多时间
setMaxRequestSize(...)：显式限制最大请求体，避免“无限放大”

场景 4：资源受限环境

如果服务跑在小容器、边缘节点或内存非常紧张的环境，可以保守一点：

Feat.httpServer(options -> {
    options.threadNum(2);
    options.readBufferSize(4 * 1024);
    options.writeBufferSize(4 * 1024);
    options.setLowMemory(true);
}).listen();

这类配置的目标不是追求极致吞吐，而是先保证服务能稳定活下来。

场景 5：HTTPS 和代理协议

如果服务直接启用 HTTPS，或部署在支持 Proxy Protocol 的负载均衡后面，可以这样配：

import org.smartboot.socket.extension.plugins.SslPlugin;
import tech.smartboot.feat.Feat;

public class HttpsServer {
    public static void main(String[] args) {
        Feat.httpServer(options -> {
            options.addPlugin(new SslPlugin<>("keystore.jks", "password", "JKS"));
            options.proxyProtocolSupport();
            options.port(8443);
        }).listen();
    }
}

这里有两个重要事实：

添加 SslPlugin 后，服务会自动进入 HTTPS 模式
proxyProtocolSupport() 适合放在 Nginx、HAProxy 或 LB 后面时使用，用来拿到真实客户端地址

场景 6：优雅停机和高级线程控制

如果你需要在关闭时清理资源，或者自己管理异步通道组，可以继续使用这些高级项：

options.shutdownHook(() -> {
    System.out.println("server is shutting down");
    // 清理资源、关闭连接池、落盘状态
});

AsynchronousChannelGroup group = AsynchronousChannelGroup.withFixedThreadPool(
        4,
        Executors.defaultThreadFactory()
);
options.group(group);

这两项都属于“确实有需要再用”，不是 quickstart 阶段的必配项。

常见问题

我已经把服务跑起来了，为什么还要改 `host`

默认值本来就是 0.0.0.0，很多情况下不用改。只有当你要显式限制成 127.0.0.1，或者绑定特定 IP 时才需要动它。

`debug(true)` 能不能一直开着

本地调试可以，生产环境不建议。它底层会挂一个流量监控插件，输出很多协议细节，既影响性能也可能暴露敏感信息。

线程数是不是越大越好

不是。线程数过大可能带来更高的上下文切换成本。没有压测数据时，从默认值开始通常更稳。

为什么不建议一开始就大改缓冲区

缓冲区直接影响内存占用。只有当你已经遇到“大请求、慢上传、长 URL、响应很大”这类具体问题时，再有针对性地调。

下一步

Router 路由组件：当你要把单个处理器扩展成一组路由
异步处理：当请求里出现阻塞或耗时逻辑
CloudOptions 配置指南：如果你已经切到 Feat Cloud 开发模型