Clojure REST API 设计实战：reitit、coercion、错误模型与文档

(require '[reitit.ring :as ring]
         '[reitit.coercion.malli :as malli])

(def app
  (ring/ring-handler
   (ring/router
    [["/api/orders" {:get  {:handler list-orders
                            :coercion malli/coercion
                            :parameters {:query [:map [:page int?] [:size int?]]}}
                     :post {:handler create-order
                            :coercion malli/coercion
                            :parameters {:body [:map [:items vector?]]}}}]
     ["/api/orders/:id" {:get  {:handler get-order
                                :parameters {:path [:map [:id int?]]}}
                         :put  {:handler replace-order
                                :parameters {:path [:map [:id int?]]
                                             :body [:map [:status keyword?]]}}}]])
   (ring/routes (ring/create-default-handler)))))

;; Malli schema 定义参数
(def OrderParams
  [:map {:closed true}
   [:id int?]
   [:status [:enum :created :paid :shipped]]
   [:total pos?]])

;; 校验结果：合法返回 coerced 值，非法返回错误详情
;; {:data {:id 42}}  → {:data {:id 42}}（id 从 "42" 转成 42）

:parameters {:path   [:map [:id int?]]}    ;; 路径参数 /orders/42
             :query  [:map [:page int?]]    ;; 查询参数 ?page=2
             :body   [:map [:name string?]] ;; 请求体
             :header [:map [:x-api-key string?]]} ;; 请求头

;; 统一错误响应结构
{:error {:code    :order-not-found
         :message "订单 42 不存在"
         :status  404
         :fields  nil}}          ;; 校验错误时的字段详情

;; 对应 HTTP 状态码
;; 400 参数不合法 → {:error {:code :bad-request ...}}
;; 404 资源不存在 → {:error {:code :not-found ...}}
;; 422 业务冲突   → {:error {:code :insufficient-stock ...}}

;; 统一错误响应中间件：把业务异常映射成结构化错误
(defn error-middleware [handler]
  (fn [req]
    (try (handler req)
         (catch ExceptionInfo e
           (let [{:keys [code status message]} (ex-data e)]
             {:status (or status 500)
              :body   {:error {:code code :message message}}}))
         (catch Exception _        ;; 未预期异常，记录并返回 500
           {:status 500 :body {:error {:code :internal :message "internal error"}}})))))

(throw (ex-info "订单已支付，不能重复支付"
                {:code :already-paid :status 409}))

;; cursor 分页：按 id 游标，天然稳定
;; 请求  ?after=41&size=20
;; 查询  WHERE id > 41 ORDER BY id LIMIT 21   (多取 1 条判断有没有下一页)
;; 响应  {:data [...] :next "/api/orders?after=61&size=20"}

;; 白名单
(def ^:private sortable #{:created-at :total :status})
(def ^:private filterable #{:status :user-id})

;; 组装查询前先校验参数在白名单内，超界返回 400

;; 解析 Authorization: Bearer <jwt>
(defn jwt-middleware [secret]
  (fn [handler]
    (fn [req]
      (if-let [token (some-> (get-in req [:headers "authorization"])
                             (string/replace #"^Bearer " ""))]
        (try
          (let [claims (jwt/verify token secret)]
            (handler (assoc req :claims claims)))
          (catch Exception _
            {:status 401 :body {:error {:code :unauthorized
                                        :message "token invalid or expired"}}}))
        {:status 401 :body {:error {:code :missing-token :message "missing token"}}}))))

;; 权限校验：基于 claims 里的角色
(defn require-role [role handler]
  (fn [req]
    (if (contains? (set (:roles (:claims req))) role)
      (handler req)
      {:status 403 :body {:error {:code :forbidden :message "insufficient role"}}})))

(ring/router
 [["/api/v1/orders" {:get ...}]
  ["/api/v2/orders" {:get ...}]])

;; 集成 swagger-ui
(require '[reitit.openapi :as openapi])
(ring/router [["/api/orders" {:get {...} :post {...}}]
              ["/openapi.json" {:get {:handler (openapi/create-openapi-handler)}}]]
             {:data {:openapi {:info {:title "Orders API" :version "1.0.0"}}}})

;; 用 Malli/spec 生成合法参数 → 打 handler → 断言响应也符合 schema
(deftest order-api-contract-test
  (testing "POST /api/orders 契约"
    (let [body (gen/generate (s/gen OrderSchema))]
      (let [res (app {:uri "/api/orders" :request-method :post
                      :body (json/write-str body)})]
        (is (= 201 (:status res)))))))

;; 超时：对下游调用设超时（网络库参数）
;; http-kit 请求超时 5s，超时即 504

;; 限流：令牌桶/滑动窗口
;; 简单实现：原子计数器 + 窗口时间
(defonce ^{:doc "per-user rate limiter"}
  limits (atom {}))

;; 异步 handler：立即返回 202 + 任务 ID，结果轮询/回调
(defn async-create-report [req]
  (let [task-id (submit-task! (:body (:data req)))]
    {:status 202
     :body   {:task-id task-id :status "queued"}
     :headers {"Location" (str "/api/tasks/" task-id)}}))

;; ETag：内容 hash，客户端 If-None-Match 命中 → 304
{:status 200
 :headers {"ETag" (etag-for data)
           "Cache-Control" "private, max-age=60"}
 :body data}