path: root/content/article/clj6.md

+++
title = 'Coffee Break Clojure, Vol.6'
subtitle = 'Ring Ring Ring'
slug = 'clj6'
tags = ["Lisp","Clojure","编程","Web"]
categories = '茶歇蔻芥'
date = 2026-10-06 00:17:09
draft = false
toc = true
endnotes = [
    '本文副标题 *Ring Ring Ring*，来自 S.H.E. 的[同名歌曲](https://redirect.invidious.io/watch?v=nnQNiPAK-nY)。'
]
fedi = 'https://akk.eltr.ac/objects/a0ebb4b3-ca36-4b8d-9095-3a09c7f30d65'
+++

[上一篇](/article/clj5/)讲解了如何用 Leiningen 管理 Clojure 项目的目录结构和依赖项，今天我们来了解 Clojure 生态中最常见的 Web 后端库 [Ring](https://github.com/ring-clojure/ring)。不对，和那个 [IndieWeb Ring](https://xn--sr8hvo.ws/) 没有关系。<!--more-->

## 初识 Ring

Ring 是对 Web 服务器的**低层**抽象，也就是说没有实现页面路由（router），和通常的后端框架（比如 Go 的 Gin、Python 的 Django、Java 的 Spring Web 等）有很大区别。

根据 [Ring Spec 1.6.1](https://github.com/ring-clojure/ring/blob/master/SPEC.md)，Ring 主要有三个概念：

1. Handler（处理器）
2. Middleware（中间件）
3. Adapter（适配器）

Ring 提供了三种 API： 同步 API、异步 API 和 WebSocket API。不同的 API 在概念上略有不同，我们先从最简单的同步 API 讲起。

Handler 就是一个函数，接收 HTTP 请求，返回 HTTP 响应。 

```clojure 
;; 一个示例 Handler
(fn [request] response)
```

异步 API 的区别不大，只不过，由于 Handler 的结果需要异步返回，如果出了错也要异步报错，所以要传入两个回调函数用来响应和报错。

```clojure
(fn [request respond raise]
  (if (not exception)
    (respond response)
    (raise exception)))
```

一个 Handler 可以同时实现同步和异步 API。

```clojure 
(fn
  ([request]
    response)
  ([request respond raise]
    (respond response)))
```

Middleware 接收一个或多个 Handler，也可能接受一些参数，最后返回新的 Handler。可以理解为设计模式中的装饰器模式（decorator pattern），用来调整或增强 Handler 的行为，比如把 Handler 返回的响应体都解析成 JSON 字符串。

Adapter 接收一个 Handler 和其他配置参数，在调用时启动 HTTP 服务器。 

```clojure 
;; 调用一个 Adapter 的示例
(run-adapter handler options)
```

把 `options` 设置成 `{:async? true}`，Adapter 就能以异步模式运行了。前提是 Handler 支持异步 API，Adapter 也要支持 `:async?` 才行。异步 API 可以让服务器并行处理多个请求，如果对并发度有要求可以用。 

接收 HTTP 请求的就是 Adapter，他会把请求包装成 Request Map 传递给 Handler，随后把 Handler 返回的 Response Map 构造成 HTTP 响应发送给客户端。可以把 Adapter 理解为设计模式中的代理模式（proxy pattern），用户不直接调用 Handler，而是通过 Adapter 调用 Handler，Adapter 会处理 HTTP 协议相关的细节。

![](https://img.eltr.ac/geedeapro/article/clj6/ring-concepts.svg "图片由我使用 [Excalidraw](https://excalidraw.com/) 绘制")
{.dark:invert}

上述组件其实都不必有代码依赖关系，因为函数可以作为数据传递，上图的虚线都表示数据流。Handler 先是经过 Middleware 被改装成了新的 Handler，然后被传入 Adapter；Adapter 在 Web 服务器有请求进来时调用 Handler 产生响应数据，把响应数据包装成响应体后传送给客户端。

## 简单的 Web 服务器

先在 `project.clj` 里添加两个新依赖：

```clojure 
  :dependencies [[org.clojure/clojure "1.10.1"]
                 [ring/ring-core "1.8.2"]
                 [ring/ring-jetty-adapter "1.8.2"]])
```

其中一个是 Ring 的核心库，另一个是 Jetty[^1] 的 Ring Adapter。`ring-core` 也提供了一些 Middleware，我们其实只需要写 Handler。

创建 `src/antfigher/handler.clj`，`antfigher` 是我用来演示的项目名。我们先让 Handler 只返回 `Hello!` 这一条信息。

```clojure 
(ns antfighter.handler)

(defn handler [request]
  {:status 200 
   :body "Hello!"})
```

接下来需要启动 Web 服务器，如果你安装了上一篇提到的 `lein-ring` 插件，就可以直接用命令行启动了。在 `project.clj` 中添加这些配置：

```clojure 
  :plugins [[lein-ring "0.12.6"]]
  :ring {:handler antfighter.handler/handler}
```

`:plugins` 安装了 Ring 插件，`:ring` 则是这个插件的配置项，其中 `:handler` 指定了 `antfigher.handler` 命名空间下的 `handler` 符号，也就是我们刚才定义的 `handler` 函数。

在终端输入 `lein ring server` 启动服务器，之后工具会自动在浏览器里打开 `http://localhost:3000`，然后就能看到 `Hello!` 显示在浏览器页面里。

如果要打包成可以直接在 JVM 上执行的 `.jar` 文件，可以用 `lein ring uberjar` 编译。不过，我不建议依赖这个 Leiningen 插件来编译应用，而且不少应用其实除了启动 Ring 服务器，还需要启动别的东西，比如后台处理线程、消息队列等等。`lein ring uberjar` 只会把指定的 Handler 编译进去。

在 `core.clj` 文件的 `-main` 函数里编写启动逻辑：

```clojure {hl_lines=[3,4,9]}
(ns antfighter.core
  (:gen-class)
  (:require [antfighter.handler :refer [handler]]
            [ring.adapter.jetty :refer [run-jetty]]))

(defn -main
  "I start a Jetty server."
  [& args]
  (run-jetty handler {:port 3000}))
```

`run-jetty` 就是 Ring Jetty Adapter，它接收 `handler` 函数和作为配置项的映射，这里我们传入的配置是 `{:port 3000}`，也就是在 `3000` 端口上启动 Jetty 服务器。

这时运行 `lein run`，再手动打开 `localhost:3000`，也能看到 `Hello!`。如果用 `lein uberjar` 把项目编译成 `.jar`，然后用 `java -jar xxx.jar` 运行，也是一样的效果。[^2]

开发时建议用 `lein ring server`，因为自带热重载，保存代码后就能看到效果。

## 处理 HTTP 请求

Handler 接收的参数 `request` 是个映射，结构如下：

| Key                 | Type                               | Required |
| ------------------- | ---------------------------------- | -------- |
|`:body`              |`java.io.InputStream`               |          |
|`:headers`           |`{String String}`                   | Yes      |
|`:protocol`          |`String`                            | Yes      |
|`:query-string`      |`String`                            |          |
|`:remote-addr`       |`String`                            | Yes      |
|`:request-method`    |`Keyword`                           | Yes      |
|`:scheme`            |`Keyword`                           | Yes      |
|`:server-name`       |`String`                            | Yes      |
|`:server-port`       |`Integer`                           | Yes      |
|`:ssl-client-cert`   |`java.security.cert.X509Certificate`|          |
|`:uri`               |`String`                            | Yes      |

Handler 也应该返回一个映射，结构如下：

| Key      | Type                                       | Required |
| -------- | ------------------------------------------ | -------- |
|`:body`   |`ring.core.protocols/StreamableResponseBody`|          |
|`:headers`|`{String String}` or `{String [String]}`    | Yes      |
|`:status` |`Integer`                                   | Yes      |

上述表格摘自 [Ring Spec](https://github.com/ring-clojure/ring/blob/master/SPEC.md)。大部分情况下我们都只需要使用 `:body` 和 `:headers`，也就是响应头（或请求头）以及响应体（或请求体），响应时还需要带上 `:status`，即 HTTP 状态码。

当然，如果你不用任何路由库，纯手动路由，那还要用到 `:request-method`（请求方法，如 `GET` `POST`）和 `:uri`（用来解析路径）。

Handler 做的事情其实就是对请求做些处理，然后构造响应。比方说，如果客户端用 `GET` 方法请求 `/hello` 目录才返回 `Hello!`，对其他路由都返回 `404` 和 `Not Found`，就可以这样写：

```clojure 
(ns antfighter.handler
  (:import [java.net URI]))

(defn handler [request]
  (let [method (:request-method request)
        uri (:uri request)
        path (.getPath (URI. uri))]
    (if (and (= method :get)
             (= path "/hello"))
      {:status 200 
       :body "Hello!"}
      {:status 404 
       :body "Not Found"})))
```

不过，访问 `/hello` 会得到 `Hello!`，但访问 `/hello/` 却是 `Not Found`。我们的路由匹配方式有缺陷。处理这些细节太麻烦了，有没有别的办法？

## 沉着冷静地路由

[Compojure](https://github.com/weavejester/compojure) 是 Ring 的主要贡献者 [weavejester](https://github.com/weavejester) 维护的路由库。这个名字显然来自 *Composure*，意思是「沉着冷静」。

如果要新建项目的话，其实可以直接用 Leiningen 的 `compojure` 模板：

```
lein new compojure hello-world
```

不过我自己的感受是，不用脚手架从零搭建会减少很多认知负债，在一开始就把各种组件、依赖关系和架构搞清楚是最好的。熟悉之后再图方便使用模板。

下文提及的符号基本都定义在 [`compojure.core`](https://weavejester.github.io/compojure/compojure.core.html) 命名空间里，读者应该会使用 `require` 引入符号（如果不会，就去读[上一篇](/article/clj5/)），我就不写 `require` 了。

Compojure 的核心是 `routes` 函数，用来把多个 Handler 组合成一个。一般和 `GET`、`POST`、`PUT` 等路由宏一起使用，每个宏对应一个 HTTP 方法，可以用 `ANY` 宏匹配任意方法。这些宏展开之后，最终返回的是对应方法和路径的 Handler。

```clojure 
(def api-routes
  (routes 
    (GET "/hello" request (handle-hello request))
    (POST "/receive" request (handle-receive request))))

(run-jetty api-routes {:port 3000})
```

上述代码可以简写为：

```clojure 
(defroutes api-routes
  (GET "/hello" request (handle-hello request))
  (POST "/receive" request (handle-receive request)))

(run-jetty api-routes {:port 3000})
```

`request` 可以直接传给处理逻辑，也可以解构（destructure）之后再传递：

```clojure 
(defroutes api-routes
  (GET "/hello" [username] (say-hello username))
  (POST "/receive" [data] (receive data)))
```

放在向量里的符号会被自动绑定到对应名称的 Query String 或 POST 参数上。

```sh 
curl http://localhost:3000/hello?username=Alice 
# => Hello Alice!
```

Compojure 也可以用 Clojure 自带的[解构](https://clojure.org/reference/special_forms#binding-forms)，比如把数据从 Session 里取出来：

```clojure 
(GET "/user" {{:keys [user-id]} :session}
  (str "The current user is " user-id))
```

关于解构，一般用向量取出 Query 和 POST 参数就够了，更多用法可以参考 [Compojure Wiki](https://github.com/weavejester/compojure/wiki/Destructuring-Syntax)。如果觉得解构的语法太麻烦，直接用 Request map 也没有问题。

这些宏也天然支持动态路由：

```clojure 
;; 路径中的 :username 会被绑定到 username 符号上
;; 下面的路由会匹配所有形如 /hello/* 的 GET 路径
(GET "/hello/:username" [username] 
  (say-hello username))

;; 可以用正则表达式做更严格的匹配
(GET ["/user/:id", :id #"[0-9]+"] [id]
  (get-user id))
```

路由可以嵌套，要用到 `context` 宏，参考 [Wiki](https://github.com/weavejester/compojure/wiki/Nesting-routes) 里的例子：

```clojure 
(defroutes user-routes
  (context "/user/:user-id" [user-id]
    (GET "/profile" [] ...)
    (GET "/posts" [] ...)))
```

如果一个请求发过来，没有匹配上任何一条路由，那么 Compojure 会返回 `nil`。我们还没处理 Not Found 路径。可以用 [`compojure.route`](https://weavejester.github.io/compojure/compojure.route.html) 里的 `not-found` 函数处理 `404` 请求。

```clojure 
(require '[compojure.route :as route])

(defroutes api-routes
  (GET "/hello" [username] (say-hello username))
  (POST "/receive" [data] (receive data))
  (route/not-found "Not Found"))
```

Compojure 不仅帮我们解构 `request`，还可以智能地处理 `response`。比如，我们可以把 `GET "/hello"` 这个路由的响应替换成字符串。

```clojure 
(defroutes api-routes
  (GET "/hello" [username] (str "Hello " username "!"))
  (POST "/receive" [data] (receive data))
  (route/not-found "Not Found"))
```

`"Hello Alice!"` 会被自动包装成：

```clojure 
{:status 200
 :headers {"Content-Type" "text/plain; charset=utf-8"}
 :body "Hello Alice!"}
```

构造这种响应体可能很麻烦，除了让 Compojure 自动处理（说实话，我觉得自动处理有点令人捉摸不透，自己写清楚会好点），还可以用 [ring-http-response](https://github.com/metosin/ring-http-response) 工具库：

```clojure 
(require '[ring.util.http-response :refer :all])

(continue)
; {:status 100, :headers {}, :body ""}

(ok "body")
; {:status 200, :headers {}, :body "body"}

(created "url" "body")
; {:status 201, :headers {"Location" "url"}, :body "body"}

(found "url")
; {:status 302, :headers {"Location" "url"}, :body ""}
```

## 自由组合中间件

Compojure 能帮我们处理路由、请求体的解构和响应体的封装，但内部结构并不复杂，这些功能是通过 Middleware 实现的：

```clojure 
(defn make-route
  "Returns a function that will only call the handler if the method and path
  match the request."
  [method path handler]
  (-> handler
      (wrap-response)
      (wrap-route-middleware)
      (wrap-route-info [(or method :any) (str path)])
      (wrap-route-matches method path)))
```

这些 `wrap-` 开头的函数就是 Middleware，最初的 `handler` 作为参数被传入这些函数，一层层被包装。`wrap-response` 给 Handler 增加了自动包装返回值（响应体）的能力，`wrap-route-matches` 则保证只有请求体里的方法和路径都匹配时才放行。

还记得 `defroutes` 定义的符号也是个 Handler 吗？Compojure 的路由不过是把多个匹配不同路由的 Handler 组合成了一个大的 Handler。Handler 就是这样被组合、装饰才变得支持多路由和各种额外功能的。

我们还可以继续包装 Handler，比如用 [`ring-json`](https://github.com/ring-clojure/ring-json) 库，把响应体 `:body` 里的 Clojure 数据结构自动解析为 JSON 字符串：

```clojure
  :dependencies [[org.clojure/clojure "1.10.1"]
                 [ring/ring-core "1.8.2"]
                 [ring/ring-jetty-adapter "1.8.2"]
                 [ring/ring-json "0.5.1"]]) ;; <- 新依赖
```

`ring.middleware.json/wrap-json-body` 会解析所有 `Content-Type` 为 JSON 的响应体。

```clojure 
(require '[ring.middleware.json :refer [wrap-json-body]])

(defroutes api-routes 
  (GET "/test" [] 
    {:status 200
     :headers {"Content-Type" "application/json"}
     :body {:message "Cheshire just visited me."}}))

(def app 
  (wrap-json-body api-routes))

(run-jetty app {:port 3000})
```

```sh 
curl http://localhost:3000/test 
# => {"message": "Cheshire just visited me."}
```

如果需要对响应数据做处理，比起放在业务逻辑里增加复杂度，不如写一个 Middleware，对 Handler 进行装饰。如果是相对通用的需求，可以找找有没有已经实现自己需求的库。

---

## 其他参考资料 

- 除了 Ring 默认的 Jetty，我个人比较推荐 [http-kit](https://github.com/http-kit/http-kit)，它提供了简单且性能较好的 Web 服务器实现，可以用 `org.httpkit.server/run-server` 替代 `run-jetty`。这个库也提供了 HTTP 客户端实现。
- 除了 Compojure，还有更新更现代的 [reitit](https://github.com/metosin/reitit)，不过仍处于 `0.x.x` 版本阶段，不如 Compojure 稳定。
    
    reitit 的主要亮点是数据驱动，路由不必写成宏形式，可以写成嵌套的向量：

    ```clojure 
    (defn cqrs-routes [actions]
      ["/api" {:interceptors [::api ::db]}
       (for [[type interceptor] actions
             :let [path (str "/" (name interceptor))
                   method (case type
                            :query :get
                            :command :post)]]
         [path {method {:interceptors [interceptor]}}])])
    ```
    
    上面这个示例来自 [reitit](https://cljdoc.org/d/metosin/reitit/0.11.0/doc/basics/route-syntax) 文档。说实话，用 `for` 循环（或者 `map`）构造路由看起来很酷，但用宏同样可以做到啊。Clojure/Lisp 代码本身就是数据，不需要什么「数据驱动」。

    不过 reitit 还有别的好处，比如可以在路由里写拦截器（interceptor）。
- 你可能会想要 Swagger API 文档，有 [`ring-swagger`](https://github.com/metosin/ring-swagger) 这个库，本质上是在 API 路由的定义里添加了一些元数据和文档描述，然后在**运行时**用这些数据生成 `swagger.json`，还把 Swagger UI 也打包在内。

    还有专门为 Compojure 设计的 [`compojure-api`](https://github.com/metosin/compojure-api)，用 `ring-swagger` 实现。我试了试，这个库的依赖有点大，打包后可能有十几二十兆。在我看来不如手写文档，除非 API 真的很复杂。

--- 

## 最后 

这其实也是我第一次这么仔细地阅读 Ring 和 Compojure 的架构。Ring 的 Handler、Middleware 和 Adapter 其实很优雅，尤其是 Middleware 的组合，以非常优雅清晰也非常函数式的方式拓展了 Handler 的能力。

由于写文的过程中发现了不少之前不了解的细节，所以我打算稍后就去整理一下我项目里的 API 写法。那么，回见！

[^1]: Jetty 是个 Java Web 服务器；也可以换成别的，这里就用默认的 Jetty 演示了。

[^2]: 上篇文章提到了，如果要用 Java 运行，就要保留 `core.clj` 中的 `:gen-class`。