dictybase/graphql-server

graphql-server

概述

graphql-server是dictyBase的GraphQL服务器，基于Go语言开发，使用https://github.com/99designs/gqlgen%E5%B7%A5%E5%85%B7%E7%94%9F%E6%88%90%E4%BB%A3%E7%A0%81%E4%BB%A5%E5%8C%B9%E9%85%8DgRPC%E6%A8%A1%E5%9E%8B%E3%80%82%E8%AF%A5%E6%9C%8D%E5%8A%A1%E5%99%A8%E6%95%B4%E5%90%88%E4%BA%86%E7%94%A8%E6%88%B7%E3%80%81%E8%A7%92%E8%89%B2%E3%80%81%E6%9D%83%E9%99%90%E3%80%81%E5%BA%93%E5%AD%98%E3%80%81%E8%AE%A2%E5%8D%95%E7%AD%89%E5%A4%9A%E7%A7%8DgRPC%E6%9C%8D%E5%8A%A1%E5%8F%8Apublication API端点，提供统一的GraphQL查询和变更接口，并支持通过命令行进行配置与日志管理。

核心功能与特性

• 多服务集成：支持用户、角色、权限、库存、订单等多种gRPC服务，以及publication API端点
• 代码生成：基于https://github.com/99designs/gqlgen%E5%B7%A5%E5%85%B7%EF%BC%8C%E9%80%9A%E8%BF%87GraphQL 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端点（默认："https://betafunc.dictybase.org/publications"） [$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文件存储在https://github.com/dictyBase/graphql-schema%E4%BB%93%E5%BA%93%EF%BC%8C%E4%B8%BB%E8%A6%81%E5%8C%85%E5%90%AB%EF%BC%9A

• https://github.com/dictyBase/graphql-schema/blob/master/query.graphql - 所有查询定义
• https://github.com/dictyBase/graphql-schema/blob/master/mutation.graphql - 所有变更定义
• https://github.com/dictyBase/graphql-schema/blob/master/scalar.graphql - 标量类型定义（如timestamp）

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

代码生成步骤

1. 更新gqlgen.yml：

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

2. 运行生成命令：

   bash
   go generate ./...
   

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

3. 注意事项：

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

     go
     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