5分钟搭建轻量级HTTP服务器：Hutool SimpleServer实战指南

2026-02-04 04:25:07作者：温玫谨Lighthearted

你是否还在为搭建临时服务器编写繁琐的配置文件？是否需要一个无需安装、开箱即用的Java轻量级服务器解决方案？本文将带你使用Hutool的SimpleServer组件，通过3行核心代码快速搭建功能完备的HTTP服务器，轻松应对本地开发、临时接口测试、静态资源托管等场景。

技术原理与核心组件

Hutool的HTTP服务器模块基于JDK内置的com.sun.net.httpserver实现，通过封装简化了服务器创建、请求处理和响应发送的流程。核心实现类SimpleServer位于hutool-http/src/main/java/cn/hutool/http/server/SimpleServer.java，提供了链式API设计，支持端口绑定、请求过滤、路由映射等功能。

服务器工作流程包含三个关键环节：

请求接收：通过HttpServer监听指定端口，接收客户端连接
请求处理：通过ActionHandler将请求分发到对应的Action处理器
响应发送：通过HttpServerResponse封装响应数据并返回客户端

核心组件结构如下：

graph TD
    A[SimpleServer] --> B[HttpServer]
    A --> C[HttpFilter]
    A --> D[ActionHandler]
    D --> E[RootAction]
    D --> F[自定义Action]
    B --> G[HttpServerRequest]
    B --> H[HttpServerResponse]

快速上手：3行代码启动服务器

环境准备

在项目中引入Hutool HTTP模块依赖（以Maven为例）：

<dependency>
    <groupId>cn.hutool</groupId>
    <artifactId>hutool-http</artifactId>
    <version>5.8.22</version>
</dependency>

基础服务器搭建

创建ServerDemo.java，编写以下代码：

import cn.hutool.http.server.SimpleServer;

public class ServerDemo {
    public static void main(String[] args) {
        // 创建服务器并绑定8080端口
        new SimpleServer(8080)
            // 设置静态资源根目录
            .setRoot("D:/static")
            // 启动服务器
            .start();
    }
}

运行程序后，控制台将输出：

Hutool Simple Http Server listen on 【localhost:8080】

此时访问http://localhost:8080即可查看D:/static目录下的静态文件。

高级功能配置

自定义请求处理

通过addAction方法可以绑定特定路径到自定义处理器。例如创建一个返回JSON数据的接口：

new SimpleServer(8080)
    .addAction("/api/hello", (request, response) -> {
        // 设置响应类型为JSON
        response.setContentType("application/json;charset=utf-8");
        // 发送JSON响应
        response.write("{\"msg\":\"Hello Hutool Server\"}");
    })
    .start();

访问http://localhost:8080/api/hello将得到JSON响应：{"msg":"Hello Hutool Server"}

请求过滤与拦截

使用addFilter方法添加全局过滤器，可用于身份验证、日志记录等场景：

new SimpleServer(8080)
    .addFilter((request, response, chain) -> {
        // 记录请求日志
        System.out.println("Request: " + request.getMethod() + " " + request.getURI());
        // 继续处理请求
        chain.doFilter();
    })
    .setRoot("D:/static")
    .start();

HTTPS安全配置

通过HttpsConfigurator可以快速启用HTTPS支持，需要准备SSL证书：

// 创建SSL上下文
SSLContext sslContext = SSLContext.getInstance("TLS");
// 加载证书（此处省略证书加载代码）
// ...

// 创建HTTPS服务器
new SimpleServer(
    new InetSocketAddress(443), 
    new HttpsConfigurator(sslContext)
).start();

典型应用场景

本地静态网站开发

将Markdown文档、前端静态页面放置在指定目录，通过SimpleServer实现本地预览：

new SimpleServer(8080)
    .setRoot("D:/my-blog")  // 包含HTML/MD文件的目录
    .start();

临时API模拟服务

在前端开发过程中，通过SimpleServer快速搭建模拟接口，避免等待后端接口开发：

new SimpleServer(8080)
    .addAction("/api/users", (req, res) -> {
        res.write("[{\"id\":1,\"name\":\"张三\"},{\"id\":2,\"name\":\"李四\"}]");
    })
    .addAction("/api/products", (req, res) -> {
        res.write("[{\"id\":101,\"name\":\"Hutool工具包\"}]");
    })
    .start();

轻量级文件共享

通过设置根目录为文件存放目录，实现局域网内文件共享：

// 共享D盘下的share目录
new SimpleServer(8080)
    .setRoot("D:/share")
    .start();

同一局域网内的其他设备通过访问你的IP地址（如http://192.168.1.100:8080）即可浏览和下载文件。

性能优化与扩展

线程池配置

通过setExecutor方法自定义线程池，优化并发处理能力：

// 创建自定义线程池
ExecutorService executor = new ThreadPoolExecutor(
    10,  // 核心线程数
    50,  // 最大线程数
    60,  // 空闲时间
    TimeUnit.SECONDS,
    new LinkedBlockingQueue<>()
);

new SimpleServer(8080)
    .setExecutor(executor)  // 设置自定义线程池
    .setRoot("D:/static")
    .start();

请求路径映射

通过多个addAction调用实现复杂的路由配置：

new SimpleServer(8080)
    .addAction("/", (req, res) -> res.write("首页"))
    .addAction("/about", (req, res) -> res.write("关于我们"))
    .addAction("/contact", (req, res) -> res.write("联系我们"))
    .start();

常见问题解决方案

端口占用问题

当启动时报错"Address already in use"，表示端口被占用，可通过以下方式解决：

// 方式1：更换端口
new SimpleServer(8081).start();

// 方式2：查找并关闭占用端口的进程
// Windows: netstat -ano | findstr :8080
// Linux: lsof -i:8080

跨域访问配置

添加CORS过滤器解决前端跨域问题：

new SimpleServer(8080)
    .addFilter((req, res, chain) -> {
        // 设置允许跨域的域名
        res.setHeader("Access-Control-Allow-Origin", "*");
        // 设置允许的请求方法
        res.setHeader("Access-Control-Allow-Methods", "GET,POST,PUT,DELETE,OPTIONS");
        chain.doFilter();
    })
    .start();