Clojure 函数式错误处理：Result、异常与结构化错误

;; 抛：中断执行流，向上传播
(throw (ex-info "余额不足" {:code :insufficient-funds :balance 10}))

;; 接：try/catch 捕获，或向上冒泡
(try
  (withdraw! account 100)
  (catch ExceptionInfo e
    (handle-failure (ex-data e))))

;; 不抛，返回「结果值」
(defn withdraw! [account amount]
  (if (<= amount (:balance account))
    {:status :ok   :data (update account :balance - amount)}
    {:status :err  :error {:code :insufficient-funds :balance (:balance account)}}))

;; 调用方显式解构处理
(let [{:keys [status data error]} (withdraw! account 100)]
  (if (= status :ok) data (report error)))

;; 异常不只消息，还有 data
(ex-info "订单创建失败"
         {:code :order-failed
          :order-id 42
          :cause :db-timeout})
;; (ex-data e) → {:code :order-failed :order-id 42 :cause :db-timeout}

;; 带 cause（原始异常链）
(ex-info "上游服务失败"
         {:code :upstream-error :svc :payment}
         original-exception)

;; 自定义异常类型：用 derive 建立层级
(derive ::business-error ::error)
(derive ::not-found ::business-error)
(derive ::insufficient-funds ::business-error)

;; 捕获时按层级判断
(catch clojure.lang.ExceptionInfo e
  (when (isa? (-> e ex-data :code) ::insufficient-funds)
    ...))

;; 定义一个简单的 Result 容器
;; {:status :ok :data v}  /  {:status :err :error e}

(defn ok  [v]   {:status :ok  :data v})
(defn err [e]   {:status :err :error e})

;; bind：ok 继续，err 短路（Monad 的 bind）
(defn >>= [result f]
  (if (= :ok (:status result))
    (f (:data result))
    result))    ;; err 直接透传，f 不执行

;; 用 >>= 串起可能失败的步骤，任一失败即短路
(-> (validate input)          ;; {:status :ok ...} 或 err
    (>>= validate-user)
    (>>= place-order)
    (>>= charge))

;; 全部 :ok → 拿到最终 data
;; 任一步 :err → 直接返回那个 err，后续不跑

(defn error-middleware [handler]
  (fn [req]
    (try (handler req)
         (catch ExceptionInfo e
           (let [{:keys [status code message]} (ex-data e)]
             {:status (or status 500)
              :body {:error {:code code :message message}}}))
         (catch Exception e
           (log/error e "unhandled")    ;; 记录原始异常
           {:status 500
            :body {:error {:code :internal :message "internal error"}}}))))

(defn safe-task [f]
  (try
    (f)
    (catch Exception e
      (log/error e "task failed")
      (retry-with-backoff! f))))   ;; 可恢复则重试

;; 输入校验放在函数最前，非法输入 → 结构化错误（不往下传）
(defn place-order [order]
  (let [spec-result (s/conform ::order-spec order)]
    (when (= ::s/invalid spec-result)
      (throw (ex-info "非法订单" {:code :invalid-input
                                  :problems (s/explain-data ::order-spec order)})))
    ...))

;; 开发期：instrument 让被校验的函数「参数不合法就抛」
;; （见 spec 篇：s/fdef + st/instrument）
;; 生产：合法参数照常，非法参数被 spec 拦截并报结构化错误

可重试的错误：
  网络抖动、临时超时、下游 503、锁竞争
不可重试的错误：
  参数非法（重试也没用）、权限不足、业务状态冲突
→ 判断标准：错误「会不会因为再试一次而消失」

;; 简单指数退避：1s 2s 4s ... 上限 + 抖动
(defn retry [f {:keys [max-attempts max-delay-ms]}]
  (loop [attempt 1]
    (let [res (try {:status :ok :data (f)}
                   (catch Exception e {:status :err :error e}))]
      (if (or (= :ok (:status res)) (>= attempt max-attempts))
        res
        (do (Thread/sleep (min (* 1000 (Math/pow 2 (dec attempt)))
                               max-delay-ms))
            (recur (inc attempt)))))))

;; 结构化日志：错误时带上错误码与上下文
(log/error {:event :order-failed
            :order-id 42
            :code :db-timeout
            :ex e})    ;; 堆栈保留，便于定位

可观测的错误指标：
  - 错误率（按错误码分组）
  - 重试次数分布（退避是否生效）
  - 超时错误趋势（下游健康度）
  - 未处理异常计数（边界兜底命中数）
→ 错误要有「看得见的量」：率、分布、趋势

;; 分层设计总结
;; ── 内部业务层：值化错误为主
(defn withdraw! [acct amount]
  (cond
    (nil? acct)        {:status :err :error {:code :not-found}}
    (> amount (:bal acct)) {:status :err :error {:code :insufficient}}
    :else              {:status :ok :data (update acct :bal - amount)}))

;; ── 编排层：短路链组合
(defn transfer! [from to amount]
  (-> (withdraw! from amount)
      (>>= #(deposit! to (:data %)))
      (>>= #(log-transfer! from to amount))))

;; ── 边界层：异常/错误统一转 HTTP
(defn transfer-handler [req]
  (let [result (transfer! ...)]
    (match result
      {:status :ok :data d}    {:status 200 :body d}
      {:status :err :error {:code :insufficient}} {:status 409 :body ...}
      {:status :err :error {:code :not-found}}    {:status 404 :body ...})))