clojure.spec库入门学习

时间 2019-11-30

标签 clojure.spec clojure spec 入门学习繁體版

原文原文链接

此文已由做者张佃鹏受权网易云社区发布。
html

欢迎访问网易云社区，了解更多网易技术产品运营经验。java

clojure是一门动态类型的语言，在类型检查方面并无c++/java这种静态类型语言好用，因此多个模块之间进行接口参数传递时，因为接口文档设计不严谨等缘由，总会发生接口参数类型错误，参数个数不正确等问题，给代码调试带来很大的挑战，所以在clojure中，对接口参数的进行类型和范围的检查是很是必要的。为此，咱们找到了clojure.spec这个库（ https://clojure.github.io/clojure/branch-master/clojure.spec-api.html ），正好能够解决以上问题。c++

1.clojure.spec库介绍：git

spec库主要是用来定义数据的结构和类型，并对其数据类型进行校验，而且能够根据spec生成对应的校验数据。要使用clojure.spec库，必须依赖最新的alpha版本的clojure：程序员

    [org.clojure/clojure "1.9.0-alpha10"]

由于clojure.spec库中有不少函数与clojure.core库中的函数重名（+、melt、def），因此不要使用use将整个库中的函数导入到当前命名空间下，而是要使用require，以下：github

    (require '[clojure.spec :as s])

2.specification的定义： 正则表达式

可使用s/def函数来给一个specification定义名字，由s/def定义的specification必须是namespace keyword（其中关于命名空间的关键字在这篇博客中有介绍：http://blog.csdn.net/zdplife/article/details/52304258 ）。最简单定义spec的方式就是：一个普通的谓词函数（接收一个参数，返回boolean类型）就能够做为一个specification：api

    ;;定义一个specification，只有偶数才能知足条件
    (s/def ::even-val even?)
    ;;=> :my-clj.core/even-val

specification也能够是多个specification的组合，最简单的组合函数是：s/and和s/or。s/and必须知足and下的全部specification的条件，组合的specification才会校验成功，以下：数组

    ;; ::and-test表示大于10的偶数
    (s/def ::and-test (s/and 
                        ::even-val
                        #(> % 10)
                        ))
    ;;=> :my-clj.core/and-test

s/or函数表示只要知足其中一个条件则成立，可是s/or函数必须在每个条件前面加一个:tag，这主要是为了在使用s/conform解析数据时，让数据更容易理解，便于肯定是知足那个条件。s/or的用法以下：安全

    ;;以下在谓词int?和string?前加了tag，tag主要是为了告诉咱们是知足哪一个条件
    (s/def ::or-test
      (s/or :int-number int?            :string-number string?))
    ;;=> :my-clj.core/or-test

3.经常使用解析spec的函数：

使用spec来解析和判断数据的函数主要有:s/valid? ,s/conform ,s/explain ,s/explain-str ,s/explain-data:

s/valid?函数:

s/valid?用来判断给定数据是否知足当前的specification，若是知足则返回true，不然返回false：

    (s/valid? ::even-val 10)
    ;;=> true
    (s/valid? ::even-val 11)
    ;;=> false

s/conform函数:

s/conform函数根据给定的specification和data参数，若是data符合specification校验条件，则根据specification的格式返回解析后的data，不然返回s/invalid：

    ;;若是知足条件则返回对应的解析数据，不然返回s/invalid
    (s/conform ::even-val 10)
    ;;=> 10
    (s/conform ::even-val 11)
    ;;=> :clojure.spec/invalid

    ;;conform并不是必定会返回与原有数据如出一辙的数据，它会根据对应specification会有所变化，好比or-test有:tag标志，因此返回的conform-data是一个vector,告诉咱们“hello world”是知足string条件，而不是int条件。
    (s/conform ::or-test "hello world")
    ;;=> [:string-number "hello world"]

s/explain系列函数：
根据explain的字面意思，很容易理解其做用是用来解释匹配失败的缘由，共有三个相关函数：s/explain函数将错误信息的缘由打印出来，并返回nil；s/explain-str会将s/explian打印出来的内容转换为字符串并返回；s/explain-data会将错误信息做为一个map数据结构返回。若是匹配成功，三个函数则都返回对应的success。

    ;;val=11不知足偶数的判断条件，根据返回结果，咱们很容易找到数据校验错误的位置
    (s/explain ::even-val 11)
    ;;打印结果：val: 11 fails spec: :my-clj.core/even-val predicate: even?
    ;;=> nil

    (s/explain-str ::even-val 11)
    ;;=> "val: 11 fails spec: :my-clj.core/even-val predicate: even?\r\n"

    ;;explain-data会把错误信息做为一个map返回
    (s/explain-data ::even-val 11)
    ;;=> #:clojure.spec{:problems [{:path [], :pred even?, :val 11, :via [:my-clj.core/even-val], :in []}]}

4.集合spec的生成：

咱们常常会遇到某个类型字段是属于某个集合中的任意一个元素，好比咱们定义一个聚合字段类型，该字段类型多是SUM/MAX/MIN/AVG/COUNT中的一个。为此咱们能够定义该字段的spec以下：

    ;;由于clojure中的set能够看成谓词使用，因此咱们很容易实现该字段spec的定义
    (s/def ::aggregator #{"SUM","AVG","CNT","CNTD","MAX","MIN"})

    (s/valid? ::aggregator "SUM")
    ;;=> true
    (s/valid? ::aggregator "SUM1")
    ;;=> false

5.数组spec的生成：

对于数组spec常用的生成函数主要有s/coll-of ,s/every ,s/tuple这三个函数：

s/coll-of函数：

coll-of函数生成的数组spec的特色是：该数组中的全部元素必须知足同一个条件。

 (s/def ::even-val even?)
 ;;=> :my-clj.core/even-val
 ;;定义一个数组的spec，该数组中的全部元素都必须是偶数
 (s/def ::coll-of-test (s/coll-of ::even-val))
 ;;=> :my-clj.core/coll-of-test

 (s/valid? ::coll-of-test [2 4 6])
 ;;=> true
 (s/valid? ::coll-of-test [1 4 6])
 ;;=> false
 ;;其中数组为空也知足条件
 (s/valid? ::coll-of-test [])
 ;;=> true

coll-of函数还接收可选的参数，用来对数组中的元素进行限制，可选参数有以下：

（1）:kind- - - -能够指定数组的类型，vector，set，list等；

（2）:count- - - -能够限定数组中元素的个数；

（3）:min-count- - - -限定数组中元素个数的最小值

（4）:max-count- - - -限定数组中元素个数的最大值

（5）:distinct- - - -数组没有重复的元素

（6）:into- - - -能够将数组的元素插入到[],(),{},#{}这些其中之一，主要是为了改变conform函数的返回结果

关于以上可选参数使用举例以下：

    ;;定义一个数组的spec，其中全部元素是偶数，这个数组是vector类型，共有4个元素，元素不能重复，conform结果放在set中：
    (s/def ::coll-of-test (s/coll-of even? :kind vector? :count 4 :distinct true :into #{}))
    ;;=> :my-clj.core/coll-of-test

    ;;知足条件
    (s/valid? ::coll-of-test [2 4 6 8])
    ;;=> true

    ;;用explain函数解释错误的缘由
    (s/explain ::coll-of-test [2 4 6 7])
    ;;In: [3] val: 7 fails spec: :my-clj.core/coll-of-test predicate: even?

    ;;list的数组不知足条件
    (s/explain ::coll-of-test '(2 4 6 8))
    ;;val: (2 4 6 8) fails spec: :my-clj.core/coll-of-test predicate: vector?

    ;;conform解析结果放在了一个set中
    (s/conform ::coll-of-test [2 4 6 8])
    ;;=> #{4 6 2 8}

s/every函数：

s/every函数与s/coll-of函数的做用相同，而且参数类型也相同。不一样的是：在有不知足条件元素的状况下，s/coll-of函数依然会检查每个元素并返回错误信息，而s/every函数只检查部分元素。因此s/every函数更适合数据量比较大的状况：

    ;;用s/coll-of和s/every函数定义做用相同的spec，都是检查数组是否所有为string类型的元素
    (s/def ::coll-of-test (s/coll-of string?))
    (s/def ::every-test (s/every string?))

    ;;在校验错误的状况下，every-test只返回前20个元素的错误信息
    (s/explain ::every-test (range 50))
    ;;In: [0] val: 0 fails spec: :my-clj.core/every-test predicate: string?
    ;;In: [1] val: 1 fails spec: :my-clj.core/every-test predicate: string?
    ;;...
    ;;In: [18] val: 18 fails spec: :my-clj.core/every-test predicate: string?
    ;;In: [19] val: 19 fails spec: :my-clj.core/every-test predicate: string?

    ;;而coll-of-test会返回全部不知足元素的校验错误信息
    (s/explain ::coll-of-test (range 50))
    ;;In: [0] val: 0 fails spec: :my-clj.core/coll-of-test predicate: string?
    ;;In: [1] val: 1 fails spec: :my-clj.core/coll-of-test predicate: string?
    ;;...
    ;;In: [48] val: 48 fails spec: :my-clj.core/coll-of-test predicate: string?
    ;;In: [49] val: 49 fails spec: :my-clj.core/coll-of-test predicate: string?

因此在须要肯定全部元素错误信息的状况下使用coll-of，而在大量数据的状况下，为了保证效率，使用every函数效果会更好。

s/tuple函数：

tuple函数与前两个函数不一样，它能够指定数组中每一个元素的类型，检查要求更严格苛刻，适合数组元素比较少且元素类型不是所有相同的校验：

    ;;能够指定一个数组中三个元素，类型分别为int，string，vector
    (s/def ::tuple-test (s/tuple int? string? vector?))

    (s/valid? ::tuple-test [1 "hello" [1 2 3]])
    ;;=> true
    (s/valid? ::tuple-test [1 "hello" 3])
    ;;=> false

6.map的spec生成：

对于map的spec生成函数主要有s/map-of, s/every-kv ,s/keys ,s/keys*

s/map-of函数：
s/map-of函数与s/coll-of函数做用相似，前两个参数分别是对key和value进行校验的spec，后面还能够跟着可选参数，与coll-of的可选参数同样，有：kind/count/min-count/max-count/distinct/into，其中kind默认状况下是map，若是是list和vector，则校验数据是[k v]的数组，map-of的用法以下：

    ;;用map-of定义一个spec，类型是[[k v]],k是关键字，v是字符串
    (s/def ::map-of-test (s/map-of keyword? string? :kind vector?))

    ;;由于不是vector形式的map，因此校验失败
    (s/explain ::map-of-test {:a 1 :b 2})    val: {:a 1, :b 2} fails spec: :my-clj.core/map-of-test predicate: vector?

    ;;知足条件返回success
    (s/explain ::map-of-test [[:a "hello"] [:b "world"]])
    ;;Success!

s/every-kv函数：

s/every-kv函数与s/map-of的区别就像s/every与s/coll-of函数的区别，s/every-kv函数适合数据量比较大的状况下，其参数格式与map-of函数的参数格式彻底同样，用法以下：

    ;;用every-kv定义一个spec，校验key为关键字，value为数字的map
    (s/def ::every-kv-test (s/every-kv keyword? number?))

    (s/explain ::every-kv-test {:a 1 :b 3.14})
    ;;Success!
    (s/explain ::every-kv-test {:a "hello" :b 3.14})
    ;;In: [:a 1] val: "hello" fails spec: :my-clj.core/every-kv-test at: [1] predicate: number?

s/keys函数：

s/keys函数比map-of函数和every-kv函数的限制更增强烈，能够分别对map中的每个value的进行限制，可是map的key必须是关键字。假设咱们定义一个person的数据结构以下：

    person：
        {            :name       string类型            :age        int类型且知足(< 0 age 100)            :gender     boolean类型            :spouse     （optional）string类型        
        }

以上定义的person数据结构有3个必选的字段（:name :age :gender）和1个可选择的字段（:spouse）,为了用keys定义person数据结构的spec，首先咱们须要根据person的key（key必须是关键字）来定义其对应value的校验spec，以下：

    ;;所定义的spec的名字必须与person中key的名字的一致
    (s/def ::name string?)
    (s/def ::age (s/and int? #(<= 0 % 100)))
    (s/def ::gender boolean?)
    (s/def ::spouse string?)

接下来咱们就可使用keys来定义person的spec了，用keys定义spec时，须要使用:req和:opt来指定哪些字段是必须的，哪些字段可选的，以下：

    ;;全部必选字段和可选字段的spec都必须在[]中列出来
    (s/def ::person1 
      (s/keys :req [::name ::age ::gender]
              :opt [::spouse]
              ))

这时若是使用::person1去校验任意一个知足条件的person数据结构都会出错:

    (s/explain ::person1 {:name "xiao ming"
                          :age 25
                          :gender false
                          :spouse "xiao hua"
                          })
    ;;val: {:name "xiao ming", :age 25, :gender false, :spouse "xiao hua"} fails spec: :my-clj.core/person1 predicate: (contains? % :my-clj.core/name)

根据以上错误信息咱们能够找到缘由，是由于该数据结构中不包含:my-clj.core/name字段。这是由于使用：req和：opt指定的字段要求被校验的map的key必须是namespace keyword，也就是说person数据结构中的key必须是namespace keyword。以下若是改为namespace keyword，返回结果则会成功：

    (s/explain ::person1 {::name "xiao ming"
                          ::age 25
                          ::gender false
                          ::spouse "xiao hua"
                          })
    ;;Success!

若是必须使用namespace keyword作map中的key会给咱们书写代码时带来不少困惑，幸亏keys函数还提供了另外两个字段:req-un/opt-un用来替换对应的req/opt，这样数据结构中的key就能够是全局的keyword了，以下：

    ;;使用标志req-un/opt-un来区别必须字段和可选字段
    (s/def ::person2 
      (s/keys :req-un [::name ::age ::gender]              :opt-un [::spouse]
              ))

    ;;这种状况下，普通的keyword就能够校验成功了。
    (s/explain ::person2 {:name "xiao ming"
                          :age 25
                          :gender false
                          :spouse "xiao hua"
                          })
    ;;Success!
    ;;由于:spouse字段是可选的，没有:spouse字段，依然会成功
    (s/explain ::person2 {:name "xiao ming"
                          :age 25
                          :gender false
                          })
    ;;Success!
    ;; :gender字段是必须有的，若是没有则会失败
    (s/explain ::person2 {:name "xiao ming"
                          :age 25
                          :spouse "xiao hua"
                          })
    ;;val: {:name "xiao ming", :age 25, :spouse "xiao hua"} fails spec: :my-clj.core/person2 predicate: (contains? % :gender)

须要注意的是，s/keys函数并无对不在req和opt中字段做限制。也就是说，若是person数据中多了一些其它不必的字段，校验也会成功：

    ;;虽然person的数据结构中多了一个color字段依然会成功，keys函数只会校验存在req和opt中的字段，会无视其余字段
    (s/explain ::person2 {:name "xiao ming"
                          :age 25
                          :gender false
                          :spouse "xiao hua"
                          :color "yellow"
                          })
    ;;Success!

这样设计的目的多是给予程序员更多选择的机会吧，可是在项目中，多余的字段老是会给咱们带来困惑和bug，因此为了将其字段限制在必定范围内，咱们能够定义一个对其keys进行限制的谓词函数以下：

    ;;定义一个谓词函数，mmap中的每一个key都必须在数组mkeys中
    (defn keys-validator? [mmap mkeys]
      (clojure.set/subset? (set (keys mmap)) (set mkeys)))

这样咱们就可使用keys-validator函数和s/keys一块儿对一个map数据结构的spec做更加严格的限制：

    ;;从新定义一个::person3,有三个必选字段和一个可选字段，以及全部字段必须在[:name :age :gender :spouse]中
    (s/def ::person3 
      (s/and
        (s/keys :req-un [::name ::age ::gender]                :opt-un [::spouse]
                )
        (fn [x] (keys-validator? x [:name :age :gender :spouse]))
        ))

    ;;成功校验用例
    (s/explain ::person3 {:name "xiao ming"
                          :age 25
                          :gender false
                          :spouse "xiao hua"
                          })
    ;;Success!

    ;;若是多了一个color字段会失败，提示不知足keys-validator这个条件
    (s/explain ::person3 {:name "xiao ming"
                          :age 25
                          :gender false
                          :spouse "xiao hua"
                          :color "yellow"
                          })
    ;;val: {:name "xiao ming", :age 25, :gender false, :spouse "xiao hua", :color "yellow"} fails spec: :my-clj.core/person3 predicate: (fn [x] (keys-validator? x [:name :age :gender :spouse]))

s/keys*函数：

s/keys函数与s/keys函数功能基本彻底一致，只是验证的数据格式不同而已，s/keys验证的是以{key value}形式表示的map，而s/keys验证的是数组形式[key value]，s/keys*的使用以下：

    ;;以keys*定义一个::person4.格式与::person2一致，只是keys换成keys*
    (s/def ::person4 
      (s/keys* :req-un [::name ::age ::gender]              :opt-un [::spouse]
              ))

    ;;这时候若是去校验一个{}形式的map会报错
    (s/explain ::person4
               {:name "xiao ming"
                :age 25
                :gender false
                :spouse "xiao hua"
                })

    ;;In: [0] val: [:name "xiao ming"] fails spec: :my-clj.core/person4 at: [:clojure.spec/k] predicate: keyword?

    ;;若是解释数组形式的key value则返回success！
    (s/explain ::person4
               [:name "xiao ming"
                :age 25
                :gender false
                :spouse "xiao hua"]
               )
    ;;Success!

7.spec中空值（null）的处理：

在定义数据接口时，常常遇到某个字段无值的特殊状况，在clojure空值用nil表示，对于某个可能为nil的字段的校验，clojure.spec中提供了s/nilable这个函数，接收一个spec参数，返回一个spec，表示该spec能够接收空值特殊状况：

    ;;若是咱们给person2中name字段为nil，校验则会出错
    (s/explain ::person2
               {:name nil
                :age 25
                :gender false
                :spouse "xiao hua"
                })
    ;;In: [:name] val: nil fails spec: :my-clj.core/name at: [:name] predicate: string?

    ;;当咱们把定义::name时，允许其为nilable，
    (s/def ::name (s/nilable string?))
    (s/def ::person5 
      (s/keys :req-un [::name ::age ::gender]              :opt-un [::spouse]
              ))

    ;;此时，即便name为nil，也会返回success
    (s/explain ::person2
               {:name nil
                :age 25
                :gender false
                :spouse "xiao hua"
                })
    ;;Success!

因此咱们能够根据接口定义要求合理的使用s/nilable来知足咱们的需求。

8.spec中命名冲突的处理：

当咱们使用"::"定义spec时，若是两个不一样的数据结构下某个字段名字相同，就会发生命名冲突的问题，好比咱们在定义person数据结构的基础上又定义了一个dog结构：

    dog：
    {
        :name string?
        :age int?  (< 0 age 20)
    }

对于dog中的:name字段，能够和person中的:name字段用同一个spec，由于他们描述一致，可是对于两个结构中age字段的范围不一致，这样就会致使命名冲突的问题。由于clojure.spec库中每定义一个spec的名字必须是namespace keyword，而这正是使用namespace keyword而不使用keyword的缘由，由于咱们能够在定义spec时选择为其指定命名空间的方式定义（http://blog.csdn.net/zdplife/article/details/52304258 ），其命名空间能够随意指定，该命名空间不必定存在也能够，所以就能够很好的解决该问题了：

    ;; ::person的定义
    (s/def :person/name string?)
    (s/def :person/age (s/and int? #(<= 0 % 100)))
    (s/def :person/gender boolean?)
    (s/def :person/spouse string?)
    (s/def ::person
      (s/keys :req-un [:person/name :person/age :person/gender]              :opt-un [:person/spouse]
              ))

    ;; ::dog的定义
    (s/def :dog/name string?)
    (s/def :dog/age (s/and int? #(<= 0 % 20)))
    (s/def ::dog
      (s/keys :req-un [:dog/name :dog/age]
              ))

    ;; 成功解决命名冲突，校验成功
    (s/explain ::person   {:name "xiao ming"
                           :age 25
                           :gender false
                           :spouse "xiao hua"
                           })
    ;; Success!
    (s/explain ::dog   {:name "du du"
                           :age 19
                           })
    ;; Success!

9.正则表达式在spec中的使用：

正则表达式在校验数据格式方面，有着其独特的优点。正好clojure中也有相关正则表达式的处理函数，常用的re-matches函数，能够构造一个正则表达式适配器（http://blog.csdn.net/zdplife/article/details/51868499），而该正则表达式适配器正好能够看成clojure.spec使用：

    ;;定义一个匹配移动电话号码的正则表达式
    (def reg-phone-num #"^1(3[0-9]|4[57]|5[0-35-9]|7[01678]|8[0-9])\d{8}$")

    ;;使用上述定义的正则表达式来定义一个spec
    (s/def ::phone-num #(re-matches reg-phone-num %))

    ;;号码正确，返回success
    (s/explain ::phone-num "15977765765")
    ;;Success!

    ;;号码错误，错误信息返回
    (s/explain ::phone-num "14988865765")
    ;;val: "14988865765" fails spec: :my-clj.core/phone-num predicate: (re-matches reg-phone-num %)

10.在接口函数中使用spec：

在函数中使用spec，最好的方式是利用在定义函数时的的输入输出条件检查（pre-condition/post-condition）,假设咱们定义一个接口函数transform-person，函数输入是一个person数据结构，输出是一个字符串，定义以下：

    ;;定义一个函数，用s/valid?函数对其输入和输出参数进行校验
    (defn transform-person [person]
      {:pre [(s/valid? ::person person)]       :post [(s/valid? string? %)]
       }
      (let [gender-str (if (:gender person) "a boy" "a girl")
            his-or-her (if (:gender person) "his" "her")
            ]
        (str (:name person) " is " gender-str ",and " his-or-her " age is " (:age person))
        ))
    ;;定义一个知足条件的person1
    (def person1
      {:name "xiao ming", :age 25, :gender false, :spouse "xiao hua"}
      )
    ;;定义一个不知足条件的person2
    (def person2
      {:name "liu wei", :age -10, :gender false, :spouse "xiao hua"}
      )

    ;;调用接口函数成功
    (transform-person person1)
    ;;=> "xiao ming is a girl,and her age is 25"

    ;;接口参数校验失败，抛出异常
    (transform-person person2)
    ;;AssertionError Assert failed: (s/valid? :my-clj.core/person person)  my-clj.core/transform-person (form-init1838625064402666216.clj:1)

11.总结：

本文主要介绍了clojure.spec库的一些基本函数的用法，其实这些函数对于普通的接口参数检测已经足够了，clojure.spec库中还有一些其它函数：alt函数/cat函数/melt函数，还可使用正则中的*/+/?等，这些函数也蛮好玩的，有兴趣的能够去试着玩一下，这边有介绍：http://clojure.org/guides/spec

免费体验云安全(易盾)内容安全、验证码等服务

更多网易技术、产品、运营经验分享请点击。