纯Java手写HTTP服务器：从ServerSocket到静态文件服务

简介这款简单的JAVA HTML服务器基于Socket、线程池、输入输出流与基础HTTP协议实现虽然仅有少量核心类却完整展现了从TCP监听到HTTP响应解析的服务器骨架。适合Java初学者理解网络编程、并发处理与HTTP协议交互流程也可作为课程设计或毕业设计的基础参考。资源压缩包共7个文件包含2个Java源码、2个可直接运行的JAR包、2个示例HTML页面和1份使用说明txt整体大小仅26KB轻量易部署。说明文档给出了DOS命令行启动方式与默认端口配置读者可快速将HTML文件发布到本地1234端口查看效果。源码基于JDK1.6编写使用了JDK自带的线程池想要深入研究的开发者可直接修改源码重新打包。目前已有297人学习下载对想用最少代码理解HTTP服务器原理的入门者而言是一份短小精悍、值得动手实践的参考资料。 做Java开发这几年见过不少同事一提到“写服务器”就条件反射地打开Spring Boot工程加个spring-boot-starter-web然后RestController一标跑起来完事。这当然没问题但如果你连HTTP协议长什么样都没见过哪怕Boot用得再熟练遇到线上怪问题也只能干瞪眼。前阵子我在给团队做内部分享时就用一个“简单的JAVA HTML服务器”做切入点从零搭了一个只依赖JDK的静态文件服务半个多小时讲完大家反而比看十分钟的框架源码更来劲。这篇博文我就把这次实操完整记录下来不引任何第三方依赖就用ServerSocket亲手完成端口监听、请求解析、文件读取和响应返回把Java、HTML、服务器三者串成一个能跑起来的整体。这套东西适合谁想搞清楚HTTP请求到底怎么走的后端新人被面试官问“HTTP服务器原理”却答不上细节的求职者以及工作中只想快速起一个本地静态页面预览工具的老手。下文会逐个环节拆解每个关键步骤都会解释“为什么这么做”最后附上我踩过的坑和排查思路照着敲一遍你会收获一个完全属于自己的迷你Web服务器。1. 项目背景与整体设计思路1.1 为什么要用纯JDK实现一个HTTP服务器市面上现成的服务器太多了Tomcat、Jetty、Undertow甚至Nginx都能秒级托管HTML文件。那为什么还要拿纯JDK写一遍最直接的原因就是只有亲手写过一次你才能真正理解HTTP服务器到底在做什么。很多同学用Spring Boot写接口只知道方法上标个GetMapping浏览器请求进来就能返回结果。但中间的映射逻辑、请求行解析、响应状态码设置、Content-Type赋值全都被框架藏起来了。一旦遇到像“浏览器打开乱码”“静态资源加载不出来”“接口偶发超时”这类问题没有底层概念就很难定位。而自己实现一遍HTTP服务器你会自然理解浏览器发来的其实就是一串文本服务器要做的就是解析这串文本、找到资源、再按指定格式拼一串文本返回去。这个认知一旦建立再回看框架的文档和源码很多配置项的意义就一目了然。另外一点是面试价值。Java面试题里“Socket编程”和“HTTP协议”都是高频考点面试官尤其喜欢问“如果让你实现一个简单的Web服务器你会怎么做”。实际写过一遍的人能立刻说出ServerSocket.accept()、请求行格式、响应头必备字段、状态码含义甚至能指出线程模型的瓶颈这是背八股文换不来的深度。1.2 方案选型ServerSocket 还是 HttpServerJDK其实自带了一个com.sun.net.httpserver.HttpServer类能直接创建HTTP服务比ServerSocket封装得更高级。那为什么我最终选择ServerSocket因为HttpServer虽然省事但它把大量细节隐藏在了内部实现里比如请求解析、线程调度都替你处理好了。用这个类写出来的东西本质上还是“调框架”对理解协议本身帮助有限。用ServerSocket则相当于拿到HTTP服务器的“最小骨架”一个监听端口的套接字一个接收连接的accept()方法剩下的协议解析全部自己写。虽然代码量多一点但每一行都对应着一个明确的概念。等你把整个流程跑通之后再去看HttpServer源码几分钟就能读懂它内部做了什么。两种选型的对比如下方案依赖HTTP协议暴露程度上手难度适用场景ServerSocket仅JDK完全暴露手工解析中学习原理、面试准备、极简工具HttpServer仅JDK部分封装低快速搭建内部接口、本地轻量服务Tomcat / Jetty第三方高度封装低生产环境、复杂应用这个项目定位就是“学习本地工具”所以ServerSocket是最合适的选择。2. 环境准备与项目骨架2.1 环境要求与目录结构这个项目对环境的要求低到令人发指只要装了JDK 8或以上版本即可命令行编译运行都行不需要Maven、Gradle也不需要IDE。我日常用的是JDK 11如果你机器上只有JDK 8也完全没问题代码里用到的API都是JDK 1.0时代就有的。我习惯把工程目录和网页资源分开方便后面做路径映射。建议按下面这个结构组织simple-http-server/ ├── src/ │ └── SimpleHttpServer.java ├── webroot/ │ ├── index.html │ ├── style.css │ ├── app.js │ └── images/ │ └── logo.png └── README.mdwebroot就是服务器要对外暴露的静态资源目录对应Web服务器里的“站点根目录”。后续浏览器请求根路径/时服务器就在这里查index.html请求/style.css时就查webroot/style.css。2.2 准备一个顺手的前端测试页既然要做HTML服务器网页文件肯定得准备。别用太复杂的内容够测试就行。我的index.html长这样!DOCTYPE html html langzh-CN head meta charsetUTF-8 title简单Java HTML服务器测试页/title link relstylesheet href/style.css /head body h1服务器运行正常/h1 p这是由纯Java Socket实现的HTTP服务器返回的页面。/p img src/images/logo.png altlogo width100 script src/app.js/script /body /html页面里故意引了CSS、图片和JS三种资源目的是测试服务器对不同文件类型的响应是否正确。style.css随便写一句h1 { color: blue; }app.js写一句console.log(loading ok)图片可以随便找一张小尺寸的。准备好这些后面按章节跑起来页面正常渲染就说明静态资源服务已经通了。3. 核心代码实现与HTTP协议拆解3.1 端口监听与多线程处理模型服务器启动的第一步是创建一个ServerSocket并绑定端口。这个端口相当于服务器对外服务的“门牌号”浏览器访问http://localhost:8080就是通过这个门牌号找过来的。我选8080而不是80是因为80端口是HTTP协议默认端口在Linux上绑定需要root权限本地开发完全没必要折腾权限问题。public class SimpleHttpServer { private static final int PORT 8080; private static final String WEB_ROOT webroot; public static void main(String[] args) throws IOException { ServerSocket serverSocket new ServerSocket(PORT); System.out.println(服务器启动成功访问 http://localhost: PORT); while (true) { Socket socket serverSocket.accept(); new Thread(() - handleRequest(socket)).start(); } } }accept()方法是一个阻塞调用会一直等在那里直到有客户端连接进来。while(true)保证服务器能持续服务不同请求。但这里有一个明显的隐患每来一个请求就new Thread如果并发量大了线程会无节制地创建程序很快就吃不消。这个设计对学习来说够用但真要扛并发应该用线程池。改成ExecutorService其实就几行代码用Executors.newFixedThreadPool(8)替换裸new Thread即可。我在实际演示中会先跑单线程版本然后模拟浏览器发两个并发请求让大家亲眼看到第二个请求被卡住的现象再切到线程池版本。这个对比比单纯讲理论有效得多。3.2 请求解析拿到“用户在要什么”浏览器连接过来之后服务器要做的第一件事是读取客户端发来的请求数据。HTTP请求其实是一段有固定格式的文本第一行叫请求行包含请求方法、请求路径和协议版本后面跟着若干请求头直到空行结束。一个典型的GET请求长这样GET /index.html HTTP/1.1 Host: localhost:8080 User-Agent: Mozilla/5.0 ... Accept: text/html服务器不需要关心所有请求头最关键的就是请求行里的三要素。解析代码如下private static void handleRequest(Socket socket) { try (BufferedReader in new BufferedReader(new InputStreamReader(socket.getInputStream())); OutputStream out socket.getOutputStream()) { String requestLine in.readLine(); if (requestLine null || requestLine.isEmpty()) { return; } System.out.println(收到请求: requestLine); String[] parts requestLine.split( ); if (parts.length 2) { sendError(out, 400, Bad Request); return; } String method parts[0]; String requestPath parts[1]; if (!GET.equals(method)) { sendError(out, 405, Method Not Allowed); return; } // 继续处理请求路径... } catch (Exception e) { e.printStackTrace(); } finally { try { socket.close(); } catch (IOException ignored) {} } }注意split( )按空格切分请求行。requestPath可能长成/index.html或/style.css如果请求的是根路径/后续要给它映射成默认首页/index.html。这里有一个容易踩的坑请求路径里经常带着查询参数比如/index.html?id123。如果不处理文件查找会直接拿着/index.html?id123这个字符串去拼路径结果必然找不到文件。所以拿到requestPath之后要先把?后面的参数部分去掉这一步叫“清洗路径”。我见过不少新手在这栽跟头后面把路径清洗逻辑写进公共方法。3.3 响应构造把内容按协议返回去拿到文件内容后服务器要按HTTP协议格式返回给浏览器。响应格式同样不是随便拼的第一行是状态行后面是响应头、空行和响应体。空行是响应头和响应体的分界线少了这个空行浏览器会以为整个响应都是响应头页面就渲染不出来。private static void sendResponse(OutputStream out, int statusCode, String contentType, byte[] body) throws IOException { String statusText switch (statusCode) { case 200 - OK; case 400 - Bad Request; case 404 - Not Found; case 405 - Method Not Allowed; default - Internal Server Error; }; String header HTTP/1.1 statusCode statusText \r\n Content-Type: contentType \r\n Content-Length: body.length \r\n Connection: close\r\n \r\n; out.write(header.getBytes(UTF-8)); out.write(body); out.flush(); }几个关键的响应头字段解释一下。Content-Type告诉浏览器返回的数据是什么类型是HTML还是CSS还是图片浏览器才能决定怎么解析。Content-Length声明响应体的字节数浏览器据此知道要读多少数据才算接收完。如果服务端返回数据量和这个值对不上浏览器会报错或一直等待。Connection: close则告诉浏览器响应结束后直接关闭连接省得维护长连接状态。这串\r\n是需要特别注意的编码细节。HTTP协议规定行尾必须是回车加换行也就是CRLF。如果用\n大部分浏览器宽容能处理但严格遵循RFC的客户端可能解析出错。既然写到底层了就按标准来。3.4 MIME类型映射与静态文件读取静态资源服务最核心的一步就是根据文件扩展名返回对应的Content-Type。HTML要返回text/htmlCSS要返回text/cssPNG图片要返回image/png如果统一都返回text/html浏览器拿到CSS文件会直接按纯文本展示页面样式就全丢了。private static String getContentType(String fileName) { if (fileName.endsWith(.html) || fileName.endsWith(.htm)) return text/html; charsetutf-8; if (fileName.endsWith(.css)) return text/css; charsetutf-8; if (fileName.endsWith(.js)) return application/javascript; charsetutf-8; if (fileName.endsWith(.jpg) || fileName.endsWith(.jpeg)) return image/jpeg; if (fileName.endsWith(.png)) return image/png; if (fileName.endsWith(.gif)) return image/gif; if (fileName.endsWith(.ico)) return image/x-icon; if (fileName.endsWith(.json)) return application/json; charsetutf-8; if (fileName.endsWith(.pdf)) return application/pdf; return application/octet-stream; }字符集charsetutf-8这个细节很关键。HTML文件里虽然写了meta charsetUTF-8但如果响应头里没声明字符集浏览器在解析响应时会先用默认编码猜测。中文Windows环境经常默认用GBK一旦猜错就乱码。在Content-Type里显式声明charsetutf-8能彻底避免这个坑。文件读取直接用Files.readAllBytes最省事String cleanPath requestPath.contains(?) ? requestPath.substring(0, requestPath.indexOf(?)) : requestPath; String fileName cleanPath.equals(/) ? /index.html : cleanPath; File file new File(WEB_ROOT, fileName); if (file.exists() file.isFile()) { byte[] content Files.readAllBytes(file.toPath()); sendResponse(out, 200, getContentType(fileName), content); } else { sendError(out, 404, Not Found); }映射逻辑就三步清洗路径、拼接webroot、读文件。如果文件不存在就返回404错误页。这段代码虽然短却是整个服务器功能的骨架。4. 功能增强与边界情况处理4.1 默认首页与404错误页服务器不能只服务/index.html用户访问http://localhost:8080时实际上发的是根路径/所以必须做默认首页映射。我上面的代码用了cleanPath.equals(/)判断然后指向/index.html这就是绝大多数Web服务器的默认首页机制。如果资源目录下没有index.html浏览器会看到404页面效果和Nginx找不到首页时一样。错误页也有讲究。最基础的版本是在sendError方法里返回一段简单的HTML字符串。实际操作中我建议把404页做得友好一点毕竟这是用户能直接看到的界面。一个完整点的错误页可以包含诉求说明、返回首页的链接、错误码标识甚至埋点统计但核心逻辑不变。private static void sendError(OutputStream out, int statusCode, String message) throws IOException { String body !DOCTYPE htmlhtml langzh-CNheadmeta charsetUTF-8 title statusCode message /title/head bodyh1 statusCode message /h1 pa href/返回首页/a/p/body/html; sendResponse(out, statusCode, text/html; charsetutf-8, body.getBytes(UTF-8)); }注意错误页也要走sendResponse流程而不是随便写一段内容就完事。状态码、响应头、响应体三要素一个都不能少否则浏览器无法识别这是一个错误响应。4.2 中文乱码与字符集处理中文乱码是Java Web开发里最高频的问题之一在这个迷你服务器上同样存在。乱码根源只有一个数据从字节到字符的转换过程中发送方和接收方用的字符集不一致。浏览器发送请求时URL里的中文路径会经过URL编码比如/测试.html在HTTP请求行里会变成/%E6%B5%8B%E8%AF%95.html这是UTF-8的百分号编码形式。服务器拿到这个路径后直接拿字符串去拼文件路径系统会把%E6%B5%8B当成普通字符而不是编码自然找不到文件。解决办法有两种一是在服务端做URL解码用URLDecoder.decode(cleanPath, UTF-8)还原成中文路径二是约定所有资源文件名都用英文不碰中文。第二种做法在实际项目中更常见毕竟静态资源命名的通用规范就是英文加短横线。但响应内容里的中文又是另一回事。HTML文件本身是UTF-8编码服务器读入字节后原样返回只要响应头声明了charsetutf-8浏览器就能正确渲染。我自己调试时为了排除文件编码问题会先用file命令或者IDE确认HTML文件编码确实是UTF-8。很多新手用记事本存文件保存的其实是GBK网页里明明写了meta charsetUTF-8也救不回来。这不是服务器代码的锅是文件本身的编码就错了。4.3 单线程模型下的阻塞问题不引入线程池的单线程版本有一个特别直观的毛病一个请求占住连接后后面所有请求都得排队等着。我当时做演示故意在handleRequest里加了一行Thread.sleep(5000)模拟耗时请求结果浏览器刷新页面整个服务器就死了5秒什么请求都处理不了。这个现象背后是accept()和handleRequest()在同一个线程里串行执行。accept()等到一个连接后进入handleRequest方法慢慢读数据、发响应这段时间内不会回到accept()继续等待新连接。所以必须让每个连接的处理逻辑脱离主线程。改成线程池的代码量很小ExecutorService executor Executors.newFixedThreadPool(8); while (true) { Socket socket serverSocket.accept(); executor.submit(() - handleRequest(socket)); }固定8个线程对本地小工具完全够用。而且线程池还附带一个好处任务队列能起到天然的削峰作用。如果瞬时请求量超过8个多余请求会在队列里排队而不是直接把系统拖垮。这个模型和Tomcat的默认连接器设计思路其实是相通的搞懂了小的再看大的就不觉得神秘。5. 常见问题与排查技巧实录5.1 端口被占用怎么办启动服务器时报java.net.BindException: Address already in use: bind这是端口被占用了。最直接的原因是上次启动的Java进程没退出或者8080被其他程序占用。排查分三步走先看占用进程再杀掉旧进程或者干脆换端口启动。Windows下命令是netstat -ano | findstr :8080 taskkill /PID 进程号 /FLinux/macOS下命令是lsof -i :8080 kill -9 进程号除了解决眼前问题我建议把端口号定义为常量并支持启动参数覆盖比如java SimpleHttpServer 9090这样换端口时不用改代码。生产环境更正规的做法是把端口做成配置项但这个项目里用启动参数演示最直观。5.2 浏览器缓存导致的“改了不生效”开发时修改了HTML或CSS文件刷新浏览器却还是旧页面。这不是服务器代码有问题而是浏览器HTTP缓存机制在起作用。浏览器对无Cache-Control头的响应会按启发式缓存策略决定要不要复用本地副本有时候就给你用了旧版本。解决办法有两个层面。服务端方面在响应头里加上Cache-Control: no-cache告诉浏览器每次都要向服务器确认资源是否更新。客户端方面开发时按CtrlF5强制刷新绕过缓存。对生产环境来说给静态资源加Cache-Control和ETag是另一套完整策略这里不展开但明白原理后你至少知道问题出在哪不会傻乎乎地去重启服务器。5.3 URL编码与特殊字符解析浏览器地址栏里的路径并不一定就是服务器实际收到的字符串。空格会被编码为%20中文会被编码为%E6%B5%8B%E8%AF%95?后面跟的是查询参数而不是路径部分。服务器做文件映射前必须先解码。我之前有个案例调试时发现明明浏览器访问/my%20page.html服务器收到的却是/my page.html。查了一圈才发现现代浏览器在发送请求时会根据请求头的Host和URL规范自动把空格还原成%20再发出去。服务器端其实收到的是编码后的字符串。所以如果你在服务器端打印请求行发现带了%20之类的内容别慌这就是正常的。要做的是在拼接文件路径之前调用URLDecoder.decode把它还原成空格再去文件系统里找对应文件。不过这里有个注意点URLDecoder.decode会把号也解码成空格而URL路径里的可能本身就是合法的加号字符。更严谨的做法是只对路径中的各段单独解码避免对路径分隔符/做错误处理。对当前项目来说直接整体解码基本够用因为我们的文件路径里很少有加号。5.4 大文件传输与内存溢出的风险我用Files.readAllBytes读取文件到内存再发送这在演示环境没问题但涉及大文件时会有隐患。假设webroot里放了一个500MB的视频文件服务器会一次性把这500MB读进JVM堆内存。如果同时有几个并发请求OutOfMemoryError就会找上门也就是热词里那个java: OutOfMemoryError: insufficient memory的典型场景。解决思路是使用流式传输把文件切片读写try (FileInputStream fis new FileInputStream(file)) { out.write(header.getBytes(UTF-8)); byte[] buffer new byte[8192]; int bytesRead; while ((bytesRead fis.read(buffer)) ! -1) { out.write(buffer, 0, bytesRead); } out.flush(); }同时响应头里的Content-Length依然要设置成file.length()这样浏览器才知道什么时候数据算收完。这个思路理解以后再看Nginx的sendfile配置、Tomcat的sendfile优化就明白它们在做什么了都是想办法减少数据在用户态和内核态之间的拷贝次数避免将全部内容一次性装入内存。5.5 常见问题速查表现象可能原因排查思路启动报端口占用8080被其他进程占用netstat/lsof 查看进程kill 后重试浏览器访问拒绝连接服务器没启动或防火墙拦截检查启动日志telnet 127.0.0.1 8080 测试页面中文乱码HTML文件编码或响应头字符集不对确认文件是UTF-8Content-Type带charsetutf-8刷新后页面不更新浏览器缓存CtrlF5 强制刷新响应头加 no-cacheCSS/图片加载不出来MIME类型映射缺失或路径错误看服务器日志打印的请求路径检查webroot目录结构并发请求卡住单线程模型换线程池限制并发大文件导致OOM一次性读取整个文件进内存改流式读取分批写响应请求路径带参数404没清洗URL查询参数先按?切分路径再做文件映射6. 从迷你服务器到生产级Web服务器的差距写完这个迷你服务器不妨再想想它和Tomcat、Nginx之间还差着什么带着这个问题去学习效率会高很多。第一层差距在协议完整性。HTTP/1.1要求支持持久连接、分块传输、条件请求、Keep-Alive复用、虚拟主机等这些在迷你服务器里全部没实现。第二层差距在并发与IO模型。ServerSocket加线程池属于经典的BIO阻塞IO模型而生产级服务器普遍采用NIO或异步IO用更少的线程支撑更高的并发。第三层差距在安全与治理。路径穿越防护、请求大小限制、访问控制、日志审计、动态路由这些“看不见的工程”才是一个能用服务器的底气。但反过来说正因为它简单才能把HTTP协议最核心的骨架完整暴露出来。理解了请求行、状态行、响应头、Content-Length这些基础概念再看任何Web框架的源码都不会再觉得是黑盒子。很多框架的底层无非就是在这个骨架上填充了更多功能。最后再说一个个人小技巧如果你想把这段代码拿来当本地开发工具可以给它加一个--directory启动参数指定任意目录作为webroot再配合一个简单的html文件就相当于自己写了一个可配置的静态文件服务器。做些小页面、临时分享文件完全够用。这也是我日常用得最爽的场景之一。本文还有配套的精品资源点击获取