re-graph：Clojure/ClojureScript 的 GraphQL 客户端

项目简介

re-graph 是一个基于 ClojureScript 实现的 GraphQL 客户端库，提供了对 GraphQL 服务端的高效访问能力。其最显著的特点是内置了对 WebSocket 协议的支持，使得开发者可以轻松实现 GraphQL 订阅（Subscriptions）等实时功能，而不仅仅是普通的查询（Query）和变更（Mutation）。

该项目由开发者 oliyh 创建并维护，在 GraphQL 生态中为 Clojure 开发者提供了一套完整的、与 ClojureScript 无缝集成的客户端解决方案。

核心特性

• 使用 ClojureScript 编写：与前端 JavaScript 生态完美互操作，同时保留 Clojure 的函数式编程范式。
• WebSocket 支持：原生支持通过 WebSocket 建立持久连接，适用于实时通信场景。
• HTTP 支持：支持基于 HTTP POST 的标准 GraphQL 查询与变更操作。
• 完整 GraphQL 操作：支持查询、变更以及订阅三类核心操作。

技术栈

安装与配置

re-graph 可通过 Leiningen 或 Clojure CLI（tools.deps）添加依赖。

Leiningen：

[re-graph "0.1.0"]

Clojure CLI（deps.edn）：

{:deps {re-graph/re-graph {:mvn/version "0.1.0"}}}

快速上手

re-graph 以 re-frame 事件处理模型为核心，初始化时注册事件处理器，然后通过 dispatch 事件来发起请求。

1. 初始化

启用 HTTP 和 WebSocket 支持：

(ns my-app.core
  (:require [re-graph.core :as re-graph]))

;; 初始化 re-graph，启用 HTTP 与 WebSocket
(re-graph/init {:http-url "https://api.example.com/graphql"
                :ws-url "wss://api.example.com/graphql"})

2. 发起查询

使用 :graphql/query 事件发起 GraphQL 查询：

(re-frame/dispatch [:graphql/query
                    {:query "{ user(id: 1) { name email } }"
                     :id "get-user"}])

3. 发起变更

(re-frame/dispatch [:graphql/mutation
                    {:query "mutation UpdateUser($id: ID!, $name: String!) { updateUser(id: $id, name: $name) { id name } }"
                     :variables {:id 1 :name "New Name"}
                     :id "update-user"}])

4. 订阅实时数据

通过 WebSocket 订阅服务端数据变更：

(re-frame/dispatch [:graphql/subscribe
                    {:query "subscription { userUpdated { id name } }"
                     :id "user-updated"}])

5. 处理响应

注册响应事件处理器（以 :graphql/response 及其操作 ID 为关键字）：

(re-frame/reg-event-fx
  [:graphql/response "get-user"]
  (fn [{:keys [db]} [_ {:keys [data errors]}]]
    {:db (assoc-in db [:user] data)}))

WebSocket 支持详解

re-graph 的 WebSocket 实现遵循 GraphQL over WebSocket 协议，默认使用 graphql-ws 协议的兼容实现。其优势在于：

• 单一连接可复用，减少重复握手开销。
• 支持服务端推送数据，适用于通知、实时指标等场景。
• 自动处理连接状态，断线时可配合 re-frame 的 :graphql/ws-connected、:graphql/ws-disconnected 等事件实现重连逻辑。

API 概览

适用场景

• 需要 WebSocket 实时推送能力的 ClojureScript 单页应用（SPA）。
• 基于 re-frame 架构的前端项目。
• 需要与 GraphQL 服务端进行多种协议（HTTP/WS）交互的复杂客户端应用。

相关资源

• GitHub 仓库：oliyh/re-graph
• 依赖托管：Clojars（re-graph/re-graph）