Haskell：morpheus-graphql-client（强类型客户端）

graphql-github-io-zh-Hans生态项目与库

Haskell：morpheus-graphql-client（强类型客户端）

简介

morpheus-graphql-client 是 morpheus-graphql 项目的一部分，为 Haskell 提供了一套强类型的 GraphQL 客户端解决方案。它利用 Haskell 强大的类型系统，在编译期对查询进行验证和类型推断，从而保证客户端与服务器之间的数据交互安全可靠。

该库的核心理念是：查询即类型。通过将 GraphQL 查询与 Haskell 类型绑定，开发者不再需要手动解析 JSON 或处理运行时错误，所有类型不匹配的问题都能在编译阶段被捕获。

主要特性

编译期查询校验：查询中的字段、参数、类型错误都会在编译时暴露，而不是等到运行时才失败。
自动类型推导：从 GraphQL 查询中自动生成对应的 Haskell 数据类型，无需手写繁琐的解析代码。
类型安全响应：服务器返回的数据直接映射为强类型 Haskell 值，消除对 Value 的显式模式匹配。
与 morpheus-graphql 服务端无缝集成：服务端和客户端可共享 Schema 定义，保障两端一致性。
纯函数式设计：基于 IO 和 Monad 抽象，自然融入 Haskell 生态。

安装

通过 Hackage 或 GitHub 引入依赖：

yaml 复制代码

# package.yaml 或 cabal 文件
dependencies:
  - morpheus-graphql-client

使用 stack 或 cabal 安装：

bash 复制代码

cabal update && cabal install morpheus-graphql-client

快速上手

以下示例展示如何定义一个强类型查询并发送请求。

1. 定义查询

使用 graphql 准引用器（QuasiQuoter）编写查询，并指定返回类型：

haskell 复制代码

{-# LANGUAGE QuasiQuotes #-}
{-# LANGUAGE TypeApplications #-}

import Morpheus.GraphQL.Client (graphql)
import Data.Aeson (Value)

-- 定义查询，使用 @ 符号指定返回类型（此处为 Value）
query :: Value
query = [graphql|
  query {
    hero {
      name
      friends { name }
    }
  }
|]

2. 执行请求

通过 morpheusGraphqlClient 请求函数发送查询到指定端点：

haskell 复制代码

import Morpheus.GraphQL.Client (morpheusGraphqlClient)
import qualified Data.Aeson as A

main :: IO ()
main = do
  -- 指定端点 URL 和查询
  result <- morpheusGraphqlClient "https://api.example.com/graphql" query
  case result of
    Left err -> putStrLn $ "请求失败: " <> show err
    Right val -> print (A.encode val)

3. 强类型自定义类型

更常见的是定义自己的数据类型，让库自动填充：

haskell 复制代码

{-# LANGUAGE DeriveGeneric #-}
{-# LANGUAGE OverloadedStrings #-}

import GHC.Generics (Generic)
import Morpheus.GraphQL.Client (graphql)
import Data.Aeson (FromJSON)

data Hero = Hero
  { name :: String
  , friends :: [Character]
  } deriving (Show, Generic)

data Character = Character
  { name :: String
  } deriving (Show, Generic)

instance FromJSON Hero
instance FromJSON Character

-- 查询返回 Hero 类型
query :: IO (Either String Hero)
query = morpheusGraphqlClient "https://api.example.com/graphql" [graphql|
  query {
    hero {
      name
      friends { name }
    }
  }
|]

工作原理

morpheus-graphql-client 在编译期通过 Template Haskell 解析 GraphQL 查询，并生成相应的 FromJSON 实例和查询构建代码。这意味着：

查询中的字段必须与服务器 Schema 匹配，否则编译失败。
响应 JSON 会被自动解析为类型安全的 Haskell 值。
嵌套对象可以直接通过记录语法访问。

与其它客户端对比

特性	morpheus-graphql-client	graphql-client	haskell-graphql-client
强类型编译期校验	✅ 原生支持	✅ 需额外模板	❌ 运行时解析
准引用器	✅ 内置	✅ 内置	❌
服务端集成	✅ 同一项目生态	❌	❌
文档质量	良好	一般	较差

生态与资源

GitHub 仓库：morpheusgraphql/morpheus-graphql
文档与示例：仓库 docs/ 目录及 examples/ 中的客户端示例
服务端支持：morpheus-graphql-server，可与你 favorite Web 框架集成（如 Servant、Warp）

总结

morpheus-graphql-client 是 Haskell 生态中少有的、真正将“强类型”贯穿整个 GraphQL 请求生命周期的客户端库。它有效减少了运行时错误，提升了代码可维护性，特别适合对类型安全要求极高的项目。如果你是 Haskell 开发者且正在寻找 GraphQL 客户端，这是一个值得尝试的选择。

帮助我们改进文档

发现翻译问题或内容错误？请告诉我们。