告别SQL字符串噩梦：Yesql让Clojure与SQL优雅共舞
【免费下载链接】yesql A Clojure library for using SQL. 
项目地址: https://gitcode.com/gh_mirrors/ye/yesql
为什么要颠覆传统SQL使用方式？
你是否也曾在Clojure代码中写下这样的查询？
(query "SELECT * FROM users WHERE country_code = ? AND age > ? AND signup_date > ?" "GB" 18 "2023-01-01")
当查询条件超过3个，参数顺序稍不注意就会导致逻辑错误；当SQL语句超过20行，缩进混乱和缺少语法高亮让维护变成噩梦。而另一种极端——使用Clojure DSL构建查询：
(select :*
(from :users)
(where (and (= :country_code "GB") (> :age 18) (> :signup_date "2023-01-01"))))
这种方式不仅需要学习新语法，当遇到复杂子查询或数据库特有函数时，最终还是要回归(raw-sql "...")的妥协。Yesql给出了第三种选择——让SQL回归SQL，让Clojure专注Clojure。
读完本文你将掌握
- ✅ 10分钟上手Yesql的核心工作流
- ✅ 4种参数传递模式的实战对比
- ✅ 从单查询到批量SQL文件的管理策略
- ✅ 生产环境必备的事务与连接管理
- ✅ 3类常见陷阱的规避方案
- ✅ 性能优化的5个关键技巧
Yesql核心原理：SQL即函数
工作流程图解
Yesql通过解析SQL文件中的特殊注释标记，将SQL语句转化为类型安全的Clojure函数。核心优势在于：
- 零学习成本：完全使用原生SQL语法
- 双向工具支持：享受IDE的SQL语法高亮与Clojure函数提示
- 团队协作：DBA可直接编辑SQL文件，无需了解Clojure
快速入门：15行代码实现完整查询
1. 环境准备
项目依赖配置（project.clj）：
:dependencies [
[org.clojure/clojure "1.11.1"]
[yesql "0.5.3"] ; 最新版本请查询Clojars
[org.postgresql/postgresql "42.3.5"] ; 数据库驱动
]
数据库连接配置：
(def db-spec {:classname "org.postgresql.Driver"
:subprotocol "postgresql"
:subname "//localhost:5432/your_db"
:user "db_user"
:password "db_pass"})
2. 创建SQL文件
resources/sql/user_queries.sql:
-- name: users-by-country
-- 按国家代码查询用户列表
-- 参数: :country_code (字符串), :min_age (整数)
SELECT id, name, email, signup_date
FROM users
WHERE country_code = :country_code
AND age >= :min_age
ORDER BY signup_date DESC
LIMIT :limit OFFSET :offset
3. 生成并使用查询函数
(ns your-app.db
(:require [yesql.core :refer [defqueries]]))
;; 导入SQL文件生成函数
(defqueries "sql/user_queries.sql" {:connection db-spec})
;; 调用生成的函数
(defn get-recent-users [country age page per-page]
(users-by-country {:country_code country
:min_age age
:limit per-page
:offset (* (dec page) per-page)}))
;; 使用示例
(get-recent-users "CN" 18 1 20)
; => ({:id 1001, :name "张三", :email "zhangsan@example.com", ...} ...)
函数自动生成的元数据：
(clojure.repl/doc users-by-country)
; => -------------------------
; => your-app.db/users-by-country
; => ([{:keys [country_code min_age limit offset]}]
; => [{:keys [country_code min_age limit offset]} {:keys [connection]}])
; =>
; => 按国家代码查询用户列表
; => 参数: :country_code (字符串), :min_age (整数)
四种参数传递模式全解析
1. 命名参数（推荐）
-- name: find-by-email
SELECT * FROM users WHERE email = :email
(find-by-email {:email "user@example.com"})
2. 位置参数（兼容遗留代码）
-- name: find-by-country-and-age
SELECT * FROM users WHERE country = ? AND age > ?
(find-by-country-and-age {:? ["CN" 18]}) ; :?键对应参数向量
3. IN子句参数（自动展开）
-- name: find-by-ids
SELECT * FROM users WHERE id IN (:ids)
(find-by-ids {:ids [1001 1002 1003]}) ; 自动展开为 (1001, 1002, 1003)
4. 混合参数（谨慎使用）
-- name: complex-query
SELECT * FROM users
WHERE country = ?
AND age > :min_age
AND tags && :tags
(complex-query {:? ["CN"] :min_age 18 :tags ["active" "premium"]})
参数模式对比表：
| 模式 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 命名参数 | 可读性强，顺序无关 | 不支持重复参数 | 大多数CRUD操作 |
| 位置参数 | 兼容JDBC原生语法 | 易混淆参数顺序 | 移植遗留SQL代码 |
| IN子句 | 自动处理集合展开 | 受数据库参数数量限制 | ID列表查询 |
| 混合模式 | 灵活性最高 | 代码可读性差 | 复杂报表查询 |
高级操作：事务、批量与结果处理
事务管理最佳实践
(require '[clojure.java.jdbc :as jdbc])
(defn transfer-funds! [from-id to-id amount]
(jdbc/with-db-transaction [tx db-spec] ; 创建事务连接
(update-balance! {:id from-id :amount (- amount)} {:connection tx})
(update-balance! {:id to-id :amount amount} {:connection tx})
(log-transfer! {:from from-id :to to-id :amount amount} {:connection tx})))
数据修改操作（INSERT/UPDATE/DELETE）
-- name: create-user!
INSERT INTO users (name, email, country_code)
VALUES (:name, :email, :country_code)
-- name: update-user-email!
UPDATE users SET email = :new_email WHERE id = :id
-- name: delete-inactive-users!
DELETE FROM users WHERE last_login < :cutoff_date
;; 创建用户并获取影响行数
(create-user! {:name "李四" :email "lisi@example.com" :country_code "CN"})
; => 1 ; 影响行数
;; 更新操作
(update-user-email! {:id 1001 :new_email "new@example.com"})
; => 1
获取自动生成的主键
-- name: create-user<! ; 使用<!后缀标记自动生成键
INSERT INTO users (name, email) VALUES (:name, :email)
(create-user<! {:name "王五" :email "wangwu@example.com"})
; => {:id 1003, :name "王五", :email "wangwu@example.com"} ; PostgreSQL返回完整行
结果处理函数
;; 只返回第一行
(user-count {:result-set-fn first})
; => {:count 1563}
;; 提取特定字段
(active-user-ids {:result-set-fn #(map :id %)})
; => (1001 1002 1003 ...)
;; 组合处理
(recent-signups {:result-set-fn (comp count filter :premium)})
; => 28 ; premium用户数量
项目实战：大型应用的SQL管理策略
1. SQL文件组织规范
resources/
├── sql/
│ ├── common/ # 通用查询（分页、计数）
│ │ └── pagination.sql
│ ├── users/ # 用户模块
│ │ ├── queries.sql # 查询操作
│ │ └── commands.sql # 修改操作
│ ├── orders/ # 订单模块
│ └── reports/ # 报表查询
2. 命名约定
| 元素 | 命名规则 | 示例 |
|---|---|---|
| 查询函数 | 名词+介词+宾语 | users-by-email, orders-with-items |
| 修改函数 | 动词+名词+! | create-user!, update-order-status! |
| 主键生成 | 动词+名词+<! | insert-product<! |
| SQL文件 | 模块名+queries.sql | user_queries.sql |
3. 批量导入与命名空间管理
(ns your-app.db
(:require [yesql.core :refer [require-sql]]))
;; 模块化导入
(require-sql ["sql/users/queries.sql" :as user-queries :refer [user-count]])
(require-sql ["sql/orders/commands.sql" :as order-cmds])
;; 使用别名调用
(user-queries/users-by-country "CN")
(order-cmds/create-order! {:user-id 1001 :items [...]})
;; 直接引用
(user-count)
性能优化：让查询飞起来
1. 避免N+1查询问题
反面示例：
;; 先查订单，再循环查订单项（N+1查询）
(defn get-orders-with-items [user-id]
(for [order (user-orders {:user-id user-id})]
(assoc order :items (order-items {:order-id (:id order)}))))
优化方案：
-- name: orders-with-items
SELECT o.*, i.id as item_id, i.product_id, i.quantity
FROM orders o
JOIN order_items i ON o.id = i.order_id
WHERE o.user_id = :user-id
(defn get-orders-with-items [user-id]
(->> (orders-with-items {:user-id user-id})
(group-by :id)
(map (fn [[order-id items]]
(-> (first items)
(dissoc :item_id :product_id :quantity)
(assoc :items (map #(select-keys % [:item_id :product_id :quantity]) items)))))))
2. 结果集处理策略
| 处理方式 | 性能影响 | 适用场景 |
|---|---|---|
| 默认映射 | 中 | 小结果集（<100行） |
| :row-fn只提取需要字段 | 高 | 列表展示、统计 |
| :result-set-fn doall | 低 | 大结果集流式处理 |
| 数据库端聚合（COUNT/SUM） | 极高 | 统计报表 |
优化示例：
;; 只提取必要字段，减少数据传输
(user-list {:country "CN"
:row-fn (juxt :id :name) ; 只保留id和name
:result-set-fn vec}) ; 转为向量而非序列
常见问题与解决方案
1. 参数名与Clojure关键字冲突
问题：SQL参数包含连字符（如:user-id）与Clojure关键字冲突
解决方案：
-- name: find-by-user-id
SELECT * FROM users WHERE user_id = :user-id ; SQL字段用下划线，参数用连字符
(find-by-user-id {:user-id 1001}) ; Clojure使用kebab-case
2. 处理数据库特定类型
(require '[clojure.java.jdbc :as jdbc])
;; JSONB字段处理（PostgreSQL）
(defn save-preferences! [user-id prefs]
(update-user-prefs! {:id user-id
:prefs (jdbc/value-of prefs)})) ; 自动转为JSONB
3. 调试SQL生成
;; 打印生成的SQL和参数
(require '[yesql.util :refer [log-sql]])
(defqueries "sql/debug.sql" {:connection db-spec :log-fn log-sql})
从其他方案迁移到Yesql
从JDBC直接调用迁移
| 传统JDBC方式 | Yesql方式 |
|---|---|
(query db "SELECT * FROM t WHERE a=?" 1) | (query-fn {:a 1}) |
| 手动处理结果集映射 | 自动关键字映射 |
| 字符串拼接SQL | 外部SQL文件 |
从ORM框架迁移
Hibernate/JPA用户注意：
- Yesql无实体映射，直接操作原始数据
- 关联查询需手动处理（参考N+1问题解决方案）
- 事务管理仍使用
clojure.java.jdbc
最佳实践清单
开发环境
- ✅ 为SQL文件配置语法高亮和格式化
- ✅ 使用REPL自动重载SQL文件变更
- ✅ 配置数据库连接池（HikariCP）
代码组织
- ✅ 查询与命令分离（Queries vs Commands）
- ✅ 按业务模块组织SQL文件
- ✅ 每个SQL文件不超过500行
性能与安全
- ✅ 所有用户输入通过参数传递（防注入）
- ✅ 复杂报表查询添加执行计划注释
- ✅ 定期使用EXPLAIN分析慢查询
总结：重新定义Clojure与SQL的关系
Yesql不是另一个ORM框架，而是SQL的自然延伸。它解决了以下核心痛点：
- 维护性：SQL集中管理，告别字符串拼接
- 可读性：原生SQL语法+注释=自文档化代码
- 协作性：开发与DBA使用相同的SQL文件
- 性能：直接优化SQL而非中间层抽象
通过本文介绍的方法，你可以：
- 将SQL从字符串地狱中解放出来
- 减少50%的数据库相关代码量
- 使查询性能提升30%以上
- 消除90%的参数传递错误
立即尝试Yesql，体验Clojure与SQL的完美融合！
【免费下载链接】yesql A Clojure library for using SQL. 项目地址: https://gitcode.com/gh_mirrors/ye/yesql
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
