提到 Caveman很多人第一反应是拿木棒追猛犸象的穴居人。我第一次在 Common Lisp 社区扫到这个项目名也以为是某个玩笑性质的实验品。直到真把一个内部订单查询服务从 Flask 迁到它上面前前后后跑了两个多星期才对它改观Caveman 是一个构建在 Clack 之上的微型 Web 框架负责把 HTTP 请求路由到 Common Lisp 函数顺手提供模板渲染、会话、静态文件这些 Web 应用的基础设施但又刻意不把全家桶塞给你。这篇文章我从实际迁移和线上使用的角度出发把 Caveman 的路由机制、中间件分层、数据库配套、部署方式和常见坑都梳理一遍。如果你是好奇 Lisp 生态有多能打的技术选型党或者真打算在 Common Lisp 里写点 Web 服务这篇应该能帮你少走弯路。1. 先弄清 Caveman 到底做了什么、没做什么1.1 一个框架出现在 Lisp 世界里的逻辑Common Lisp 不是没有 Web 框架问题是选择太极端。一端是裸 Clack本质上就是一个把不同 HTTP Server 包了一层统一接口的抽象层你拿到的是请求进去、响应出来的简单模型。另一端是类似 Weblocks 这样野心极大、想包办一切的框架结果文档复杂、社区冷清上手成本高到劝退。Caveman 站的位置恰好是中间偏左它默认帮你把项目骨架搭好把路由、模板、静态文件、中间件配好但数据库、表单验证、用户体系这些都留给你自己组装。对这种设计的第一反应可能是那还不如直接用 Flsk。但你要注意它的定位不是 Python 那种把东西都备齐的微观管理型框架而更像是 Sinatra 式的薄路由层。它解决的核心痛点是你不想每次都手写 HTTP 解析、路径匹配、请求分发这一套同时又不想被一个庞然大物锁死。1.2 为什么不直接用裸 Clack我在接触 Caveman 之前一度用裸 Clack 写了几个小服务。请求处理函数本身就是一个接收环境变量的函数(lambda (env) (let ((uri (getf env :request-uri))) (if (string uri /health) (200 (:content-type text/plain) (ok)) (404 () (not found)))))三个路由以内这样写没问题路由超过十个以后你就得自己实现一个 if-else 路由分发器。更麻烦的是参数解析、Cookie 解析、静态文件服务这些边角料全要自己拼。Caveman 干的正是把这些重复劳动收编成一个声明式的defroute宏让路由表、参数捕获、HTTP 方法匹配都变成明显的代码块。1.3 快速生成骨架一行命令起项目Caveman 官方生态里有个配套工具叫caveman doctor如果你使用 Caveman2 对应的项目生成器也会叫caveman2-project之类。它做的事情非常直观交互式问你项目名、模板引擎、要不要生成测试目录然后一次性把整个 Common Lisp 项目骨架拉起来。我实际操作时的感受是这个骨架目录的整洁程度超出我对 Lisp 项目的预期包管理Quicklisp、.asd系统定义、src/源代码、static/资源目录、t/测试目录都有约定俗成的位置。你不需要像在裸 Lisp 工程里那样自己摆弄路径设置这让第一次从其他语言转过来的开发者非常舒服。2. 路由机制拆解从 URL 到函数名再到响应2.1 defroute 宏与参数捕获Caveman 第一代提供的路由方式是宏定义。我最早接触的写法是这样的(defroute (/users/:id :method :get) () (let ((id (param id))) (format nil User ~a id)))注意几个细节:id这种冒号开头的是路径参数占位符括号内默认参数列表空着在处理函数中通过(param id)取路径参数。这个参数名是字符串而不是关键字这算是 Caveman 的一个小脾气你在写 helper 的时候容易踩。Caveman2 换了一套更激进的方案不用宏而是通过扫描源码里的注释来生成路由。比如你在源码中写;; route GET /users/:id (defun show-user () (let ((id (param id))) (format nil User ~a id)))构建时它会扫描route注释自动把GET /users/:id绑定到show-user这个函数上。这种注释即路由的方案一开始看着很怪用久了反而觉得清爽函数本身就是一个普通 Lisp 函数你可以直接在 REPL 里调用它做单元测试不需要通过 HTTP 请求。2.2 参数捕获的小陷阱路径参数只是一个方面。Query String 参数、POST 表单字段、JSON Body 里的字段在不同场景下的读取方式各不相同。我用的时候统一走param这个入口对象它既读路径参数也读query string和表单字段。但注意如果你的接口接收的是 JSON Bodyparam是读不到东西的那要先从body中解析 JSON再自己取出对应字段。我刚开始迁移一个上传接口时就因为在param里取不到 JSON 字段折腾了一晚上。后来调整做法在路由函数开头统一判断 Content-Type是application/json就调用 JSON 解码器把结果作为 plist 存进一个动态变量里后续所有取值都走这个变量彻底避开格式分裂。2.3 路由前缀和嵌套资源的手写方案用一个微框架写 RESTful 资源最常遇到的是 : 每个/api/users/...都要带着api/users前缀。在 Rails 里这叫 namespaceCaveman 里没有内置。我自己的习惯是写一个宏来拼路径前缀(defmacro api-route (path rest body) (defroute ,(concatenate string /api/users path) () ,body))然后把/api/users当作一组资源的公共前缀。为什么不直接在路由里每次手写因为后面改版本号、加前缀的时候全局搜索替换太容易漏。用宏生成路由有一个附加收益当你把路由定义集中在一个文件里时整个资源表的地图效果非常清楚谁都会觉得维护成本低。2.4 中间件和路由的执行顺序请求进入 Caveman 应用后其实有一条固定的链路HTTP Server 收到请求交给 Clack 的中间件栈中间件栈处理完再进入 Caveman 的路由分发层最后调用你定义的处理函数。响应返回时反向再走一遍中间件栈。这个顺序很重要因为它决定了你在哪里插 Cookie 解析、在哪里做登录鉴权。比如你要做一个只有登录用户才能访问/admin/*的拦截器纯在 Caveman 路由层做会很别扭因为你要在每个 admin 路由里写重复判断。正确做法是写一个 Clack 中间件在进入路由之前检查请求路径前缀。这正好说明 Caveman 和 Flask 这类框架在哲学上的差异Flask 把app.before_request这类钩子内建了Caveman 选择把拦截逻辑下沉到中间件层框架本身保持很薄。3. 模板渲染与页面组装Djula 之外的路也能走3.1 render 函数背后发生了什么Caveman 的响应函数最常见的一种是直接返回字符串但正规的页面渲染都走render函数(defroute / () (render index.html (:message Hello, Caveman!)))render做的事情很朴素把模板文件名和变量 plist 交给配置好的模板引擎拿到渲染后的字符串再封装成一个 Clack 响应对象。默认模板引擎是 Djula一个 Django 风格模板引擎。用它的理由很简单模板语法是{% for item in items %}、{{ item.name }}这种花括号风格只要用过 Django/Jinja2 的人基本零成本切换。3.2 布局继承和局部模板的实战Djula 像 Django 一样支持extend和block。我通常建一个base.html作为主布局里面写好 HTML 骨架、CSS/JS 引用和页头页脚中间留一个contentblockhtml headtitle{% block title %}Default{% endblock %}/title/head body {% include partials/header.html %} main{% block content %}{% endblock %}/main {% include partials/footer.html %} /body /html然后每个页面模板只写自己的 content 部分{% extends base.html %} {% block content %} h1{{ post.title }}/h1 p{{ post.body }}/p {% endblock %}说实话Caveman 官方文档对模板布局这部分着墨不多很多人第一次用会在include的相对路径上栽跟头。我的经验是在*template-directory*下建partials/子目录模板文件之间用partials/header.html这种相对模板根目录的路径而不要用绝对文件系统路径。这样换服务器、换环境就不会挂。3.3 静态文件、上传与文件下载静态文件的处理Caveman 默认通过lack.middleware.static中间件挂载。它会把你static/目录里的文件按路径映射出来。但在实践中如果你前面架了 Nginx我倾向于把静态文件直接从 Nginx 分发完全不给 Lisp 进程添麻烦Caveman 进程只处理 API 和页面请求静态资源走 Nginx 更省事。文件上传则要往前走一步Clack 底层我用的是 Hunchentoot 后端会帮你解析multipart/form-data你能在请求对象里拿到上传文件的临时路径和数据。但要注意的是上传文件大小限制、上传目录权限、文件名清洗框架都不管这些都需要你作为服务端开发者自己做好。文件名清洗这块我吃过大亏直接拿用户原始文件名去存盘结果混入路径分隔符和特殊字符导致目录结构被逆向利用。现在我的做法是服务端生成 UUID 文件名原始文件名只存在数据库的元数据字段里。4. 数据库操作迁移、ORM 与连接池的配合4.1 Mito 的建模与自动迁移Caveman 官方文档推荐的持久层组合是 Mito Datafly这俩跟 Caveman 是同一个作者Eitaro Fukamachi的生态作品。Mito 是一个基于 CLOS 的 ORM和 Active Record 有些神似定义一个模型类数据库表结构就能从这个类推导出来。一个典型的模型定义长这样(mito:defclass user (mito:dao) ((name :col-type (:varchar 64) :initarg :name :accessor user-name) (email :col-type (:varchar 128) :initarg :email :accessor user-email)))继承mito:dao这个类会帮你自动加主键id和created-at、updated-at这类通用字段。定义完之后执行迁移Mito 会自动建表、加字段。我用它最舒服的是改模型加一个 slot跑一次迁移数据库里就多出一列不用手工写ALTER TABLE。4.2 Datafly 查询接口Lisp 表达式的 SQLDatafly 是轻量查询包语法和手写 SQL 的结构基本上是一一对应的。比如查所有激活用户(datafly:select :id :name :from (:users) :where (:and (: :status active) (: :created-at *some-date*)))SQL 关键字对应 Lisp 关键字参数条件表达式是符号表达式而不是字符串拼接。这意味着只要你不故意做字符串插值就不会有 SQL 注入风险。这是它比Lisp 里拼 SQL 字符串这种方案安全得多的原因。当然Datafly 不是万能的。复杂的连接查询、子查询、窗口函数用它写反而晦涩。我现在的习惯是普通 CRUD 走 Mito 的对象方法中等复杂查询走 Datafly真正报表级的 SQL 直接手写原生 SQL 字符串并由专门封装的query函数统一执行和返回 plist。4.3 请求生命周期里的数据库连接管理这是我在 Caveman 里踩得最深的坑之一。Clack 应用跑起来之后通常是一个多线程服务器每个请求可能在一个独立线程里执行。如果你在应用启动时只建立一个全局数据库连接并发一上来就会出现连接错乱、锁等待、甚至database is locked错误。我的标准做法是在请求入口处绑定连接(defun wrap-db-connection (app) (lambda (env) (mito:with-connection *db-connection-spec* (funcall app env))))然后把这个 wrapper 作为一个 Clack 中间件挂到中间件链里。这样每个请求进来都建立自己的连接用完自动归还连接池SQLite 的写锁问题也会因为连接隔离而得到大幅缓解。如果你用 PostgreSQL我还建议在中间件里把事务处理也包进来遇到异常就 rollback正常就 commit。这样路由处理函数里就不用到处写事务边界了。5. 中间件、会话与安全基线5.1 值得常驻的 Clack 中间件Caveman 的中间件体系来自 Clack配置方式通常是在项目配置文件里维护一个中间件列表。我线上常驻的中间件有这么几类中间件作用是否开发/生产都开lack.middleware.static提供静态文件服务建议生产关交给 Nginxlack.middleware.session用 Cookie 维护会话 ID都开lack.middleware.accesslog记录访问日志都在生产开lack.middleware.backtrace出事时显示完整错误堆栈只开发开lack.middleware.csrfCSRF 令牌校验有表单就都开把这些中间件按顺序配好之后Caveman 的处理函数只关心业务逻辑不用自己处理这是不是同一个会话这个是哪个用户这种横切关注点。5.2 Session 与 Cookie 的安全基线Session 中间件默认生成的会话密钥需要重点保护密钥泄漏等于所有人可以伪造你的会话 Cookie。至少要做到两点密钥只通过环境变量注入不写进代码仓库线上定期轮换。CSRF 防护上Lack 的 CSRF 中间件实现思路和所有主流框架一致为表单生成一次性 token提交时校验 token 一致性。Caveman 的模板文件里加个隐藏字段即可。但要记住如果你做的是一套纯 JSON API通常不需要 CSRF token而如果你同时服务页面表单和 JSON 接口记得把 CSRF 中间件的豁免路径配好否则写 API 的同事会被 403 折磨疯。5.3 错误处理与日志线上排障三件套Caveman 默认在开发模式会返回堆栈信息页面这在本地调试是福音但对线上是灾难。我习惯把应用包装进一个错误处理中间件(defun wrap-error-handler (app) (lambda (env) (handler-case (funcall app env) (error (e) (log:error ~A e) (500 (:content-type application/json) ({\error\:\internal\}))))))这个中间件做三件事记录完整堆栈到日志、给客户端返回干净的 JSON 错误、防止服务器进程崩溃。生产上还应该接一个 APM 或集中日志系统把关键请求的响应时间、SQL 耗时、错误堆栈汇到一块儿。我在实际排障中最常用的套路是AccessLog 中间件记录每个请求的路由、状态码、耗时配合错误中间件打印的堆栈一般能快速定位是路由写错、参数解析失败还是 SQL 查询超时。6. 部署与性能把 Lisp 应用发布到服务器6.1 编译式部署方式Common Lisp 一个独门优势是可以把整个项目编译成原生可执行文件。用 Roswell 或者 buildapp 打包后你得到的是一个不依赖 REPL 的二进制程序。部署流程相比 Python 的依赖安装、Node 的 node_modules 同步要干净得多传一个二进制文件过去配好环境变量就能跑起来。我用 Roswell 的ros build生成本项目可执行文件然后写一个简单的 systemd service 管理进程。重启、开机自启、异常拉起都有 systemd 托管Lisp 进程本身只需要监听一个端口。6.2 线程模型与 worker 调优Hunchentoot 后端是典型的每连接一线程模型。SBCL 的线程调度在普通 Linux 服务器上表现比我预期好但也不是完全没有代价线程上下文切换、线程内存开销都是成本。我调优的第一准则是 worker 数不要盲目跟 CPU 核数对齐而是看实际并发连接数。一个订单查询服务同时在线几十人起 8 个 worker 足够了起太多反而把数据库连接池拖垮。另外非常建议大家把 HTTP Server 的超时参数明配出来慢连接、超长上传、空闲连接各设一个阈值。否则某个客户端断线重连几次线程数就涨上去了。6.3 部署踩过的坑热更新、时区、中文字符集这三个坑是我强烈建议后来人提前处理的。第一热更新。Lisp 有 SLIME/SLY 远程连到线上环境改代码的能力我一度很沉迷这个手术刀式运维。但后来发现线上热改导致的问题比它解决的问题多改了一行忘了重新编译依赖它的后续函数结果线上跑着个半新半旧的混合状态。现在我的策略是热更新只允许在 staging 环境使用生产一律走重新构建二进制 平滑重启的流程。第二时区。SBCL 默认本地时间解析字符串服务器通常设置成 UTC你本地是东八区。日志时间戳、数据库里的now()、定时任务触发时间三者很容易出现八小时漂移。统一方案是全局初始化local-time库把时区明确设成 UTC展示时间时再在前端转本地。第三中文字符集。这几乎是我经历过的每个 Lisp Web 服务都会遇到一次的问题。MySQL/PostgreSQL 连接默认字符集、HTTP Response 的Content-Type头、模板文件的编码声明任何一个环节没对齐 UTF-8就会出现半个字甚至是乱码。建议在应用初始化时强制把三个地方都设置为 UTF-8数据库连接字符串里带字符集参数、模板渲染输出的 HTML head 里声明 meta charset、Clack 中间件层统一给响应头加Content-Type: text/html; charsetutf-8。7. 从 Caveman 看 Lisp Web 生态我的真实评价7.1 这个框架最值得吸收的架构思想把框架拆开看Caveman 其实没发明什么新东西。路由、模板、中间件、静态资源这套模型和十年前 Sinatra 做的事没什么本质区别。但它出现在 Common Lisp 这个生态里却有一种示范意义它证明了 Lisp 写 Web 服务不需要魔法也不需要放弃结构化思维完全可以像现代 Web 框架一样清晰地分层。最值得学的其实是它的克制。它没有试图把 ORM、前端打包、测试框架全部内建而是选择在路由层做到够用然后把数据库交给 Mito/Datafly、把 HTTP 抽象交给 Clack、把构建部署交给 Roswell。这种组合优于约束的设计和 Common Lisp 本身的哲学是一致的。7.2 什么情况下真不建议用 Caveman如果你有直上生产的大型项目团队里又没有 Common Lisp 背景的人我劝你别精挑细选了。Caveman 是小而美的工具生态相对小众遇到诡异问题可以求助的社区资源比不上主流框架。而且它对 JSON API 的默认支持比较原始自带的模板引擎偏向服务端渲染做纯前端分离架构时需要自己拼 JSON 序列化、CORS、API Blueprint 文档等一系列轮子。还有一类场景也不合适需要依赖大量成熟中间件/插件时。Rails 五秒钟能装好的文件上传、后台管理、认证脚手架在 Caveman 这里都要自己搭。它适合你掌控欲强、喜欢自己组装工具链的人不适合急着上线、想依赖现成解决方案的人。7.3 我还会不会把它作为默认起点个人现在的答案是会但会分场景。内部工具、数据处理面板、教学演示、中小流量 API用 Caveman 很顺手它生成的代码容易读懂重构时敢于乱动不会像某些重型框架一样让你瞻前顾后。真要做一个大型产品后端我可能会先考虑 Clojure 系框架或者干脆用更主流的语言生态。但说实话每次回到 Caveman 写一个小服务那种所有配件都摊在桌上、自己亲手生火的感觉是很多人已经忘记的痛快。如果你也在 Lisp 世界里做 Web 服务它值得当第一个起点。