Clojure GraphQL API 实战：lacinia、Schema、Resolver 与权限

(require '[com.walmartlabs.lacinia :refer [execute]]
         '[com.walmartlabs.lacinia.schema :as schema])

(def order-schema
  {:objects
   {:Order {:fields {:id {:type 'String}
                     :total {:type 'Float}
                     :items {:type '(list :Item)}}}
    :Item  {:fields {:id {:type 'String} :price {:type 'Float} :qty {:type 'Int}}}}
   :queries
   {:order {:type :Order
            :args {:id {:type 'String!}}
            :resolve order-resolver}}}})

(def compiled-schema (schema/compile order-schema))
;; 执行查询
(execute compiled-schema {:query "{ order(id: \"42\") { id total } }"})

;; 标量类型
'String 'Int 'Float 'Boolean 'ID

;; 非空与非空列表
'String!              ;; 非空标量
'(list :Order)        ;; 列表
'(list :Order!)       ;; 非空元素的列表
'(:non-null (list :Order)) ;; 非空列表

;; 枚举
{:enum :OrderStatus {:values #{:created :paid :shipped}}}

;; 接口/联合（多态）
{:interfaces {:HasPrice {:fields {...}}}
 :unions     {:SearchResult {:members [:Order :Item]}}}

;; 查询级 resolver：拿到查询参数 → 返回对象
(defn order-resolver
  [context args value]      ;; context 全局, args 参数, value 父值
  (get-order (:id args)))   ;; 返回 Order 对象

;; 字段级 resolver：父对象 → 解析子字段
;; :items 字段的 resolver
(defn order-items-resolver
  [ctx args order]
  (get-items (:id order)))  ;; 从父 order 取 items

;; 返回 nil → 字段为 null（可按 Schema 非空规则报错）
;; 抛出异常 → 该字段错误（GraphQL 部分成功：兄弟字段照常）
(defn order-resolver [ctx args _]
  (if-let [o (get-order (:id args))]
    o
    (throw (ex-info "order not found" {:code :not-found}))))
;; 查询一个字段失败不影响同层其他字段 → GraphQL 的「部分结果」特性

;; 方案 1：batch resolver（lacinia 支持 :batch true）
;; :items 用批量解析：一次拿所有订单的 items
{:objects {:Order {:fields {:items {:type '(list :Item)
                                    :batch true      ;; 批量
                                    :resolve order-items-batch}}}}}

;; 方案 2：DataLoader 式批处理（在 resolver 里自己聚合）
(defn order-items-batch [ctx args orders]
  (let [ids (mapv :id orders)]
    (batch-get-items ids)))   ;; 一次 DB 查询，按 order 分组返回

;; 方案 3：预加载/joins（数据库层一次查出嵌套）

{:mutation
 {:create-order {:type :Order
                 :args {:items {:type '(list :OrderItemInput)!}}
                 :resolve create-order-mutation}}}

GraphQL 变更的约定：
  1. 变更显式、串行执行（GraphQL 不保证并发）
  2. 返回「变更后的实体」而非仅成功标志
  3. 输入类型（Input）与输出类型分离
  4. 事务：整个 resolver 内一个数据库事务
  5. 幂等键：重试安全

(defn create-order-mutation [ctx args _]
  ;; 一个事务内完成创建
  (with-open [conn (db/get-conn)]
    (db/with-transaction [tx conn]
      (let [order (insert-order! tx (:items (:input args)))]
        (log-order-created! order)
        order))))    ;; 返回新建的 Order

;; 服务入口：解析请求头 → 构造 context
(defn graphql-handler [req]
  (let [ctx {:auth (authenticate req)}]    ;; 身份注入 context
    (execute compiled-schema {:query (:query (:body req))
                              :variables (:variables (:body req))
                              :context ctx})))

;; 在 resolver 里用 context 校验
(defn order-resolver [ctx args _]
  (when-not (authorized? (:auth ctx) :read-order)
    (throw (ex-info "forbidden" {:code :forbidden})))
  (get-order (:id args)))

;; 或：用「受保护 resolver」包装
(defn with-role [role f]
  (fn [ctx args value]
    (when-not (has-role? (:auth ctx) role)
      (throw (ex-info "forbidden" {:code :forbidden})))
    (f ctx args value)))

{:subscriptions
 {:orderUpdated {:type :Order
                 :resolve order-updated-resolver}}}
;; 搭配推送传输（如 WebSocket），lacinia 支持 streaming

订阅流程：
  客户端订阅 orderUpdated
  服务端在订单变更时「推送」更新给订阅者
  → 实时场景：库存变化、订单状态、协作编辑

订阅的陷阱：
  - 连接管理（重连、心跳、断线恢复）
  - 推送频率控制（节流/合并）
  - 订阅者的身份权限（订阅前校验）
  - 大规模订阅的扇出（fan-out）
→ 实时是「推送」，比「拉取」多一层连接与状态管理

不是「二选一」：
  - 对外 BFF：GraphQL 聚合多个 REST 服务
  - 对内核心：REST/内部 API 保持简单
  - 渐变迁移：新功能 GraphQL，存量 REST 不动
→ 常见做法：GraphQL 做「前端的取数层」，REST 做「服务的接口层」

;; GraphQL resolver 内部调 REST/微服务
(defn order-resolver [ctx args _]
  (let [svc (rest-call! :order-service (:id args))]
    (normalize svc)))   ;; REST 响应 → GraphQL 对象
;; 好处：客户端一次请求，后端聚合多个服务
;; 代价：GraphQL 层成为「编排中心」，复杂度集中

;; 1. 深度限制（limit depth）
;; 实现：自定义校验器，遍历字段深度 > N 拒绝

;; 2. 复杂度限制（cost per field）
;; 每个字段给成本，总成本超限拒绝
(def field-cost {:Order 5 :Item 2 :reviews 10})

;; 3. 查询结果条数上限
;; 列表字段返回前截断（maxItems）

;; 三者结合：深度限制防嵌套、复杂度防昂贵字段、条数防巨大列表