Clojure 宏：defmacro 与 syntax-quote

宏是 Clojure 乃至整个 Lisp 家族最强大的特性之一。它让你能在编译期操作代码本身，实现普通函数无法做到的事情。本文将深入讲解 defmacro 的用法，以及如何借助 syntax-quote（语法引用）编写安全、优雅的宏。

一、为什么需要宏？

在 Clojure 中，普通函数接收数据作为参数，返回计算结果。函数的调用在运行时发生。但宏不同——宏接收的是 代码本身，返回的也是代码。宏的展开发生在编译期，展开后的代码再参与正常编译。

举一个简单的例子。假设你需要频繁检查 nil 值并进行快速失败：

(defn safe-divide [a b]
  (if (or (nil? a) (nil? b))
    (throw (IllegalArgumentException. "参数不能为 nil"))
    (/ a b)))

这段代码在每个需要 nil 检查的函数里都要重复一遍。如果用宏，可以把这个行为抽象成关键字般的能力：

(defmacro when-not-nil [value & body]
  `(when-not (nil? ~value)
     ~@body))

这个宏的含义是：只有当 value 不为 nil 时，才展开并执行 body 中的代码。看起来像是给语言添加了新语法。

二、defmacro 的基础用法

2.1 定义宏的语法

defmacro 的定义方式与 defn 类似，但关键区别在于它的返回值应该是 可以被求值的代码片段（称为 S 表达式），而不是最终运行时的值。

(defmacro my-macro [arg]
  ;; 这里返回的是一段代码，而不是执行结果
  `(println "参数是: " ~arg))

2.2 宏的调用与展开

调用宏时，Clojure 首先将宏展开成它代表的代码，然后再执行展开后的代码。你可以用 macroexpand-1 或 macroexpand 查看展开结果，这对调试非常有帮助：

;; 定义一个简单的条件宏
(defmacro unless [condition & body]
  `(if (not ~condition)
     (do ~@body)))

;; 查看宏展开的结果
(macroexpand-1 '(unless (> 5 3)
                  (println "5 不大于 3")))
;; => (if (not (> 5 3)) (do (println "5 不大于 3")))

注意看，unless 宏被完整展开成了 if 表达式。这就是宏的工作方式：生成代码，让代码再生成行为。

2.3 宏与函数的根本区别

函数调用时参数先求值，再把求值结果传给函数。宏则相反——参数 不求值，直接作为原始代码传入。这既是力量的来源，也是容易出错的地方。

;; 函数：参数先求值
(defn add [a b]
  (+ a b))

(add 1 2)  ;; => 3
;; 这里的 1 和 2 先被求值，再传给 add

;; 宏：参数不求值
(defmacro add-macro [a b]
  `(+ ~a ~b))

(add-macro 1 2)  ;; => 3
;; 这里的 1 和 2 作为字面量代码传入，在宏展开时才参与运算

三、syntax-quote 与反引号

3.1 什么是 syntax-quote

在宏的定义中，你会大量使用反引号 `（称为 syntax-quote 或语法引用）。它有几个重要作用：

1. 阻止求值：普通引用 ' 只阻止最外层求值，而反引号 ` 可以阻止整个表达式的求值，让代码保持原样。
2. 解构展开：在反引号内部，可以使用 ~（波浪号）取消引用，让特定部分恢复求值。
3. 自动前缀命名空间：反引号会自动给所有符号加上当前命名空间前缀，避免命名冲突。

;; 普通引用：保持表达式原样
'(+ 1 2)  ;; => (+ 1 2)

;; 语法引用：同样保持原样，但符号会带上命名空间
`(+ 1 2)  ;; => (clojure.core/+ 1 2)

3.2 ~（波浪号）：取消引用

在反引号内部，使用 ~ 可以让某个部分恢复求值：

(defmacro log-value [expr]
  `(println "值是: " ~expr))

(log-value (+ 1 2))  ;; => 打印 "值是: 3"

如果没有 ~，expr 会被当作符号处理，而不是被求值的结果。

3.3 ~@（波浪号 at）：解构列表

当你想把一个列表展开到外层列表中作为多个元素时，使用 ~@：

(defmacro debug-print [& statements]
  `(do
     (println "=== 调试开始 ===")
     ~@statements
     (println "=== 调试结束 ===")))

(debug-print
  (println "第一句")
  (println "第二句"))
;; 展开后：
;; (do
;;   (println "=== 调试开始 ===")
;;   (println "第一句")
;;   (println "第二句")
;;   (println "=== 调试结束 ==="))

四、实战：构建领域专用语言

宏最强大的用途是创建 领域专用语言（DSL）。假设你在构建一个路由库，希望有这样的语法：

(defroute index "/" [] (render :home))
(defroute user "/user/:id" [id] (render :profile id))

这看起来像是给语言添加了原生语法，实际上可以用宏实现。首先定义路由结构的数据表示，然后用宏把它们转换成函数定义：

(defmacro defroute [name path params & body]
  `(defn ~name []
     (let [~params {}]  ;; 简化处理，实际需要解析 path
       ~@body)))

;; 使用
(defroute home-page "/" [] "首页")
(defroute user-profile "/user/:id" [] "用户页")

4.1 处理命名冲突：unquote-splicing 与 gensym

宏展开时可能遇到变量名冲突的问题。比如下面的宏：

(defmacro bad-example [x]
  `(let [temp ~x]
     (if temp
       (println "temp 是真值")
       (println "temp 是假值"))))

;; 调用
(let [temp 100]
  (bad-example temp))

这段代码有问题：宏内部使用的 temp 可能会与外部的 temp 冲突，导致意外行为。解决方案是使用 gensym 自动生成唯一名称：

(defmacro good-example [x]
  (let [temp# (gensym "temp")]  ;; 生成如 temp123 这样的唯一符号
    `(let [~temp# ~x]
       (if ~temp#
         (println "temp 是真值")
         (println "temp 是假值")))))

;; 现在安全了
(let [temp 100]
  (good-example temp))

在反引号内部，直接在符号后面加 # 就能自动生成 gensym，如 temp#。这是最常用的写法。

4.2 syntax-quote 的自动命名空间前缀

Clojure 的 ` 会给所有符号加上当前命名空间前缀：

`println  ;; => clojure.core/println
`+        ;; => clojure.core/+

这在大多数情况下是好事，因为它确保你引用的是正确的函数。但在某些特殊场景下（比如动态生成代码需要引用特定命名空间的符号），你可能需要手动控制。这通常不是问题，因为 clojure.core 的函数会自动被引入。

五、最佳实践与常见陷阱

5.1 宏的调试技巧

宏一旦写错，编译错误信息往往难以理解。推荐的工作流：

1. 先写出宏的展开版本，确保逻辑正确。
2. 用 macroexpand-1 逐步验证展开结果。
3. 确认无误后再封装成宏。

;; 步骤 1：写出逻辑
(let [x 5]
  (when (> x 3)
    (println "大于3")))

;; 步骤 2：验证宏展开
(macroexpand-1 '(when (> x 3)
                  (println "大于3")))

;; 步骤 3：封装

5.2 避免过度使用宏

宏虽然强大，但不是所有抽象都需要用宏实现。以下情况优先考虑函数：

• 纯粹的数据转换和计算。
• 需要高阶函数作为参数（如 map、filter 的回调）。
• 需要组合多个小函数。

只有在普通函数无法优雅实现时，才考虑宏。滥用宏会让代码难以理解和维护。

5.3 递归宏与 trampoline

如果宏需要递归调用自身，展开阶段必须能正确终止。可以使用 trampoline 或确保递归调用在运行时发生而非展开期：

(defmacro deep-unroll [expr]
  (if (seq? expr)
    (let [op (first expr)
          args (mapv deep-unroll (rest expr))]
      (list op args))
    expr))

六、完整示例：构建一个简单的断言库

综合运用以上知识，我们来构建一个实用的断言宏：

(defmacro assert-msg [condition message]
  (let [cond# condition]
    `(when-not ~cond#
       (throw (AssertionError. ~message)))))

;; 使用示例
(let [x 5]
  (assert-msg (> x 10) "x 必须大于 10"))
;; 抛出 AssertionError: x 必须大于 10

如果要更复杂，支持多个断言：

(defmacro assert-all [& assertions]
  (let [pairs# (partition 2 assertions)]
    `(do
       ~@(map (fn [[cond# msg#]]
                `(when-not ~cond#
                   (throw (AssertionError. ~msg#))))
              pairs#))))

;; 使用
(let [data {:name "Alice" :age 30}]
  (assert-all
    (:name data) "必须包含 name 字段"
    (pos? (:age data)) "年龄必须为正数"))

这个例子展示了 syntax-quote、~@ 和 gensym 的协作，构成了一个小型但实用的 DSL。

七、总结

defmacro 让你能够在编译期操作和生成代码，是 Lisp 系语言最独特的特性。syntax-quote 提供了安全、便利的代码模板机制，配合 ~ 和 ~@ 实现精确的代码拼接。记住几个关键点：

• 宏的参数在展开期求值，而非运行时。
• 使用 macroexpand-1 调试宏展开结果。
• 用 # 自动生成唯一符号，避免命名冲突。
• 优先用函数，只在必要时才使用宏。

掌握宏，你就拥有了重新定义语言语法的能力，可以用 Clojure 构建真正贴合问题的领域专用语言。