大一那年我头一回正经用 Common Lisp 写 Web 应用，被一堆抽象层绕得想砸电脑。后来同事甩给我一句话：试试 Caveman，它就是那种“宁可你多写两行、也别让框架替你瞎猜”的设计。这个项目名字起得很诚实——Caveman，穴居人，原始、直接、不整花活。
这两年我用它做了三个内部工具、一个带登录和报表的小后台，加起来代码量比原来用别家框架写的同一个东西少了将近一半。这篇博文就把我完整踩过的路、趟过的坑、最后沉淀下来的用法和取舍一次性写清楚，适合那些想了解 Common Lisp 生态怎么写 Web、或者单纯厌倦了“启动一个项目先拉起两百个微服务”的朋友。
1. 让 Web 开发回归“原始”：Caveman 框架到底解决了什么
1.1 我的实际使用背景：当大工程跑不动的时候
先说场景。我常年维护一个数据清洗的平台，核心逻辑全在 Lisp 里，用户界面却一直是另一个团队用 Python 写的，两边靠消息队列传数据。每次改个字段名，就要同时改清洗脚本、改 API 文档、改前端联调，烦到骨头里。
后来需求变了：需要把几个清洗结果页做成内部查询工具，给运营自己点着看。就一两张表，一个搜索框，几个导出按钮。真的要为了这个再起一个 Python 服务、再引一套 ORM、再做一轮鉴权对接吗？我当时的想法很简单：既然核心逻辑在 Lisp，那 Web 这层也用 Lisp 写完拉倒，省掉跨语言通信的一切麻烦。
于是我开始翻 Common Lisp 的 Web 框架。最早看的是 Hunchentoot，老牌、稳，但写起来总觉得像在远古洞穴里徒手生火：一切都要手动，路由要自己组织、模板要自己拼、会话要自己存。不是说它不好，而是我的目标只是“快速把界面糊出来”，不想在基础设施上烧太多时间。
这时候 Caveman 进入了视野。它的定位和 Ruby 的 Sinatra、Python 的 Flask 差不多：微框架，给你最基本的 HTTP 路由和请求响应模型，剩下的你自己决定。但它的名字又很有迷惑性——caveman，听起来原始得很，实际上人家把现代 Web 框架里那套好用的东西都封装好了，只是封装得克制。
1.2 Caveman 的哲学：框架是脚手架，不是牢笼
我后来专门翻过它的源码和文档，越看越觉得这个项目的作者（Eitaro Fukamachi）在设计上非常清醒。
很多重量级框架的套路是提前假设你的应用长什么样：你必须用它的 ORM、必须用它的模板系统、必须按它的目录约定写控制器。这套东西对标准业务系统确实省心，但一旦你的需求不标准，框架的“好心”就会变成桎梏——你得上网搜“如何绕过 XXX 框架的限制”才能干成一件本该十分钟的事。
Caveman 反着来。它给你一个能跑的骨架，包含：
- 基础的目录结构（src、templates、static、db）
- 路由宏
defroute - 请求对象的封装
- 与 Clack（Common Lisp 的 WSGI/Rack 等价物）的无缝连接
但你完全可以不走它的目录约定，也可以不用它建议的模板引擎。框架层很薄，你的代码大部分就是纯粹的 Common Lisp，该怎样抽象就怎样抽象。这就是它名字里“caveman”的含义：穿上现代框架的外衣，但内核依然是最原始的、你能完全掌控的那一摊代码。
1.3 它的核心依赖链：Clack、Ningle 和模板之间的配合
提到 Caveman 就得知道它是站在谁肩膀上的，不然出了问题都不知道去哪查。
底层最核心的是 Clack，你可以把它理解成 Lisp 界的 Rack/WSGI。它负责接收 HTTP 请求、封装成统一的 Clack environment、再把你的响应转成标准格式发出去。Caveman 本身就是基于 Clack 的，所以你的应用本质上就是一个 Clack app，可以跑在任何支持 Clack 的服务器上，最常用的是 Hunchentoot 和 Wookie。
路由层 Caveman 内置借鉴了 ningle 的设计思路——一个更微型的路由库。defroute宏会自动匹配路径和请求方法，把 URL 参数打包好，让你像写普通 Lisp 函数一样写每个接口。这一点我很喜欢，因为路由表就是一张函数列表，没有反射、没有注解魔法，新人读代码时顺着函数名走就能看懂整个站。
模板层面 Caveman 默认建议用 Djula，一个 Django 模板语法的 Common Lisp 实现。如果你用过 Python 里的 Jinja2，上手 Djula 基本零学习成本。当然你也可以换成 Spinneret、Lisp 代码式的页面写法，但除非有特殊需求，我个人建议还是用 Djula，省心。
2. 从零搭建 Caveman 项目：5 分钟跑通 Hello World
2.1 环境准备：Roswell、Quicklisp 与 qlot
先别急着碰 Caveman，你的机器上得有一套能跑的 Common Lisp 环境。我现在的标配是 Roswell + Quicklisp，简单说：
- Roswell 管“如何装一个 Lisp 实现、如何跑脚本、如何管理多个版本的 SBCL”这些问题，类似 Node 世界里的 nvm；
- Quicklisp 管第三方库的下载与加载，类似 pip。
如果还没装 Roswell，macOS 上用 Homebrew 一条命令：
brew install roswell装完记得初始化：
ros setup这一步会下载最新稳定版的 SBCL 并配置好 Quicklisp。
这时候可以先验证一下：
ros run --eval '(format t "Hello from ~a~%" (lisp-implementation-type))'能看到 SBCL 的版本信息就说明环境OK了。
下一步是把 Caveman 拉进你的 Quicklisp 视野。大多数人会直接：
ros install fukamachi/caveman这句话的意思是从 GitHub 拉下来并部署到本地 Quicklisp 的 local-projects 目录里。以后你在 Lisp 里(ql:quickload :caveman2)就能加载。
不过我这里要说一个容易踩的细节：团队协作时，别只靠每个人的 Quicklisp 本地缓存跑项目。Quicklisp 的发行版更新很慢，今天你拉到的版本跟队友拉到的版本可能差了半年。建议用 qlot 锁版本，它通过项目里的 qlfile 固定依赖清单：
qlot install它会在项目本地生成一个隔离的 Quicklisp 环境，类似 Node 的 node_modules。后面所有加载命令都加上qlot exec：
qlot exec ros run这样团队几个人虽然系统里 Quicklisp 版本不同，但跑项目时统一使用 qlfile 锁住的版本，能省掉非常多“在我机器上是好的”这种问题。
2.2 生成项目骨架的命令与项目结构解读
Caveman 自带项目生成器，装完就直接能用：
ros run --load ~/.roswell/lisp/quicklisp/local-projects/caveman2/bin/caveman2-project.lisp -- --project myapp参数很重要：--project myapp是应用名。也支持：
caveman2-project --project myapp --author "Your Name" --description "My first Caveman app"执行完会在当前目录下生成 myapp 文件夹，完整结构是这样：
myapp/ ├── myapp.asd ├── README.markdown ├── src/ │ ├── config.lisp │ ├── myapp.lisp │ └── view.lisp ├── templates/ │ └── index.html ├── static/ │ ├── css/ │ └── js/ ├── db/ │ └── (数据库迁移脚本，默认没有) ├── test/ │ └── (测试占位文件) ├── qlfile └── .qlot/几个关键文件的作用：
myapp.asd是 ASDF 系统定义文件，相当于其他语言的 package.json + setup.py。它告诉 Lisp“这个应用由哪些源文件组成、依赖哪些库”。src/myapp.lisp是整个应用的主入口。你在这里定义路由、挂中间件、声明应用对象。src/config.lisp管配置，比如端口号、数据库连接串、debug 开关。src/view.lisp里通常定义模板变量渲染时需要的辅助函数。templates/是 Djula 模板目录，一个 HTML 文件对应一个页面。
生成的myapp.lisp里核心就这几行：
(defpackage myapp (:use :cl :caveman2 :myapp.config :myapp.view :myapp.db) (:export :*app*)) (in-package :myapp) (defclass <myapp> (<app>) ()) (defun myapp (env) (make-instance '<myapp> :appenv env)) (defroute "/" () (render #P"index.html" '()))别被这段吓到，实际上它只做了两件事：定义了一个 Caveman 应用类<myapp>，以及一个渲染首页模板的路由。它没有引入任何重量级概念，你看一眼就能明白全部流程。
2.3 启动开发服务器与热更新体验
在项目根目录下，带上 qlot 环境启动：
qlot exec ros run然后在 Lisp REPL 里加载项目：
(ql:quickload :myapp) (myapp:start :port 5000)浏览器打开http://localhost:5000，看到配置文件里的默认页面就成功了。
Caveman 的开发服务器自带热重载，代码改动后不需要手动重启进程。它默认监测源文件的修改时间，一旦发现变化就重新编译对应文件。但这有个前提：变量定义和函数重定义有时候会留“旧影子”。我在实践中发现，最稳的开发姿势是：
- 加载完成后先在 REPL 里
(myapp:stop)再(myapp:start :port 5000)一次； - 改完文件后，回到 REPL 按 Ctrl+C 打断，重新
(ql:quickload :myapp :verbose nil)再 start。
这样看似笨拙，但能避免热更新踩到“变量没重置、全局状态残留”的坑。狂热的 hack 环境固然酷，稳定输出才是生产力。
3. 路由、控制器与视图：构建一个可用网站主体
3.1 路由定义的基本概念与常用模式
Caveman 的路由宏是defroute，基本格式：
(defroute ("/users" :method :GET) () (render #P"users.html" '(:users (list-all-users))))括号里的第一参数是路径，路径后面可以用关键字参数指定方法，默认是:GET。支持的方法包括:GET、:POST、:PUT、:DELETE、:OPTIONS，几乎覆盖了 RESTful 接口的所有需求。
路径里可以带参数，用尖括号标出变量名：
(defroute ("/users/<id>" :method :GET) (&key id) (let ((user (find-user id))) (if user (render #P"user_detail.html" (list :user user)) (clack:response 404 (list (:content-type "text/plain")) (list "not found")))))注意接收参数的方式是&key，路由里写的<id>会自动变成名为id的 keyword 参数传进函数里。这个设计比有些框架把参数塞进字符串、然后你自己解析舒服太多。
defroute的返回值只需要是一个 Clack 兼容响应。Caveman 提供了render和json两个辅助函数，前者回页面，后者回 JSON：
(defroute "/api/health" () (json '(:status "ok" :time (get-universal-time))))这里我补一句很关键的心得：当你同时处理页面和 API 时，千万别在路由里塞太多业务逻辑。Caveman 不限制你，所以你必须自己约束。我的做法是每个路由只做三件事：拿参数、调业务函数、包响应。业务函数一律放到独立的模块里，这样路由层就是一张清晰的路由表。
3.2 从模板渲染页面到 JSON 接口
渲染页面用render函数：
(defroute "/search" (&key q page) (let ((results (search-data q :page (or page 1)))) (render #P"search.html" `(:query ,q :results ,results :page ,(or page 1)))))第二个参数是一个属性列表，键是模板里能用的变量名，值是传入的数据。模板里的写法长这样：
{% if query %} <p>搜索“{{ query }}”的结果：</p> {% endif %} <ul> {% for user in results %} <li>{{ user.name }} - {{ user.email }}</li> {% endfor %} </ul>Djula 的语法跟 Jinja2 是亲戚，熟悉其它模板引擎的读到这已经能上手了。
关于 JSON 接口，我要专门提醒一个初学容易懵的细节：Caveman 的json函数会把列表按 JSON 数组输出，但 Lisp 里一个(:a 1 :b 2)的属性列表并不会自动变成 JSON 对象——它会被解析成一个两元素的数组。正确打开方式是：
(defroute "/api/user/<id>" () (&key id) (if (find-user id) (json (object :id id :name "Alice" :role "admin")) (json `(:error ,(format nil "user ~a not found" id)))))object宏是 Caveman 提供用来构建 JSON 关联对象的关键工具，它内部接收 keyword 和值对，正确映射成键值结构。这个细节如果忽略了，前端拿到的数据永远是数组套数组，能被坑一晚上。
3.3 中间件与登录态处理的常见写法
凡是做 Web，永远绕不过登录态。Caveman 的中间件机制非常薄，你路过加一层函数就行，本质就是 Clack 的中间件体系。
我自己的做法是封装一个函数，叫with-auth，放在路由外层：
(defun wrap-auth (app) (lambda (env) (let ((session (clack:session env))) (if (session "user-id") (funcall app env) (clack:response 302 (list (:location "/login")) (list ""))))))然后把应用对象的中间件列表里挂上它：
(setf (getf (slot-value *app* 'caveman2:*middlewares*) :auth) 'wrap-auth)其实更常见的是在defclass里声明:middlewares关键字，但写进代码里展示是为了让你看到它不过是纯 Lisp 函数。别人过往用的“框架拦截器”、“AOP 切面”在这里通通还原成最普通的函数组合。
相当于你在进洞之前先把手电筒打开，洞还是那个洞，但你能看见前面的路了。
4. 接数据库、写增删改查：让 Caveman 应用真正落地
4.1 选择连接池还是直连：我的取舍
数据访问是 Web 项目绕不开的下半场。Caveman 本身不帮你决定用哪个数据库库，这一点和它的整体哲学一致。
Common Lisp 世界里数据库层的选择其实很集中：
- 用 PostgreSQL 的话，Postmodern 是事实标准，自带连接池、预处理语句、JSON 支持；
- 用 MySQL 的话可以用 cl-mysql，但我个人体验下来还是更推荐 MariaDB 配别的库，麻烦事少一些；
- 想写代码时完全不管 SQL，可以考虑 Mito，它是 Common Lisp 生态里最接近 ORM 的东西。
我在生产项目里最终选了 Postmodern 直连。原因很接地气：我们的数据模型就三张表，查来查去都是单表 or 简单 join，ORM 带来的建模提升顶多省五六十行代码，但引入的连接池配置、迁移工具、关系映射的调试成本可不止五六十行。而 Postmodern 的query宏本身就是一等公民，写起来也足够简洁：
(postmodern:with-connection (list "localhost" "dbname" "user" "password") (postmodern:query "select id, name, email from users where role = 'admin'"))返回结果是 alist 构成的列表，直接就能传给json序列化。中间几乎没有阻抗失配。
如果你更倾向于官方点的东西，Mito 也支持mito:select-by-sql、mito:create-table之类的辅助，但多极了一层抽象。我的观点是：业务逻辑超过十张关联表、或者有复杂的动态查询条件时，加 ORM 是划算的；否则，裸 SQL 反而是更“caveman”的智慧——少一层可能出错的转换，就少一片排查的战场。
4.2 路由与数据访问的典型问题
用 Postmodern 时最容易犯的错是忘了它依赖“动态绑定连接”。with-connection宏开了连接后，作用域内的query都走这个连接，一旦代码里出现异步处理、或者你在 REPL 里手动开并发线程去调查询，就会遇到连接未绑定的错误。
Caveman 是单线程模型还是多线程模型？答案是它会跑在 Clack 负责的服务器上，Hunchentoot 默认是多线程。这意味着两个请求可能在不同线程里并发执行，如果你的页面渲染里没有包一层with-connection，Postmodern 就找不到正确的连接上下文。
正确姿势是在路由内部显式开连接：
(defroute "/users" () (let ((users (postmodern:with-connection *db-spec* (postmodern:query "select * from users order by created_at desc")))) (render #P"users.html" (list :users users))))每次请求都新建连接看着不经济，但 Postmodern 底层连接池会复用空闲连接，实际开销可控。怕连接泄漏的话，你可以在中间件里包一层：
(defun wrap-db-connection (app) (lambda (env) (postmodern:with-connection *db-spec* (funcall app env))))挂到中间件里，就让全站每个请求默认有数据库连接。这个封装相当舒服，是一种把横切关注点集中处理的经典写法。
4.3 使用 Mito 这类 ORM（或不用）的经验
我在另一个项目里试过 Mito，简单说下对比感受。
Mito 适合那种“表结构跟着代码走”的场合。你定义一个类，它自动替你建表、动态加列，这在敏捷原型阶段确实爽：
(defclass user () ((name :col-type :varchar :initarg :name) (email :col-type :varchar :unique t :initarg :email)) (:metaclass mito:dao-table-mixin)) (mito:create-table 'user) (mito:insert-dao (make-instance 'user :name "Alice" :email "alice@example.com")) (mito:select-dao 'user :where (:= :email "alice@example.com"))看起来很美，但是有几个现实问题：
- 每次类结构变更，Mito 默认的 migrate 不一定能平滑处理已有的独立索引和外键。
- 查询大量数据时
select-dao返回的是对象列表，每条都要做 slot 到列的映射，性能比裸 SQL 差一截。 - 你仍然绕不开 SQL，遇到复杂组报表时还是要
mito:select-by-sql。
所以我的最终经验是：Mito 适合模型简单、开发速度优先的 demo 或内部工具；一旦涉及线上报表、复杂索引或大批量导入导出，直接用 Postmodern 写 SQL 反而更可靠。这句话听着像废话，但真正在项目里两边都趟过的朋友，会明白我的意思。
5. 部署体系中的实际问题：端口、静态资源与日志
5.1 用 Clack 接前端服务器：常见反代配置
Caveman 应用本身通过 Clack 启动一个 HTTP 服务，监听某个端口。生产环境我一般不让它直接面对公网，而是用 Nginx 做反向代理。
Nginx 配置里核心段落就这一段：
server { listen 80; server_name example.com; location / { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } location /static/ { alias /var/www/myapp/static/; expires 7d; } }注意我把/static/单独交给 Nginx 直接服务了，没走 Clack。这是性能上很划算的分离——静态文件的 IO 和压缩让 Nginx 来干，Lisp 进程只负责动态逻辑。
如果你的 Caveman 应用里有 WebSocket 需求，Clack 上可以用 related 库，Nginx 也要配proxy_set_header Upgrade。不过说实话，我自己目前还没在 Caveman 里碰过 WebSocket，真有这需求我大概率会单独起个小服务。
5.2 静态资源和上传文件的处理
开发阶段 Caveman 会直接托管 static 目录，方便你快速切页面调试。默认路径是项目根目录下的static/。
上线后一旦交给 Nginx，Caveman 这边的static路由最好关掉，避免功能重复且暴露内部路径。做法是忽略它，因为域名层面已经把/static/指到 Nginx 了。
上传文件的处理稍微不一样。表单 POST 到你的路由，Clack 会把文件内容放到env里。你可以这样拿：
(defroute ("/upload" :method :POST) (&key file) (when file (let ((path (merge-pathnames (file-basename file) #p"/var/www/uploads/"))) (clack:file-upload-to-path file path) (format NIL "saved to ~a" path))))这里面有个容易被忽略的变量：file-basename需要自己写或者引入一个库，因为浏览器给的文件名可能带../../这种危险路径，直接拼路径是有风险的。我用的工具库是ppath，它可以安全地取 basename：
(ppath:basename (getf file :filename))保存路径务必保证在允许的目录内。这种安全意识不是框架给的，是你自己的穴居人本能——住山洞时也要知道火堆放哪，别把洞烧了。
5.3 日志分级与错误兜底
Caveman 的日志走上层 Clack 的体系。默认情况下它会输出每个请求的方法、路径和状态码，已经能满足 90% 的调试需求。生产环境我想记录更多信息，包括耗时、查询参、登录用户，所以我封装了一个中间件：
(defun wrap-logger (app) (lambda (env) (let ((start (get-internal-real-time))) (let ((resp (funcall app env))) (format t "~&[~a] ~a ~a ~a ms~%" (get-universal-time) (getf env :request-method) (getf env :request-uri) (/ (- (get-internal-real-time) start) internal-time-units-per-second 1000.0)) resp))))错误兜底方面，Caveman 默认 500 错误页面是简陋的纯文本，但我习惯加一个统一错误处理器，捕获未处理的异常并渲染一个友好的错误页。做法同样是一个中间件：
(defun wrap-error-handler (app) (lambda (env) (handler-case (funcall app env) (error (e) (format *error-output* "~&ERROR: ~a~%" e) (clack:response 500 (list (:content-type "text/html")) (list "<h1>Something went wrong</h1>"))))))注册中间件的顺序有讲究，外层包内层。我按这个顺序挂：
(setf (getf (slot-value *app* 'caveman2:*middlewares*) :auth) 'wrap-auth (getf (slot-value *app* 'caveman2:*middlewares*) :db) 'wrap-db-connection ...)本质上中间件就是洋葱模型。你包得越外，越先执行，也越接近全局兜底。这套机制分层很清楚，出问题时在 REPL 里一眼能看到是哪一层炸的。
6. 我踩过的坑与最终心得
6.1 Quicklisp 版本和依赖冲突的再现
这是每个 Common Lisp Web 项目新手都会撞上的头号公敌。
Caveman 依赖 Clack，Clack 又依赖一堆底层库，版本一变，行为就可能飘。最经典的一次：我本机 Quicklisp 发行版正常，但同事的机器上加载项目时提示There is no package named "CLACK"，排查半天发现是 Quicklisp 还没把最新版同步过去，他本地 local-projects 里缺 Clack。
从此我立了一条规矩：项目必须带 qlfile 并跑qlot install。qlot 就是这个生态里的依赖锁。不要靠全局 Quicklisp 拼运气，团队协作时尤其如此。如果你发现 qlot 装完后启动还是报缺库，检查一下是否忘了用qlot exec前缀来启动 Lisp。这是最不起眼也最烦人的坑。
6.2 模板引擎选 Djula，记得缓存失效的坑
Djula 很稳定，但它的模板编译缓存让我绕了不少弯。
默认情况下，模板会被编译成函数缓存起来，这在生产环境是好事——性能好。但开发环境里，你改了模板文件，缓存不失效，刷新页面看到的还是旧内容。Caveman 在 debug 模式下会自动清缓存，但只要你错误配置开启了缓存，调试效率能低到你怀疑人生。
我的做法是写一个单独的函数：
(defun reload-templates () (djula:reset-template-cache))开发时每改一次模板就手动在 REPL 里执行它。上线前改为正式缓存，性能最大化。
6.3 两条建议：适合场景与不该用的场景
写了这么久，按理来说该给节总结了。我不说套话，就分享两条自己的判断。
第一条，Caveman 特别适合这些场景：
- 你已经在用 Common Lisp 写业务逻辑，只想加一层 Web 壳；
- 内部工具、管理后台、API 转发服务，需求不大但迭代频繁；
- 你受不了重型框架那一堆概念约束，想完全掌控代码组织方式。
第二条，它不太适合的场景是：
- 前端一套复杂状态管理加后端十几个微服务的大型全栈应用——那是另一个领域的事；
- 团队里没有一个会 Common Lisp 的人，你只是自己试水——学习成本会抵消框架带来的效率；
- 你的应用需要大量 WebSocket 长连接、服务器推送——Clack 生态能做，但你会发现自己一直在跟底层细节搏斗，不如用更成熟的方案。
我自己实际用下来的体验是：Caveman 是那种越想越觉得设计得好的框架。它不逼你学一堆额外抽象，但你把该有的东西自己写一遍之后，对 Web 的底层理解反而更深了。就像穴居人，不依赖现代电气，但真正懂了火怎么生、怎么控火,这比只会按开关的人可靠多了。
如果你也打算拿 Common Lisp 写点 Web 工具，最后再分享一个小技巧：先用caveman2-project生成最简骨架，然后把你平时最常写的登录、数据库连接、JSON 封装这三个中间件提前加上，后面所有项目都以这个模板为起点。我这三个内部工具能这么快做完，一半功劳是模板沉淀，另一半才轮得到框架本身。
