caveman这个项目名是我在一个失眠的深夜敲定的。当时我正被一套相当现代化的Web工具链折腾得怀疑人生装依赖、配构建、等编译一个Hello World硬是花了整个晚上。盯着终端里五颜六色的报错我忽然特别怀念小时候用记事本写HTML、双击就能在浏览器打开的年代。于是就有了这个叫caveman的小实验——一个只用Python标准库、零第三方依赖、从socket开始徒手实现的极简HTTP服务器。它不是一个能上生产的框架更像一次把自己丢回石器时代的底层演练我想亲眼看着一个HTTP请求进来再亲手把一个响应送回去。这篇文章就是caveman从设计到落地的完整复盘适合被框架封装惯了、想真正吃透Web协议底层的开发者也适合刚学完socket想找点练手项目的同学。1. 为什么是caveman一个返璞归真的Web服务实验1.1 项目到底做了什么caveman不是什么大厂开源项目它是我个人用来拆解黑盒的练手作品。它具备一个最基础Web服务器该有的能力能监听本机端口能解析HTTP请求能返回静态文件能区分GET和POST还能用一个简单的线程池同时服务多个浏览器连接。整套实现只依赖Python标准库里的socket、os、threading、functools等模块没有一行第三方依赖。压缩下来不到两百行代码却完整地跑通了输入网址、敲回车、看到页面这条最日常的请求响应链路。我特意把代码规模压在几百行以内因为它的定位是显微镜而不是盾牌。你要能一眼看完所有逻辑知道每一次recv、每一行split、每一个sendall是为了什么。一旦规模膨胀到几千行这个项目就失去了意义。这也决定了caveman的边界不做HTTPS、不做HTTP/2、不追求高并发、不兼容复杂网关只踏踏实实把HTTP那套明文协议练扎实。1.2 为什么要用穴居人思路做Web服务说句实在话现在写Web应用太幸福了框架帮你把路由、中间件、模板、ORM全部包装好你只要注册一个装饰器剩下的交给黑盒。可一旦遇到性能问题、奇怪Bug你连从哪里下手都不知道。caveman的思路就是穴居人式的——不搞全自动厨房只磨一把趁手的石斧。先解决请求来了怎么回应这个最底层的问题你才能真正理解框架到底帮你做了什么。我见过不少人用了一年Flask却说不清请求进来后第一个被执行的东西是什么。这不怪开发者因为框架把太多东西吞进了肚子里。你天天用筷子吃饭不代表你懂水稻怎么变成大米同理天天用框架写接口也不代表你懂HTTP。caveman逼着我把一碗米从稻谷开始亲手碾出来这是它最大的价值。1.3 这个实验适合谁、不适合谁我做完之后的感受是它特别适合三类人刚入门后端、对Flask/Django之类的框架处于只会用、不懂原理状态的开发者想练习网络编程、想搞清楚TCP和HTTP关系的同学以及被复杂中间件折磨到想回归本质的老熟人。反过来如果你要的是生产级高可用服务或者你只是想快速搭一个能上线的API那请直接去用成熟的Web框架。caveman不是它们的替代品它是你真正理解那些框架之前的必修课。2. 核心细节拆解HTTP请求与响应的最小闭环2.1 请求进入的完整链路理解一个HTTP服务器首先要吃透一条最基本的事实HTTP协议是跑在TCP之上的文本协议。浏览器发出去的请求到了服务端就是一段有固定格式的字节流用什么高级框架也不例外。在caveman里链路非常直观服务器在某个端口上accept等来一个客户端连接后用recv读取一段字节然后按照HTTP的规则把这些字节拆解成方法和路径。请求的格式是每行以\r\n结尾第一行是请求行形如GET /index.html HTTP/1.1从第二行开始是请求头每一行是一个key: value再往下空一行之后才是请求体。这里有个特别容易踩的小坑HTTP协议的换行符是\r\n也就是回车加换行不是单纯\n。第一次手写解析器时我也图省事只按\n分割结果浏览器倒还认但如果你用nc手工调试或对接严格的服务端时就会遇到各种微妙的问题。所以解析函数里我总是先把\r\n处理好标准协议永远照着标准来。def parse_request(raw: bytes): text raw.decode(utf-8, errorsreplace) lines text.split(\r\n) request_line lines[0] parts request_line.split( ) method, target, version parts[0], parts[1], parts[2] if len(parts) 3 else HTTP/1.1 headers {} content_length 0 for line in lines[1:]: if not line: break # 空行头部结束 key, _, value line.partition(:) headers[key.strip()] value.strip() if key.lower() content-length: content_length int(value.strip()) body b # 简化做法在recv缓冲区里找空行之后的内容 header_end text.find(\r\n\r\n) if header_end ! -1: body raw[header_end 4:] return method, target, headers, body2.2 响应为什么差一个Content-Length都不行请求解析完服务器的任务就是返回响应。响应格式同样传统状态行、响应头、空行、响应体四段。状态行如HTTP/1.1 200 OK响应头里最容易被忽略的就是Content-Length。这个字段告诉浏览器响应体一共多少字节。如果你漏了它且连接没有关闭浏览器就会进入漫长的等待状态——它不知道内容还有没有后续一直转圈直到超时。这是新手手写服务器最容易遇到的问题我曾在caveman早期版本里因为忘记计算字节长度开着浏览器干瞪眼了好几分钟。def http_response(body: bytes, status: str 200 OK, content_type: str text/html; charsetutf-8): headers [ fHTTP/1.1 {status}, fContent-Type: {content_type}, fContent-Length: {len(body)}, Connection: close, Server: caveman/0.1, ] head (\r\n.join(headers) \r\n\r\n).encode(utf-8) return head body注意这里的Content-Length用的是len(body)也就是字节数不是字符串长度。如果body是中文字符串长度和字节数会差很远用错就又是一场乱码灾难。2.3 静态文件服务路径和MIME是两道关卡静态文件是浏览器访问最频繁的场景。在caveman里我只处理一个根目录请求路径对应一个文件。这里有两道关卡第一道是默认页访问/时自动返回index.html第二道是MIME类型。MIME本质是告诉浏览器这个文件该用什么方式打开比如html文件给text/htmlpng图片给image/png。如果不给正确MIME浏览器可能直接把图片当成下载文件弹下来体验非常奇怪。读取文件时必须用rb二进制模式图片等二进制内容才不会在中途损坏。千万不要用r文本模式去读png你会在编码环节稀里糊涂地得到一堆乱码。MIME映射不需要覆盖全宇宙把常用的列出来就够了。扩展名Content-Type.htmltext/html; charsetutf-8.csstext/css; charsetutf-8.jsapplication/javascript.jsonapplication/json.pngimage/png.jpg / .jpegimage/jpeg.svgimage/svgxml.txttext/plain; charsetutf-82.4 路由、查询参数和POST表单的简单实现caveman支持路径路由但我不打算做一个复杂的Router只用if-else判断target路径即可。查询参数藏在路径问号后面例如/hello?namecaveman用Python自带的urllib.parse.parse_qs就能拆成字典。POST请求不同它的参数放在请求体里需要先拿到请求头里的Content-Length然后按长度读取body再解析body里的keyvalue串。这也是为什么解析函数里我特别注意Content-Length的原因——GET的body基本为空而POST的body有明确长度读完正好多读会阻塞少读会丢数据。from urllib.parse import urlparse, parse_qs, unquote # 路由示例 parsed urlparse(target) path unquote(parsed.path) query parse_qs(parsed.query) if path /: path /index.html elif path /hello: name query.get(name, [caveman])[0] # 返回一段动态HTML3. 实操全流程让caveman跑起来3.1 环境检查与最小监听器动手之前先确认环境caveman依赖的是Python3不需要装任何包。我建议在项目目录下建一个public文件夹把HTML、CSS、JS都放进去服务器只从这个目录往外读文件其他目录一概不碰。最小监听器十几行就能写出来创建socket、绑定端口、监听、进入accept循环。import socket HOST, PORT 127.0.0.1, 8080 server socket.socket(socket.AF_INET, socket.SOCK_STREAM) server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) server.bind((HOST, PORT)) server.listen(128) print(fcaveman listening on http://{HOST}:{PORT}) while True: conn, addr server.accept() data conn.recv(4096) print(fnew request from {addr}: {data[:60]}...) conn.sendall(bHTTP/1.1 200 OK\r\nContent-Length: 2\r\n\r\nok) conn.close()端口选8080而不是80是因为1024以下的端口在Linux和macOS上需要root权限做实验没必要跟权限较劲。HOST用127.0.0.1意味着只在本地回环地址监听外网无法访问安全又省事。3.2 搭出请求解析器把前面的parse_request接进来再带上recv后判断空数据的逻辑。浏览器关闭连接时recv可能返回空字节这种连接要跳过去否则后面解析会出错。while True: conn, addr server.accept() raw conn.recv(4096) if not raw: conn.close() continue method, target, headers, body parse_request(raw) print(method, target, headers.get(User-Agent, ))recv(4096)里的4096是单次接收缓冲区上限不是必须读满所以不要假设一次recv就能收完整个请求。HTTP请求头通常很小这个数字足够覆盖绝大多数场景如果请求体更大就得配合Content-Length循环读取。caveman这个教学版本只做单次读取够用就行。3.3 实现静态文件服务和安全校验静态文件这边最重要的一条是防路径穿越。如果用户请求的URL是/../../etc/passwd拼接后就会跳到项目目录之外后果不堪设想。解决办法很简单先把真实路径resolve出来再检查这个真实路径是否以根目录的真实路径开头。import os ROOT os.path.join(os.path.dirname(__file__), public) ROOT_REAL os.path.realpath(ROOT) def serve_static(path): if path /: path /index.html full os.path.realpath(os.path.join(ROOT_REAL, path.lstrip(/))) if not full.startswith(ROOT_REAL): return http_response(b403 Forbidden, 403 Forbidden, text/plain; charsetutf-8) if not os.path.isfile(full): return http_response(b404 Not Found, 404 Not Found, text/plain; charsetutf-8) with open(full, rb) as f: content f.read() ctype guess_mime(full) return http_response(content, 200 OK, ctype)用startswith判断前缀有一些边缘Case比如根目录是/path/public另一个目录是/path/public_evil也会误判。更严谨的做法是在路径后面加一个os.sep再判断也就是检查full os.sep或直接判断full.startswith(ROOT_REAL os.sep)或full ROOT_REAL。这个小细节我后来才补上属于手写服务器才遇得到的坑。3.4 用线程池解决并发阻塞到这里服务器已经能用了但你很快会发现一个严重问题一次只能处理一个请求。如果某个请求响应慢后面的请求全被堵在accept外面。caveman补上并发能力的方式很朴素用concurrent.futures.ThreadPoolExecutor开一个固定大小的线程池每个连接丢给线程池处理。线程数不用多默认10个左右足够撑起这个实验。注意不要为了炫技开几千线程线程切换开销会让性能急剧下降。from concurrent.futures import ThreadPoolExecutor pool ThreadPoolExecutor(max_workers10) while True: conn, addr server.accept() pool.submit(handle_connection, conn, addr)3.5 一个可以直接运行的整体代码骨架我把上面的零件拼成一个完整版你可以直接存成server.py跑一下。核心思路依然是穴居人式的任何部分都能看穿任何行为都可预期。import socket import os from concurrent.futures import ThreadPoolExecutor from urllib.parse import urlparse, parse_qs, unquote HOST, PORT 127.0.0.1, 8080 ROOT os.path.join(os.path.dirname(__file__), public) ROOT_REAL os.path.realpath(ROOT) MIME { .html: text/html; charsetutf-8, .css: text/css; charsetutf-8, .js: application/javascript, .json: application/json, .png: image/png, .jpg: image/jpeg, .jpeg: image/jpeg, .svg: image/svgxml, .txt: text/plain; charsetutf-8, } def guess_mime(path): ext os.path.splitext(path)[1].lower() return MIME.get(ext, application/octet-stream) def parse_request(raw): text raw.decode(utf-8, errorsreplace) lines text.split(\r\n) parts lines[0].split( ) method parts[0] target parts[1] if len(parts) 1 else / headers {} for line in lines[1:]: if not line: break key, _, value line.partition(:) headers[key.strip()] value.strip() body b header_end text.find(\r\n\r\n) if header_end ! -1: body raw[header_end 4:] return method, target, headers, body def http_response(body, status200 OK, content_typetext/html; charsetutf-8): headers [ fHTTP/1.1 {status}, fContent-Type: {content_type}, fContent-Length: {len(body)}, Connection: close, Server: caveman/0.1, ] return (\r\n.join(headers) \r\n\r\n).encode(utf-8) body def serve_static(path): if path /: path /index.html full os.path.realpath(os.path.join(ROOT_REAL, path.lstrip(/))) if not full.startswith(ROOT_REAL): return http_response(b403 Forbidden, 403 Forbidden, text/plain; charsetutf-8) if not os.path.isfile(full): return http_response(b404 Not Found, 404 Not Found, text/plain; charsetutf-8) with open(full, rb) as f: content f.read() return http_response(content, 200 OK, guess_mime(full)) def handle_connection(conn, addr): try: raw conn.recv(4096) if not raw: return method, target, headers, body parse_request(raw) parsed urlparse(target) path unquote(parsed.path) if path /hello: query parse_qs(parsed.query) name query.get(name, [caveman])[0] html fh1Hello, {name}/h1pfrom caveman server/p.encode(utf-8) resp http_response(html) else: resp serve_static(path) conn.sendall(resp) finally: conn.close() server socket.socket(socket.AF_INET, socket.SOCK_STREAM) server.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) server.bind((HOST, PORT)) server.listen(128) print(fcaveman listening on http://{HOST}:{PORT}) pool ThreadPoolExecutor(max_workers10) while True: conn, addr server.accept() pool.submit(handle_connection, conn, addr)运行前先在项目目录里建一个public文件夹放一个index.html。我日常测试时就放了一句Welcome to caveman。然后python server.py浏览器打开http://127.0.0.1:8080/就能看到。想测试动态路由访问/hello?nameyourname试试。注意Windows下最后一行会一直阻塞在accept如果想停止服务直接CtrlC即可。4. 常见问题与排查技巧实录4.1 浏览器一直转圈却不显示页面做caveman最大的翻车现场就是页面一直转圈。绝大多数情况是响应头少了Content-Length或长度写错。浏览器无法判断请求是否彻底结束只能等待超时。排查方法很简单用curl -v看响应头如果返回内容里没有Content-Length问题就锁定在响应构造上。4.2 页面里的中文全变成乱码如果响应头用的是text/html而不是text/html; charsetutf-8中文字符大概率就会乱码。字符串编码成bytes之后浏览器不知道它是什么编码只能靠猜。规范做法是所有text类资源的Content-Type后面都带charsetutf-8JavaScript和CSS也建议加图片则是二进制格式不需要charset。4.3 静态资源404但文件明明存在这种问题大半出在路径拼接上。请求路径是/user/../index.html拼接时如果直接用原始字符串可能错位甚至出现路径穿越风险。我统一用os.path.realpath做规范化再检查前缀。如果发现页面能访问但CSS/JS加载失败优先看浏览器Network标签里资源的URL和服务器返回的状态码十有八九是路径拼接的锅。4.4 请求一多就卡死单线程版本遇到慢客户端会形成队头阻塞一个连接没处理完其他请求全部排队。解决方案就是线程池或者更进阶的select/epoll事件循环。caveman选线程池是因为代码直观每个连接一个任务子线程之间互不干扰。要注意的是线程池的max_workers别贪大我在本机试过10个和100个10个时的实际吞吐并不差100个反而会因为线程上下文切换而抖动。4.5 手工调试的几个命令有时候写服务器最高效的调试方式不是写测试而是直接发原始请求。curl提供了丰富的参数nc更是能把HTTP请求亲手打一遍。我调试caveman时最常用的命令列在这里。命令用途curl -v http://127.0.0.1:8080/查看完整请求与响应头curl -I http://127.0.0.1:8080/只获取响应头curl -X POST -d namecaveman http://127.0.0.1:8080/hello发送POST表单echo -e GET / HTTP/1.1\r\nHost: 127.0.0.1\r\n\r\n | nc 127.0.0.1 8080手写HTTP请求5. 再往前一步给caveman留的扩展位5.1 保持原始感的小扩展实验做完不代表项目就废了我给它留了几个不违背穴居人原则的扩展位把if-else路由换成一张路由表格用字典映射路径到处理函数增加一个简单的访问日志模块给静态资源加Last-Modified和If-Modified-Since做简单缓存或者用select模型替代线程池。每加一个特性都要回到项目初衷要让每个字节都可解释而不是堆复杂度。我现在又给caveman加了POST表单解析和简单的Cookie读取依然只有两百多行代码。5.2 做完caveman之后我的真实感受说点掏心窝的话做完这个项目我最明显的改变是再看框架文档时那些原本玄乎的概念突然都落到了实处。中间件不过是我在handle_connection里那个先处理、再传给下一个函数的模式路由不过是一个查表动作模板就是把字符串拼进HTML再发出去的封装。以后再碰到连接异常、响应超时我能先掰着指头数一遍字节流而不是对着报错瞎猜。我也强烈建议每个后端开发不论用什么语言都试着用标准库写一次HTTP服务器。几百行代码换回的是对整个Web技术栈再也骗不了你的底气。caveman的代码我到现在还在迭代每次往里面加一个小功能都像给石器时代的石斧加了一个防滑手柄工具原始但握在手里踏实。