Phrase 项目教程

Phrase 项目教程

phrase Clojure(Script) library for phrasing spec problems. 项目地址: https://gitcode.com/gh_mirrors/phr/phrase

1. 项目介绍

Phrase 是一个 Clojure(Script) 库，专门用于将 spec 问题转换为人类可读的消息。它的主要目的是在表单验证等场景中，帮助开发者生成易于理解的错误提示信息。Phrase 的设计理念是针对特定问题生成定制化的消息，而不是像 Expound 那样生成通用的消息。生成的消息主要面向应用程序的最终用户，而不是开发者。

2. 项目快速启动

安装

要安装 Phrase，只需将以下依赖项添加到你的项目中：

[phrase "0.3-alpha4"]

使用示例

假设你想要验证密码，密码必须是至少 8 个字符的字符串。你可以定义如下 spec：

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

(s/def ::password #(<= 8 (count %)))

执行以下代码将返回一个 spec 问题：

(s/explain-data ::password "1234")

Phrase 可以帮助你将这些问题映射转换为最终用户可以理解的消息。你可以定义一个 phraser 来处理这个问题：

(require '[phrase.alpha :refer [defphraser]])

(defphraser #(<= min-length (count %)) [_ _ min-length]
  (str "请至少使用 " min-length " 个字符"))

然后使用 phrase-first 函数来生成消息：

(require '[phrase.alpha :refer [phrase-first]])

(phrase-first [] ::password "1234")
;; 返回 "请至少使用 8 个字符"

3. 应用案例和最佳实践

表单验证

Phrase 最常见的应用场景是表单验证。通过定义多个 phraser，你可以为不同的验证条件生成定制化的错误消息。例如，验证密码的长度和复杂性：

(s/def ::password (s/and #(<= 8 (count %) 256)
                        #(re-find #"\d" %)
                        #(re-find #"[a-z]" %)
                        #(re-find #"[A-Z]" %)))

(defphraser #(<= lo (count %) up) [_ [:keys [val]] lo up]
  (str "长度必须在 " lo " 和 " up " 之间，但实际长度为 " (count val)))

(defphraser #(re-find re %) [_ _ re]
  (str "必须包含至少一个 "
       (case (str/replace (str re) #"/" "")
         "\\d" "数字"
         "[a-z]" "小写字母"
         "[A-Z]" "大写字母")))

国际化支持

Phrase 支持通过上下文生成国际化消息。你可以定义不同的 phraser 来处理不同的语言环境：

(defphraser #(<= min-length (count %)) [context _ min-length]
  (case (:lang context)
    :en (str "Please use at least " min-length " characters")
    :zh (str "请至少使用 " min-length " 个字符")))

4. 典型生态项目

Expound

Expound 是另一个 Clojure 库，旨在生成更易读的 spec 问题消息。与 Phrase 不同，Expound 的目标用户是开发者，而不是最终用户。Expound 通过提供更详细的错误信息来帮助开发者快速定位和修复问题。

Planck

Planck 是一个用于 ClojureScript 的独立 REPL 和脚本运行时。你可以使用 Planck 来快速测试和运行 Phrase 代码，而无需启动完整的 Clojure 环境。

boot -d phrase:0.3-alpha4
plk -cp `boot show --deps | tr '\n' ':'`

通过这些工具，你可以更高效地开发和测试 Phrase 应用。

phrase Clojure(Script) library for phrasing spec problems. 项目地址: https://gitcode.com/gh_mirrors/phr/phrase