Level up by diving down: eight critical Clojure libraries

之前在「我的 Clojure 學習之路」一文，我分析了自己過去學習的五個階段：

1. Before knowing Clojure
2. Clojure Basic
3. Tried a lot of libraries 
4. Selected Libraries
5. Level up by diving down

而在第五個階段，其實有一個很大的挑戰：「如果要 diving down 的話，要選什麼函式庫來 diving down ？」這個問題，透過 LLM 的協助，我整理出了以下的清單。這八個函式庫有以下的特性：

(a) 它們非常常用。如果你開發 web application 沒有用到它，八成是因為你用了替代方案。那你要不要質疑一下你的替代方案？
(b) 它們的設計根本就是經典。

很遺憾的事情是，我本人至今也還沒有研究完畢。我的學習過程一直沒有一套有系統的教材，是在前進之中思考合理的教材。

總之，清單如下：

   1. `weavejester/integrant`:

       * 角色: 應用程式生命週期管理、依賴注入 (DI)。

       * 啟發性: 教你如何將整個系統看作是資料。你用一個 map 來描述系統的所有元件（資料庫連線池、Web 伺服器、設定）以及它們之間的依賴關係。integrant 負責根據這個「藍圖」來啟動和關閉所有東西。這是「資料導向程式設計」在宏觀架構層面的終極體現。

   2. `juxt/aero`:

       * 角色: 設定管理。

       * 啟發性: 教你如何讓設定檔本身也變得可程式化。透過 EDN 的標籤 (#env, #ref)，你可以建立出動態、可組合、且不會洩漏密碼的設定檔。它完美地展示了利用 Clojure Reader 的能力來解決一個普遍存在的問題。

   3. `ring-clojure/ring`:

       * 角色: HTTP 抽象層的基石。

       * 啟發性: Clojure 哲學的化身。它將複雜的 HTTP 請求/回應簡化為兩個 map，將橫切關注點（如日誌、Session）抽象為 middleware（高階函式）。研究 Ring，你就能理解組合性(composability) 的力量，以及如何用簡單的資料結構來為複雜的系統建立模型。

   4. `metosin/reitit`:

       * 角色: 路由 (Routing)。

       * 啟發性: 教你如何將路由表也視為資料。你用一個 vector of vectors 來定義整個 API 的端點、HTTP 方法、處理器以及中介軟體。這種資料導向的方法不僅性能極高，而且讓路由的組合、生成和內省 (introspection) 變得輕而易舉。它完美地展示了如何用資料結構來取代複雜的 DSL 或巨集。

   5. `metosin/malli`:

       * 角色: 資料規格定義、驗證與轉換 (Data Schema, Validation & Coercion)。

       * 啟發性: 教你如何用資料來描述資料的形狀。malli 讓你用 Clojure 的資料結構來定義你系統中所有資料的規格。這份單一的「規格資料」可以被多種方式使用：驗證 API 輸入、從字串自動轉換為 int 或 uuid、產生 OpenAPI/Swagger 文件、甚至進行生成式測試。它是一個典型的「一份定義，多種用途」的範例。

   6. `buddy`:

       * 角色: 身份驗證與授權。

       * 啟發性: `protocol` 和策略模式 (Strategy Pattern) 

         的最佳教材。它定義了一個抽象的驗證協議，然後允許你插入任何具體的驗證策略（Session, JWT Token 等）。它完美地展示了如何設計一個可擴展、可插拔的系統，將「做什麼」與「如何做」徹底分離。

   7. `seancorfield/honeysql`:

       * 角色: SQL 查詢產生器。

       * 啟發性: 再次展示了「將程式碼表示為資料」的思想。你不是在拼接字串，而是在建構描述 SQL 查詢的 Clojure map 和 vector。這使得動態產生複雜查詢變得極其安全和容易組合，徹底消除了 SQL 注入的風險。

   8. `seancorfield/next-jdbc`:

       * 角色: 資料庫存取。

       * 啟發性: 教你如何為 Java API 建立一個更符合 Clojure 習慣的介面卡 (Adapter)。它透過 protocol (ReadableColumn, SettableParameter) 讓你可以擴展它，使其能處理自訂的資料類型。同時，它的函數式、基於 Reducer 的資料處理方式也極具啟發性，展示了如何將 I/O 操作與純粹的資料轉換優雅地結合起來。

Luarocks 與 Neovim

最近我遇到了一個挑戰：

> 如果使用 luarocks 安裝了 lua-cbor 的話，neovim 裡寫的 lua script 可以使用 lua-cbor 嗎？

答案是：預設不行，要做一些調整。

由於我的 luarocks 也是用 homebrew 去安裝的，而預設的 luarocks 它依賴的 lua interpreter 跟 neovim 預設依賴的 lua interpreter 不同。此外，neovim 的 package path 也很可能找不到 luarocks 的安裝 path 。

解法：
1. 重新安裝 luarocks ，下載 tar 包、重新編譯、安裝，讓它一定會依賴於 neovim 預設依賴的 lua interpreter ，即 luajit 
2. 設定 neovim 內部的 path ，使它可以讀得到 luarocks 的 module/library paths

< 重新安裝 luarocks 的指令 >
1. brew install luajit
2. wget https://luarocks.org/releases/luarocks-3.12.0.tar.gz
3. tar zxvf; cd luarocks-3.12.0
4. mkdir ~/.luarocks-luajit
5. ./configure \
  --with-lua=$(brew --prefix luajit) \
  --with-lua-include=$(brew --prefix luajit)/include/luajit-2.1 \
  --lua-suffix=jit \
  --prefix=$HOME/.luarocks-luajit
6. make && make install

注意：luarocks 的版本很重要，因為 luajit 有 65536 的限制。如果不是特定的 luarocks 版本，就會遇上這個錯誤："Error: main function has more than 65536 constants"。參考連結。


< 設定 neovim 內部的 path >
1. 在 lua 資料夾下生成一個檔案  luarocks.lua
2. 貼上以下的內容：

```
local function add_luarocks_paths()

  local luarocks_path = "/Users/laurencechen/.luarocks-luajit/share/lua/5.1/?.lua;/Users/laurencechen/.luarocks-luajit/share/lua/5.1/?/init.lua"

  local luarocks_cpath = "/Users/laurencechen/.luarocks-luajit/lib/lua/5.1/?.so"

  package.path = package.path .. ";" .. luarocks_path

  package.cpath = package.cpath .. ";" .. luarocks_cpath

end

return {add_luarocks_paths = add_luarocks_paths}

```
3. 在 init.vim 裡增加一行　lua require("luarocks").add_luarocks_paths()

neil --- 用來輔助編輯 deps.edn 檔的 CLI 工具

 neil 主要就四種常用的用法：

1. 尋找函式庫  neil dep search clojure
   
2. 新增函式庫  neil dep add org.clojure/clojure
   
3. 新增 Clojure 專案 neil new app dev.replware/myproject
   
4. 新增一些好用的輔助功能，比方說：test, nrepl, build (用來生成 uberjar) 等。
   neil add nrepl

其中，第一與第二種用法算是最常用的，因為 Clojure 的開發過程之中，就是會不停地尋找、新增 library 。而第三種用法裡，常用的有三種形式：

• neil new app [web application 專案名稱]
• neil new lib [library 專案名稱]
• neil new scratch [免洗專案名稱]

使用 compojure 時，需要特別注意的一個 helper - wrap-route

compojure 在決定接下來要使用哪一個 route 是單純地一個一個逐步比對，這個單純的作法多數時候沒有問題，但是一旦當某個 route 的 middleware 會有副作用的時候，這個作法就會出問題。

所幸，compojure 後來提供了一個 wrap-route 恰好可以處理這種情況。

HoneySQL 的 format

HoneySQL format 的 default 輸出是給 JDBC 處理的，所以當想讓它輸出給 SQL CLI 時，就要使用參數。

• 如果是使用 1.0 版本， format 的時候需要直接輸出可以被 SQL CLI 接受的字串形式，要使用 (format sql-hmap :parameterizer :none)
• 如果是使用 2.0 版本， format 的時候需要直接輸出可以被 SQL CLI 接受的字串形式，要使用 (format sql-hmap {:inline true})

如何使用 assert ，它跟 exception 不一樣喔！

參考連結

有兩個很常見的 Exception handling 不良風格

1. 濫用 :pre 和 :post 來做檢查，而不是使用 spec 或 malli

2. catch Throwable

```

(try

(assert false)

(catch Throwable e

"Barfoo"))

```

理由是類似的：

(1) Error => 程式有 bug ，設計時不考慮 catch 它。這種可以用 assert 。
(2) Exception => 程式沒有 bug 但是執行的時候遇到異常，設計時可以考慮 catch 它。

註：

(a) 用 : pre 和 : post 的話，會丟出 Error ，但是一般的格式錯誤是 Exception
(b) catch Throwable 的話，會 catch 到 Error ，但是我們只應該 catch Exception ，不應該 catch Error 。

Protocol 與 SPI (service provider interface)

最近才搞懂的東西：「在什麼樣的 context 之下，應該考慮使用 Protocol ？」

為什麼在用了 Clojure 這麼多年之後才搞懂，應該是因為我過去寫程式的時間裡，幾乎沒有在寫 Java 。

我在 Clojure 官方論壇找到了答案

答案是：Protocol 最適合用於做為 SPI (service provider interface)

protocol functions are better as SPI to hook in implementations than in API as functions consumers call directly. It is often helpful to wrap protocol methods with a normal function that can supply additional logic if needed around the call into the protocol.