Elm：dillonkearns/elm-graphql

项目简介

dillonkearns/elm-graphql 是一个为 Elm 语言设计的 GraphQL 类型安全客户端库，同时配套提供命令行代码生成器（Code Generator）。它能够基于 GraphQL 端点的 Schema（或 GraphQL 查询文档）自动生成类型安全的 Elm 代码，使得在 Elm 中请求 GraphQL API 时，编译器能够在开发阶段捕获查询中可能存在的错误，例如字段拼写错误、类型不匹配或查询结构无效等问题。

核心特性

• 端到端类型安全：生成的 Elm 代码将 GraphQL 查询结果映射为 Elm 的类型系统，所有字段名、类型、可选性和嵌套结构与服务端 Schema 严格对应，无需手写任何类型定义。
• 命令行代码生成器：通过简单命令即可从 GraphQL 端点或本地 .graphql 文件生成 Elm 模块，持续集成或本地开发均可轻松接入。
• 编译期查询校验：由于生成的代码内嵌了 GraphQL 查询的结构信息，任何不合法或与 Schema 不一致的查询都会导致 Elm 编译失败，而不是在运行时才暴露问题。
• 灵活的使用方式：支持两种代码生成模式：
  • 基于 Schema 的生成：从 GraphQL Schema 生成完整的 Elm 类型模块，适合需要动态拼装查询的场景。
  • 基于文档的生成（GraphQL Document 模式）：从 .graphql 查询文件生成调用函数，每个查询对应一个 Elm 函数，直接返回解析好的数据，逻辑更为集中。
• 与现代 Elm 生态兼容：支持 Elm 0.19 及以上版本，与 elm/http、elm/json 等官方库无缝配合，也可与 elm-graphql 的运行时库（即本仓库）结合使用。

工作原理

1. 用户提供 GraphQL 端点 URL（如 https://api.example.com/graphql）或本地 Schema 文件。
2. elm-graphql 代码生成器拉取并解析 Schema（或查询文档）。
3. 生成一个或多个 Elm 模块，包含：
   • 所有自定义类型（Object、Union、Enum、Scalar 等）对应的 Elm 类型别名和自定义类型。
   • 每个 GraphQL 类型的选择集（Selection）构造器。
   • 针对查询、变更（Mutation）和订阅（Subscription）的请求构建函数。
4. 在应用代码中，用户使用生成的选择集构造器构建查询，并通过 GraphQL 客户端发起请求，返回的结果自动解包为 Elm 类型。

快速上手

1. 安装 CLI 工具

npm install -g elm-graphql

或使用 npx：

npx elm-graphql --help

2. 生成 Elm 代码

从远程端点生成：

elm-graphql https://api.example.com/graphql --base elm-graphql

从本地 Schema 文件生成：

elm-graphql schema.graphql --base elm-graphql

3. 在 Elm 中使用

假设已生成了 Graphql.Query 等模块，定义查询：

import Graphql.Query exposing (Query)
import Graphql.SelectionSet exposing (SelectionSet)
import Github.Query


type alias Repo =
    { name : String
    , owner : String
    }


repoSelection : SelectionSet Repo Github.Query.Repo
repoSelection =
    Github.Query.repo "elm-graphql"
        { owner = "dillonkearns" }
        Repo
        |> Graphql.SelectionSet.map
            (\repo ->
                { name = repo.name
                , owner = repo.owner.login
                }
            )

构建请求并通过 HTTP 发送：

query : SelectionSet Repo RootQuery
query =
    Github.Query.repo "elm-graphql" { owner = "dillonkearns" } repoSelection


makeRequest : Cmd Msg
makeRequest =
    query
        |> Graphql.Http.queryRequest "https://api.github.com/graphql"
        |> Graphql.Http.send (RemoteData.fromResult >> GotRepo)

典型应用场景

• 需要严格类型约束的 Elm 前端应用：当你希望编译器在开发期拦截所有 GraphQL 相关的类型错误时。
• GraphQL API 版本迭代频繁的项目：当 Schema 更新时，重新运行代码生成器即可让所有不匹配的查询在编译期暴露出来。
• 团队协作：使用基于文档的生成模式时，后端和前端可共同维护 .graphql 查询文件，作为唯一的接口契约。

类似项目对比

相关资源

• GitHub 仓库：dillonkearns/elm-graphql
• 官方文档与示例：https://dillonkearns.github.io/elm-graphql/
• Elm Package 页面：https://package.elm-lang.org/packages/dillonkearns/elm-graphql/latest/

总结

dillonkearns/elm-graphql 是目前 Elm 生态中最成熟、最广泛使用的 GraphQL 类型安全解决方案。它将 GraphQL 的优势与 Elm 的强类型系统深度结合，大幅提升了前端代码的可靠性和可维护性。如果你正在使用 Elm 构建对数据准确性要求较高的应用，这个项目值得优先考虑。