看到“caveman”这个词，你可能第一时间想到的是游戏里那个穿着兽皮、扛着骨棒、只会嗷嗷叫的原始人。但在Common Lisp开发者的圈子里，caveman是另一回事——它是一个轻量Web框架的名字，全称就叫“Caveman”。我第一次听到这个名字时也愣了一下，心想这开发者是得多自嘲，才把自己做的框架起成“穴居人”。后来用上才发现，这名字其实很贴切：它就是把Web开发里最基础、最原始的那些东西帮你铺好，不搞花活，不绑架你的设计，让你能从零快速把一个HTTP服务跑起来，然后再按自己的想法随意改造。
这篇文章要聊的，就是这个叫Caveman的框架。它能做什么、适合谁、怎么从零搭起来跑通一个真正的服务，以及我在实际使用中踩过的一些坑。如果你对Common Lisp感兴趣，想用它写点Web接口或内部工具，但又被一堆复杂组件劝退，那Caveman是一个特别好的切入点。就算你之前没碰过Lisp，只要懂一点编程基础，今天跟我走一遍，也能把一个能跑的Web服务挂起来。
1. Caveman是什么：把“极简”刻进名字里的Lisp Web框架
1.1 Lisp世界的Web开发，为什么总让人感觉轮子要自己造
Common Lisp是一个很老的语言，老到你翻很多教程，感觉它跟现代Web开发完全不在一个时代。但这其实是错觉。它不仅有能跑生产环境的HTTP服务器，比如Hunchentoot，还有一层叫做Clack的抽象接口，你可以把它理解为Lisp界的Rack或WSGI，用来统一不同Web服务器之间的差异。而Caveman，就是构建在Clack之上的一层更上层的工具。
如果没有Caveman这类框架，你在Common Lisp里写一个带路由的HTTP服务，通常要做的事是：自己接收HTTP请求、自己解析URL路径、自己判断该调用哪个函数、自己拼响应头、自己处理参数编码。这些事说起来都不难，但每一个都极其琐碎，写多了你会觉得整个项目大部分代码都在做“搬运”，真正的业务逻辑反而占不到多少。
Caveman做的就是把这些琐碎的部分收拢到一个defroute宏里。你只需要声明“这个路径对应哪个函数”，剩下的请求解析、路由匹配、参数提取，框架帮你处理掉了。这种感觉跟用Python的Flask很像：框架不逼你用什么数据库、不逼你用什么模板引擎、不逼你把项目切成几个固定模块，而是给你一个足够简单的基础，剩下的你自己看着办。
拿生活打个比方：Hunchentoot相当于一块毛坯地，你能在上面盖任何建筑，但水电、道路、排污都得自己从零拉；Clack相当于统一了“这块地该怎么接市政管网”的标准；Caveman则是直接给你交付了一套已经通好水电、隔好房间的小户型，虽然装修风格得你自己定，但拎包入住的基本条件是齐了。
1.2 Caveman到底解决了什么，又适合谁用
我最早接触Caveman，是因为要写一个内部命令行工具的Web控制台。需求很简单：提供几个页面展示状态，提供几个JSON接口让前端调用，用户量最多十几个人，不需要做复杂的权限系统，也不需要扛住高并发。如果用那些大而全的Web框架，光配置和约定就能耗掉半天；如果直接裸写Hunchentoot，路由这块又得手搓。
Caveman正好卡在中间。它解决了“从零搭建一个Web服务的重复劳动”这个问题：项目骨架可以一键生成，路由写法足够直观，中间件机制沿用Clack生态，跟Common Lisp世界里的其他库能顺畅拼接。它不解决的是“你的业务该怎么设计”“你的数据层该怎么架构”“你的前端该怎么组织”，这些问题它统统丢回给你，保持了一个微型框架该有的克制。
所以它的适用场景非常明确：中小型内部系统、微服务中的某个独立接口、快速原型验证、教学演示、工具类Web页面。对我来说，它的核心价值就一句话——让Common Lisp写Web服务变得不再像是在做底层网络编程，而像是在写普通业务逻辑。
反过来说，如果你的目标是做一个千万级用户的大平台，或者你希望靠框架自带的一整套全家桶快速堆功能，那Caveman不适合你。它不提供开箱即用的用户体系、后台管理、ORM全套集成，你得自己组装。这不是框架的缺陷，而是它的定位。选型最怕的不是选错，是用在错误的场景里然后回来骂工具不行。
2. 从零到一：环境准备和项目初始化
2.1 先把Common Lisp环境跑起来
在开始碰Caveman之前，你需要一个能跑Common Lisp的环境。我用的是一路被验证过无数次的组合：SBCL作为实现，Quicklisp作为依赖管理，Emacs加SLIME作为开发环境。但如果你不喜欢Emacs，直接终端里写代码也没问题，SBCL启动之后就是交互式环境。
安装顺序是这样的：先装SBCL，通常Linux发行版自带包管理直接就能装，macOS用Homebrew也很方便。装完之后，再装Quicklisp，它是一个类似npm或pip的库管理器。装上之后在REPL里执行(ql:quickload :caveman)，它会自动把Caveman和它依赖的一堆库全部拉下来。第一次拉取可能需要一点时间，因为依赖树还挺多的，但装完之后一般就稳定了。
这里有个细节值得提一下：如果你因为网络原因在拉Quicklisp的时候很慢，可以先设置好国内可用的Quicklisp镜像再执行加载。这一步不属于Caveman本身，但不解决的话你可能在环境阶段就卡住。装好之后，建议先跑一个最简单的HTTP服务验证环境是通的，再进下一步，否则后面出问题你很难分清是框架问题还是环境问题。
2.2 用Caveman自带命令生成项目骨架
环境准备好之后，生成项目特别简单。在REPL里执行：
(ql:quickload :caveman) (caveman:generate-project "myapp")执行完以后，当前目录下会多出一个myapp文件夹，里面已经帮你铺好了能跑的最小骨架。我印象里生成出来的结构大概长这样：
myapp/ ├── myapp.asd ├── src/ │ ├── app.lisp │ ├── config.lisp │ └── controllers/ │ └── myapp.lisp ├── static/ └── templates/看到这个目录，别紧张。myapp.asd是Common Lisp的系统定义文件，相当于Lisp世界的“工程文件”，你要让编译器知道这个项目包含哪些源码文件、依赖哪些外部库，都靠它。src/app.lisp是应用的入口，负责组装中间件、定义顶层路由。src/controllers/下面放具体的路由处理器，一个模块一个文件，按自己的习惯切就行。static/放静态文件，templates/放模板。
我个人不太喜欢把什么都堆在.asd文件里，所以生成骨架之后，第一件事就是打开myapp.asd，把依赖那一项认真过一遍。你要用JSON就用添加jonathan这类库，要连数据库就加cl-dbi或mito，一开始就声明清楚，后面少很多“这个函数找不到”的痛苦。
2.3 启动起来，跑通第一个请求
项目生成好了，怎么跑起来呢？最直接的方法是在REPL里加载系统，然后调Caveman生成的启动入口：
(ql:quickload :myapp) (myapp:start :port 5000)如果你用的是新版Caveman，启动函数名可能稍有变化，但入口基本都是start。跑起来之后，你用浏览器打开http://localhost:5000/，如果看到一个欢迎页或者一串简单的文本，说明整个链路已经通了。
第一次跑通时，我不建议急着改代码，先把“生成项目、启动服务、浏览器访问”这条链路走通，你就已经迈过最难的坎了。之后改路由、加业务，都是在已有的骨架上填充，不会再有无从下手的感觉。
3. 路由、控制器和参数：日常开发最常用的一块
3.1 defroute宏：Caveman的灵魂
Caveman最核心、也是使用频率最高的东西，就是defroute这个宏。它负责把URL路径绑定到一个Lisp函数上。我举个最简单的例子，假设我想让根路径返回一段欢迎文字：
(defroute "/" () "Welcome to Caveman")这段代码读起来很有意思：声明路径是/，参数列表为空，函数体直接返回一个字符串。这个字符串就是HTTP响应体。Caveman会自动帮你把它包装成合法的HTTP响应返回给浏览器。这种“返回值即响应”的设计，让写路由变成了一件特别符合直觉的事。
如果你想在路径里带动态参数，比如/hello/:name，Caveman的写法是：
(defroute "/hello/:name" (&optional name) (format nil "Hello, ~A" name))这里:name是路径参数，它会自动绑定到函数后面的name变量上。当你访问/hello/lisp时，返回的就是Hello, lisp。这种写法看起来不起眼，但省掉了我以前在Hunchentoot里手动解析URI的麻烦。
有一点得提醒你：Caveman的defroute在不同版本里的细节略有差异，有的版本路径参数绑定方式、HTTP方法声明方式不太一样。我看到过不少人在网上抄了一段代码在自己的版本上跑不通，最后发现是版本差异。我的建议是，先看生成项目里自带的示例路由，那是最贴合你当前版本的参考。
3.2 参数获取：查询参数、表单和请求头怎么办
路径参数解决的是URL里带参数的情况。但实际开发中，你更多时候要处理的是查询参数，比如/search?q=lisp里的q，或者表单POST提交上来的数据。Caveman本身提供了多种参数获取途径，但我最常用的是直接借助Clack生态里的lack.request库来解析请求对象。
原理是这样的：Caveman底层接到的是一个Clack环境对象（通常称为env），这个对象里包含了HTTP请求的所有信息。你可以把它转成一个Lack请求对象，然后从这个请求对象上拿到查询参数、表单数据、请求头、Cookies等信息。这个思路不依赖Caveman的某个具体版本，因为lack.request是更底层、更稳定的接口。
我这里想多说一句经验：很多人在用微型框架时总想找到一个“框架内置的万能参数获取函数”，但实际不如直接理解框架底层的请求对象。你只要搞明白“Caveman接收的是Clack环境，所有请求信息都在里面”，那么不管框架版本怎么变，你都能通过Clack那一层拿到你想要的东西。
3.3 响应也能是复杂结构：状态码、自定义头和JSON
前面我写的路由都是直接返回字符串，这在返回一个HTML片段时很够用。但如果你要写的是API接口，通常要设置状态码、响应头，然后返回JSON。Caveman是基于Clack的，所以它支持Clack定义的标准响应格式：一个列表，里面包含状态码、响应头、响应体三部分。
举个例子，我想写一个返回JSON的接口，就可以这样：
(defroute "/api/ping" () (list 200 (list :content-type "application/json") "{\"status\":\"ok\"}"))这个写法看起来原始，但非常透明：200是状态码，中间那个列表是HTTP头，最后那个字符串是响应体。你完全掌控返回给客户端的内容，不会出现“框架自作主张把数据包了一层”的情况。
如果你嫌手写JSON字符串太丑，可以配合jonathan库来生成JSON。先(ql:quickload :jonathan)，然后在路由里把Lisp的列表或哈希表传给jonathan:to-json，它会帮你序列化成JSON字符串。这样代码可读性会好很多，也少了很多拼接字符串时容易犯的引号错误。
有一种常见的需求是重定向，比如用户访问旧地址时要跳到新地址。基于上面的响应格式，你可以通过返回301状态码加Location响应头来实现。理解了这个标准格式之后，你会发现Caveman其实没有太多黑魔法，它就是把HTTP协议的基本概念用Lisp的列表形式直接暴露给你。
3.4 静态资源和模板渲染，怎么选
做Web页面总要处理静态文件，比如CSS、JavaScript、图片。Caveman生成的项目里有个static/目录，你在开发时把静态文件丢进去就能访问。这个功能其实是由Clack的静态文件中间件提供的，不是Caveman自己处理的，所以你在使用时不用配置太多，路径匹配和浏览器缓存这些事，中间件帮你挡掉了一部分。
模板方面，Caveman没有一个强绑定的模板引擎，你可选的方案很多。我看到很多项目用的是Djula，一个语法上跟Django模板很像的Lisp模板库；也有用CL-EMB的；还有人像我一样，干脆不用模板，直接用Lisp的format函数拼HTML字符串。对于页面很少、结构很简单的工具型应用，拼字符串反而更直接。
这里我的建议是：别一上来就引入模板引擎，除非你的页面里确实有大量重复的HTML结构需要抽出来。我见过不少项目，页面总共就两三个，模板引擎的引入却让项目结构复杂了一个量级。先问自己一个问题：我是在写大量需要动态渲染的页面，还是只是偶尔输出一小段动态内容？如果是后者，直接拼字符串，改起来还更直观。
4. 拼接数据层：数据库、会话和中间件
4.1 数据存储选型：直接用SQL，还是上ORM
Web服务十有八九要存数据。Caveman没有内建的数据库层，好处是你完全自由选择；坏处是新手容易迷茫。我在Lisp这边的常见路线主要有三条：第一条是用cl-dbi直接写SQL；第二条是用mito这个ORM，在Lisp里以面向对象的方式操作表；第三条更简单，对于小型工具，直接用内存数据结构如哈希表存数据，服务重启就丢，但对某些内部工具完全够用。
这三条路线的取舍很有意思。直接写SQL最透明，你想怎么优化怎么来，但表结构变化时要手写迁移；用ORM省事，类和表一一对应，但遇到复杂查询时会感觉被工具限制；用内存哈希表最简单，但完全不考虑数据持久化。我个人的倾向是，项目只要不是特别复杂，优先用cl-dbi加少量SQL，把SQL都集中在一个文件里管理。等到你发现这个项目的表关系复杂到SQL文件越来越难维护，再上ORM也不迟。
4.2 在一个微型框架里谈持久化，别把架构搞复杂
我见过很多人想做“微服务”，结果每个服务都用上了数据库、缓存、消息队列，最后维护成本比单体还高。Caveman这类框架本身追求的是轻，你在数据层也别急着堆东西。很多场景下，一个进程内维护的哈希表加一个定期写磁盘的周期任务，就能解决大部分内部工具的需求。
如果你确实需要真数据库，比如PostgreSQL或SQLite，使用上也简单。你可以在启动时建立连接，把连接对象存到一个全局变量或参数里，在每个路由函数中调用。这里有一个实践细节：在Lisp多线程环境下，数据库连接不能随便跨线程共享。Hunchentoot处理请求时可能是在不同线程里跑的，所以在路由里直接使用一个全局连接会有隐患。我的笨办法是给每个请求动态绑定一个连接，或者用一个连接池库。虽然听起来增加了一点复杂度，但总比并发一上来就遇到“连接已被占用”的诡异报错要好。
4.3 会话、Cookie和中间件到底怎么一回事
HTTP协议本身是无状态的，但很多应用需要记住“当前用户是谁”。这事在Caveman里通常交给Clack中间件来干，比如会话中间件会在客户端种一个Cookie，然后把会话数据存在服务器端。你只需要在组装应用时把中间件插进去，请求对象里就会带上会话相关的能力。
中间件这个概念，你可以理解为洋葱皮。请求进来时，先经过一层层中间件，最后才到你的路由函数；响应出去时，又原路反向经过每一层。静态文件处理、会话管理、日志记录、错误捕获，这些通用能力都能用中间件实现。Caveman允许你用lack:builder把这些中间件和你的应用组合在一起，组合顺序有讲究：越外层越先处理请求。
理解中间件顺序对排查问题很有帮助。比如你发现请求没到路由就被拦截了，很可能就是某个中间件的路径匹配范围太宽。我在刚开始用Clack时也经常犯这种错，后来养成一个习惯：每加一个中间件，就先写个最简单的路由打出来看看请求是否能正常穿透，再继续加下一个。
4.4 用内存做一个最简单的“计数器接口”示例
说了这么多理论，不如直接写一个能跑的小示例。假设我要做一个非常原始的访问计数器接口，每次有人访问/api/hit，数字就加一，然后返回当前次数：
(defparameter *hits* 0) (defroute "/api/hit" () (incf *hits*) (format nil "{\"count\":~D}" *hits*))这段代码在Caveman里可以直接运行。它展示了几个点：defparameter定义一个全局变量；incf是Lisp的加法赋值；返回字符串作为响应体。这个示例虽然简单，但它是很多内部工具的雏形，比如一个探活接口、一个埋点计数器、一个状态查看页。从这个雏形往外扩展，你可以加上持久化、加上并发锁、加上认证，框架不会拦着你。
这里必须提一个并发注意点：*hits*这个全局变量在多线程环境下递增不是原子操作，真实服务同时被多人访问时可能丢计数。如果想严谨一点，用bt:make-lock加个锁。我之所以提这个，是想提醒你：轻量框架把很多基础设施问题还给了你，运行时是否并发安全是你自己得留心的。
5. 部署与运行：本地调试和生产环境切换
5.1 本地开发时的启动方式
本地开发时，我最常用的方式是直接在REPL里加载项目，然后启动服务，这个过程中保留REPL交互能力。这样做的最大好处是：你可以一边开着服务，一边在REPL里改函数定义。改完某个路由函数后，甚至不需要重启服务，下一次请求进来就会自动执行新代码。这个体验对做Web开发来说非常爽，也是我在其他语言里很难找到的乐趣。
在启动时，有几个参数值得关注。端口是必设的，:port 5000这种；如果你的机器上5000端口已经被什么程序占了，就换一个。另外你可能需要设置绑定的地址，默认是localhost，这意味着只能本机访问。如果你希望局域网内其他机器也能访问，需要绑定0.0.0.0，但这样做时要自己注意安全性，别把什么敏感接口暴露到内网。
5.2 生产环境的常见部署姿势
生产环境部署Caveman，最常见的方式是用Supervisor这类进程守护工具拉起一个SBCL进程，在SBCL里加载系统、启动服务，然后由Supervisor负责监控和重启。这种方式的好处是简单直接，没有引入太多额外系统组件，崩溃了能被自动拉起。
还有一种方式是用Docker，把SBCL和项目代码打包进镜像。但这里有个细节：Common Lisp项目启动时通常要加载Quicklisp库，如果你的镜像里没有缓存这些依赖，每次启动都会重新拉取，速度慢不说，还可能因为外部依赖变动导致构建不稳定。我建议在构建镜像时把依赖提前加载并保存好，让运行时的启动过程尽量“离线完成”。
生产环境除了进程本身，通常还需要反向代理。我用得比较多的是Nginx：对外暴露80或443端口，把请求转发给后面运行在某个内网端口的Caveman进程。反向代理还能顺带处理HTTPS证书、静态资源缓存、请求体大小限制这些事，让Lisp进程只管业务逻辑。
5.3 常见问题排查速查表
把我在实际使用中遇到的问题整理一下，做成一个排查表，希望能帮你少走弯路：
| 症状 | 常见原因 | 处理思路 |
|---|---|---|
| 启动时报端口被占用 | 上一个服务进程没退出 | 找到占用端口的进程并结束它，或者换一个端口启动 |
| 访问路由返回404 | 路径写错，或路由没加载 | 检查URL是否和defroute完全一致，检查.asd是否包含了对应源码文件 |
| 修改代码后行为没变 | REPL里加载的旧函数覆盖了新代码 | 重新编译对应文件或重启服务，确保新定义生效 |
| 返回中文乱码 | HTTP头没有指定UTF-8编码 | 在响应头里加:content-type "text/html; charset=utf-8" |
| 并发请求时数据异常 | 全局变量共享未加锁 | 用锁或线程绑定数据来保护共享状态 |
| 依赖加载报错“找不到函数” | 对应库没有被加载 | 检查系统定义文件里的依赖声明，执行ql:quickload确认加载 |
这个表里的问题我基本都踩过。最让我印象深刻的是一次中文乱码，客户端怎么设置编码都不对，最后发现是响应头里根本没告诉浏览器用UTF-8解析。你看，很多问题其实不是框架难，而是对HTTP协议细节不够敏感。
5.4 一个容易被忽略的坑：代码热加载的边界
刚才我夸了REPL热加载的体验，但也要说它的另一面：它并不总是安全的。如果你改动了一个被很多路由依赖的全局数据结构，或者改动了系统定义文件里源码路径，热加载很容易让你陷入“改了一部分、没生效一部分”的混乱状态。
我的习惯是：小改动、单函数修改，放心热加载；涉及项目结构、依赖变更、启动配置的改动，老老实实重启服务。这个边界如果你把握不好，可能浪费大量时间在“为什么我改了没反应”的反复试错上。经验多了之后，你会找到自己顺手的节奏，但刚开始别迷信热加载。
6. 个人使用经验和扩展想法
6.1 我为什么在项目里保留Caveman
这几年我用Caveman写了几个内部工具和一个原型系统，每一次的选择都不是因为它有多炫酷，而是因为它帮我省掉了“从零搭一个HTTP服务”的繁琐过程。Common Lisp本身已经够独特了，如果还得为每次Web服务手动拼路由，我真的会放弃用它做Web开发。
Caveman让我在Lisp里写Web服务时，能保持Lisp的思维方式：函数就是函数，返回值就是响应，数据就是数据。它没有把一堆概念强行塞给你。所以你写的代码，基本一眼就能看懂。这种透明性，这种没有魔法包裹的感觉，在今天的Web框架里其实已经很难得了。
当然它也有明显的短板：社区小、示例少、文档更新不够及时。这也是为什么我写这篇文章时会反复提醒你“以你当前版本的示例代码为准”。但我认为，对一个想要认真用Common Lisp做点事的人来说，这个短板完全可以接受，因为你遇到的很多问题，稍微看一眼源码就能解决。
6.2 基于Caveman还能做什么扩展
如果你已经跑通了基础，还可以往下玩很多东西。比如给接口补上OpenAPI描述文档，这样前端同事可以通过Swagger UI直接看到接口参数和数据格式；比如接入Prometheus的指标接口统计请求量，让运维能监控；再比如把Caveman应用嵌到一个更大的Lisp系统里，让同一个进程既跑业务常驻任务，又对外提供HTTP接口。这些扩展方式都很适合Caveman的“微型”定位，它不会拦着你拼装任何东西。
最后说一个我自己的使用心得：刚接触Caveman时，我在它的defroute宏上卡了很久，总觉得要理解宏展开才能开始写。后来我想通了，先用生成的项目跑起来，改了两次路由，再回头看它的源码和文档，一切都通了。所以如果你现在正准备上手，我的建议是别想太多，先把默认项目跑起来，把第一个接口改掉，你就已经走在前面了。
