moon-gql 项目申报书

基本信息

项目名称：moon-gql：MoonBit 轻量 GraphQL 请求与响应工具库

参赛者：laozhen

联系方式：1456905048@qq.com

GitHub 仓库链接：https://github.com/laozhen6/moon-gql

Gitlink 仓库链接：https://gitlink.org.cn/laozhen/moon-gql

项目方向：MoonBit 应用生态 / GraphQL 数据接口适配工具

是否为移植项目：否，原创项目

项目许可证：Apache-2.0

项目简介

moon-gql 是一个使用 MoonBit 编写的轻量 GraphQL 请求与响应工具库。项目面向需要在 MoonBit 程序中接入 GraphQL API 的开发者，提供标准 GraphQL HTTP JSON 请求体生成、operationName 与 variables 处理、GraphQL 响应解析、错误信息格式化以及简单 query / mutation 构造能力。

项目的目标不是实现完整 GraphQL 框架，而是提供一个边界清晰、易于复用的小型适配层。用户可以将 moon-gql 与其他 HTTP 库配合使用，用于调用 GitHub GraphQL API、Shopify GraphQL API、Hasura、Apollo Server 等 GraphQL 服务。

核心功能范围

提供 GraphQLRequest 请求对象，保存 GraphQL 查询字符串、operationName 和 variables。

支持将 GraphQLRequest 转换为标准 GraphQL HTTP JSON body，便于交给 HTTP 客户端发送。

支持 GraphQLRequest::to_json_string()，将请求对象序列化为 JSON 字符串。

支持 GraphQLRequest::has_variables()，用于判断请求是否携带 variables。

提供 GraphQLResponse 响应对象，解析标准 GraphQL 响应中的 data 和 errors 字段。

提供 GraphQLError 错误结构，保存 GraphQL 错误消息、路径和扩展信息。

支持 GraphQLResponse::is_success()，用于判断响应是否没有 GraphQL errors。

支持 GraphQLResponse::error_messages() 和 GraphQLResponse::first_error_message()，用于提取错误消息。

支持 GraphQLResponse::format_errors()，将 GraphQL errors 中的错误消息格式化为字符串。

支持 GraphQLError::format_path()，将错误路径格式化为点分字符串。

提供轻量 Query Builder，包含 field、query 和 mutation，用于生成常见 GraphQL query / mutation 字符串。

支持 Field::has_children() 和 Operation::to_request()，便于从字段树直接生成请求对象。

提供 cmd/main 最小运行示例，展示如何构造带 variables 的 GraphQL 查询请求。

提供 MoonBit 测试文件，覆盖请求序列化、响应解析和 query / mutation builder 等核心路径。

原创或参考说明

本项目为原创 MoonBit 工具库，不是对某个现有 GraphQL 库的直接移植。

项目实现参考 GraphQL 通用请求与响应约定，包括：

• GraphQL HTTP 请求体中常见的 query、operationName 和 variables 字段；
• GraphQL 响应中常见的 data 和 errors 字段；
• GraphQL error 中常见的 message、path 和 extensions 字段。

项目不复制第三方 GraphQL 库代码，不依赖特定服务端实现，也不绑定具体 HTTP 客户端。

与完整 GraphQL 框架相比的简化和重新设计

moon-gql 不实现完整 GraphQL parser，而是通过轻量 Query Builder 辅助生成常用 query / mutation 字符串。

moon-gql 不实现 GraphQL 服务端 resolver 框架，项目聚焦客户端请求构造和响应解析。

moon-gql 不实现 schema validator 或 codegen，避免在第一阶段引入过大的类型系统和生成流程。

moon-gql 不绑定具体 HTTP client，用户可以根据自己的运行环境选择合适的网络库。

moon-gql 使用 MoonBit 原生包结构、类型系统和测试方式组织代码，保持项目轻量、可读和易于继续扩展。

运行方式

如果需要从终端创建并打开同名 MoonBit 项目，可以先进入任意工作目录，然后执行：

moon new moon-gql
code moon-gql

进入项目目录后，可以运行示例：

moon run cmd/main

示例程序会输出一个 GraphQL 请求 JSON：

{"query":"query GetUser($id: ID!) { user(id: $id) { id name } }","operationName":"GetUser","variables":{"id":"42"}}

检查项目：

moon check

运行测试：

moon test

当前状态

项目已完成第一版核心功能实现。

当前本地状态：

• moon check 可通过；
• moon test 覆盖核心请求、响应和 builder 行为；
• moon run cmd/main 可输出 GraphQL 请求 JSON 示例；
• 根目录提供 Apache-2.0 许可证；
• GitHub / Gitlink 仓库链接已补充；
• 后续可继续扩展 HTTP client 适配、schema introspection 辅助解析和更完整的 builder 能力。