graphql-server

概述

graphql-server是dictyBase的GraphQL服务器，基于Go语言开发，使用gqlgen工具生成代码以匹配gRPC模型。该服务器整合了用户、角色、权限、库存、订单等多种gRPC服务及publication API端点，提供统一的GraphQL查询和变更接口，并支持通过命令行进行配置与日志管理。

核心功能与特性

• 多服务集成：支持用户、角色、权限、库存、订单等多种gRPC服务，以及publication API端点
• 代码生成：基于gqlgen工具，通过GraphQL schema自动生成代码
• 灵活配置：支持通过命令行参数或环境变量配置各gRPC服务的主机、端口及API端点
• 日志控制：可配置日志输出格式（json/text）和日志级别（默认error）
• 命令行管理：提供简洁的命令行接口，支持启动服务器、查看帮助等操作

使用场景

作为后端GraphQL服务，适用于需要整合多种gRPC服务和API端点，提供统一数据查询与变更能力的场景，尤其适合dictyBase生态系统中需要处理用户、权限、库存等数据的应用。

使用方法

基本命令

NAME:
   graphql-server - graphql-server后端命令行工具

USAGE:
   graphql-server [全局选项] 命令 [命令选项] [参数...]

VERSION:
   1.0.0

COMMANDS:
     start-server  启动graphql-server后端服务
     help, h       显示命令列表或单个命令帮助

GLOBAL OPTIONS:
   --log-format value  日志输出格式，可选json或text（默认："json"）
   --log-level value   应用日志级别（默认："error"）
   --help, -h          显示帮助
   --version, -v       打印版本信息

子命令详解：start-server

start-server子命令用于启动GraphQL服务器，支持配置各gRPC服务连接参数及API端点：

NAME:
   graphql-server start-server - 启动graphql-server后端服务

USAGE:
   graphql-server start-server [命令选项] [参数...]

OPTIONS:
   --user-grpc-host value, --uh value        用户gRPC主机 [$USER_API_SERVICE_HOST]
   --user-grpc-port value, --up value        用户gRPC端口 [$USER_API_SERVICE_PORT]
   --role-grpc-host value, --rh value        角色gRPC主机 [$ROLE_API_SERVICE_HOST]
   --role-grpc-port value, --rp value        角色gRPC端口 [$ROLE_API_SERVICE_PORT]
   --permission-grpc-host value, --ph value  权限gRPC主机 [$PERMISSION_API_SERVICE_HOST]
   --permission-grpc-port value, --pp value  权限gRPC端口 [$PERMISSION_API_SERVICE_PORT]
   --publication-api value, --pub value      publication API端点（默认："[***]"） [$PUBLICATION_API_ENDPOINT]
   --stock-grpc-host value, --sh value       库存gRPC主机 [$STOCK_API_SERVICE_HOST]
   --stock-grpc-port value, --sp value       库存gRPC端口 [$STOCK_API_SERVICE_PORT]
   --order-grpc-host value, --oh value       订单gRPC主机 [$ORDER_API_SERVICE_HOST]
   --order-grpc-port value, --op value       订单gRPC端口 [$ORDER_API_SERVICE_PORT]

开发指南

依赖与Schema管理

gqlgen依赖GraphQL schema生成代码，schema文件存储在dictyBase/graphql-schema仓库，主要包含：

• query.graphql - 所有查询定义
• mutation.graphql - 所有变更定义
• scalar.graphql - 标量类型定义（如timestamp）

特定类别（如用户）的唯一类型和输入应放在同一目录下的独立schema文件中。

代码生成步骤

1. 更新gqlgen.yml：

   • 在schema:字段添加新schema文件路径
   • 添加自定义模型（如使用gRPC服务时，参考用户模型示例）

2. 运行生成命令：

   go generate ./...
   

   该命令会重建生成文件，可能需要几分钟。

3. 注意事项：

   • 新生成的解析器代码不含自定义包名，需手动添加（如generated包）：

     func (r *Resolver) User() generated.UserResolver {
         return &userResolver{r}
     }
     

   • 需比较新旧解析器差异，合并变更。

后续开发步骤

添加新schema并生成代码后，需进行以下重构：

1. 在registry.go中添加客户端常量
2. 若添加gRPC客户端，需在同一文件的ServiceMap中添加条目；若添加API端点，需更新RunGraphQLServer手动注册（参考Publication示例），并测试服务器初始化时的端点
3. 为客户端添加registry包方法（如GetUserClient）
4. 重构解析器：
   • 将共享解析器移至根resolver目录
   • 主生成函数（如Permission()）放入resolver.go并调整格式
   • 为每个客户端创建包含查询和变更方法的文件（参考permission.go），查询使用(q *QueryResolver)接收器，变更使用(m *MutationResolver)
5. 非共享解析器放入resolver子目录（参考user目录），必要时更新包名
6. 在main.go和validation中添加命令行标志
7. 填充解析器存根并在playground中测试

错误处理

使用errorutils包添加带自定义扩展的错误，便于前端处理，参考共享解析器示例。

文件夹结构

.
├── README.md
├── build
│   └── Dockerfile
├── cmd
│   └── graphql-server
│       └── main.go
├── deployments
│   └── charts
│       └── graphql-server
│           ├── Chart.yaml
│           ├── templates
│           │   ├── NOTES.txt
│           │   ├── _helpers.tpl
│           │   ├── deployment.yaml
│           │   └── service.yaml
│           └── values.yaml
├── go.mod
├── go.sum
├── gqlgen.yml
├── graphql-server
├── internal
│   ├── app
│   │   ├── server
│   │   │   └── server.go
│   │   └── validate
│   │       └── validate.go
│   ├── graphql
│   │   ├── generated
│   │   │   └── generated.go
│   │   ├── models
│   │   │   ├── models_gen.go
│   │   │   └── timestamp.go
│   │   └── resolver
│   │       ├── permission.go
│   │       ├── resolver.go
│   │       ├── role.go
│   │       ├── user
│   │       │   ├── permission.go
│   │       │   ├── role.go
│   │       │   └── user.go
│   │       └── user.go
│   └── registry
│       └── registry.go
└── scripts
    └── gqlgen.go