soil

数据是软件的根本，就像大地滋润万物一样，所以名为soil。

soil是数据访问层的一种封装，目的是提供一种简单、好用、通用的数据库表访问解决方案。

关于数据访问层封装的思考

在我看来对于关系型数据的访问，最灵活、最强大的莫过于SQL了。访问库表数据，离开了SQL,而去追逐ORM、DSL之类的，在实践中也带来了不少问题。比如ORM的优化问题，比如DSL的语言学习成本问题。

ORM在java世界里面比较流行，我认为主要原因有二：

java开发人员希望生存在对象的世界里面，所以要将关系映射到对象上去。
熟悉sql的人没有熟悉java的人多，希望通过ORM工具来避免接触sql或由专人维护sql

软件行业人员众多，每个团队人才配置都是各层次搭配。所以，站在设计的角度看，通过数据层封装统一或约束对库表的访问方法，是一种提升软件质量、降低技能要求的一种现实办法。

设计目标

基于上述的思考，我们希望soil能够实现以下目标：

简单：给程序员提供的调用接口简单，配置方法简单。
统一：统一函数的调用参数顺序和数量。
易运维： 1. 常见操作的sql部分虽然是自动生成，但是生成逻辑简单直接，生成结果可读性强。2. 复杂sql查询，查询逻辑比如是否like，like时%怎么补全，由sql配置文件解决。

为了使soil功能聚焦，我们限定soil在数据访问层，不考虑以下问题：

使用方法

使用流程图

                                   否
                   +------------------------------------------------------------------------------------------------------------+
                   |                                                                                                            v
+----------+     +---------------+  是   +-----------------+     +--------------+     +-------------+     +-------------+     +-----------------+
| 添加依赖 | --> | 需要复杂操作? | ----> | 确定sql文件位置 | --> | 修改配置文件 | --> | 编辑sql文件 | --> | 生成sql函数 | --> | 探索使用sql函数 |
+----------+     +---------------+       +-----------------+     +--------------+     +-------------+     +-------------+     +-----------------+

Leiningen Coordinates

[org.tovictory.utils/soil “0.1.0-SNAPSHOT”]

判断是否需要复杂操作？

soil认为，不在其自建范围内的函数，均为复杂操作，一般建议您通过编写对应函数的sql文件来生成此函数。

探索使用内建的sql函数

(require '[org.tovictory.utils.soil.api :as das])

(das/query :users)
(das/query "users")
(use 'clojure.repl)
(dir org.tovictory.utils.soil.api)
(doc das/query)
(doc das/get-by-id)
(das/get-by-id :users 1)
(das/get-count :users ["id > 5"])
(das/get-count :users {:admin true})
(das/get-count :users {:admin true :email nil})
;; 小技巧 -- 忽略null值查询， 你可以传入其他针对值做判断的谓词函数
(das/get-count :users [identity {:admin true :email nil}])

确定sql文件位置

sql文件应该放在classpath里面，可以是resouces或src下面，可以建分目录。

建议参考使用restapp模板创建出的工程中sql文件放置的位置。 sql文件编写格式及注意事项，在样例文件中也说明。

修改配置文件

配置文件，一般可以在以下的几种配置样例中进行选择。在restapp生成的工程中，一般已经自动生成该配置文件，但需要手工调整参数。

;; Oracle 参考配置
{:pool-spec {:username "username"
             :password "password"
             :min-idle 5 ;; 空闲期间最小连接数
             :max-pool-size 100
             :adapter "oracle"
             :database-name "orcl"
             :server-name "192.168.18.12"
             :port-number 1521
             :driver-type "thin"
             }
 ;; dbtype用来根据不同的数据库调整底层生成的sql，特别是分页语句、insert的id返回
 :db-spec {:db-type :oracle<12c
           :sql-param-adapter {{name}}.db.db-adapter
           :return-keys ["ID"]}}

;; H2 参考配置
#_{:pool-spec {:jdbc-url "jdbc:h2:./env/dev/db/dev_user.db"
               :min-idle 5 ;; 空闲期间最小连接数
               :max-pool-size 100
               }
   :db-spec {:db-type :h2}}

;; mysql 参考配置
#_{:pool-spec {:jdbc-url "jdbc:mysql://192.168.18.17:13306/hrms?useSSL=false"
               :username "username"
               :password "password"
               :min-idle 5 ;; 空闲期间最小连接数
               :max-pool-size 100
               }
   :db-spec {:db-type :mysql}}

;; postgresql 参考配置
#_{:pool-spec {:adapter "postgresql"
             :username "username"
             :password "password"
             :database-name "database"
             :server-name "localhost"
             :port-number 5432}
   :db-spec {:db-type :postgres
             :sql-param-adapter {{name}}.db.db-adapter
           :return-keys ["ID"]}}

License

Distributed under the Eclipse Public License either version 1.0