把 gqlgen 的 GraphQL 行为搬到 HotChocolate 16:一次 wire-level 对齐实录
接着昨天写的文章《把一个 5k star 的 Go AI 网关移植到 .NET:为什么我选择用 Orleans 重写它的并发内核》,今天写第二篇,主题是GraphQL 的GraphQL over HTTP。 AxonHub 原本是一套 Go 服务,管理面的 GraphQL 由 gqlgen 0.17.86 生成。现在整个后端要迁到 .NET,状态层换成 Orleans 10.4.1,前端一行不改。
这个约束把验收标准定死了:同一个请求,得回来同样的字节。「功能都有」不算数。JSON 形状、错误结构、HTTP 状态码、内省结果,甚至 Playground 页面,都得和参照实现对得上。
src/AxonHub.Api/GraphQL 下 44 个文件、合计超过 1 MB 的代码,大半在做这件事。注释里密密麻麻写着 internal/server/gql/graphql.go:153-179、C134、C-range difference 这类坐标,每处和 Go 侧不一致的地方都标了文件和行号。看着笨,真出问题时最省时间:不用猜,直接翻参照实现。

图:五层结构。蓝色是 GraphQL 层,绿色是 Orleans 状态层;Grain 调用集中在服务层,resolver 不直接持有 IGrainFactory。
下面挑几个真正费劲的地方说说。
一、一个进程,两套 schema
Go 侧挂了两个独立的 gqlgen server:/admin/graphql 和 /openapi/v1/graphql。.NET 侧用 HotChocolate 的命名 schema,在同一个进程里承载:
// Program.cs 节选
app.MapGraphQL("/admin/graphql")
.WithOptions(o => o.EnableGetRequests = false)
.WithMetadata(new HttpMethodMetadata([HttpMethods.Post]));
app.MapGraphQL("/openapi/v1/graphql", "openapi")
.WithOptions(o => o.EnableGetRequests = false)
.WithMetadata(new HttpMethodMetadata([HttpMethods.Post]));
"openapi" 对应 AddGraphQLServer("openapi", 20 * 1024 * 1024, disableDefaultSecurity: false) 注册的那套 schema。两个端点都禁 GET,因为参照实现只挂 POST 路由。
非 POST 请求还有一段额外的处理。HotChocolate 的端点会匹配其他方法并回 405,而 Go 侧 gin 的 NoRoute 把请求交给静态处理器,返回的是 JSON 404 包络。为了让错误形状也一致,代码在路由前插了一段短路:
// Program.cs 节选,注释里把这个差异编号为 C116
app.UseWhen(
ctx => ctx.Request.Path.StartsWithSegments("/admin/graphql")
&& !HttpMethods.IsPost(ctx.Request.Method),
branch => branch.Run(ctx =>
StaticHandler.WriteApiNotFoundAsync(ctx, ctx.Request.Path.Value ?? "/")));
前端要是有按状态码分支的逻辑,这几行就省不掉。
二、让 .NET 的 schema 长得像 Go 的
HotChocolate 默认按 CLR 类型名推断 GraphQL 名称,gqlgen 按 SDL 走。不一致的地方只能逐个钉死。
根节点:CLR 类叫 OpenApiQuery,SDL 里叫 Query,注册时显式改名 AddQueryType<OpenApiQuery>(d => d.Name("Query"))。
输入对象更麻烦。CLR 类型为了避免和业务类型撞名加了 Input 后缀,但线上名字必须是 SDL 里那几个:
// GraphQLSetup.cs 节选
.AddType(new InputObjectType<ChannelOrderingItemInput>(
d => d.Name("ChannelOrderingItem")))
.AddType(new InputObjectType<BulkImportChannelItemInput>(
d => d.Name("BulkImportChannelItem")))
.AddType(new InputObjectType<AnalyticsFilterInput>(
d => d.Name("AnalyticsFilter")))
还有一类很隐蔽:有些类型从任何根字段都走不到,只能靠 node(id:) 访问。HotChocolate 只在已注册类型里发现接口实现,所以 ChannelProbeType、UserRoleType、HourlyRequestStatsType 都得手工 AddType。漏掉一个,schema 里就缺一个类型,内省对比立刻露馅。注释把这类情况写得很直白:「Defined by dashboard.graphql but never reached from a root field」。
字段级则是 [GraphQLName("projectID")]、[GraphQLType(typeof(IdType))] 这样的标注,对应 Go 侧的全局 ID 和命名习惯。
三、四个必须自己写的标量
Go 的自定义标量在 .NET 里没有现成对应物,只能照着 wire 格式重写。
GID:形如 gid://axonhub/User/123。GidValue.Parse 连报错文案都照抄 Go:guid must start with gid://axonhub/、strconv.Atoi: parsing "...": invalid syntax。后面那句来自 strconv.Atoi 的 ErrSyntax,代码里专门用 IsDecimal 判断该报 invalid syntax 还是 value out of range。
Time:time.RFC3339Nano,UTC,小数末尾的零要去掉。
public static string Format(DateTime value)
{
var utc = value.Kind == DateTimeKind.Utc ? value : value.ToUniversalTime();
return utc.ToString("yyyy-MM-dd'T'HH:mm:ss.FFFFFFF'Z'", CultureInfo.InvariantCulture);
}
FFFFFFF 是关键。写成小写 fffffff 就会多出一串 0,前端拿到的是另一种字符串。
Cursor:Go 侧用 msgpack 载荷加 base64.RawStdEncoding。移植环境拿不到 msgpack 依赖,代码改用 JSON 载荷,但保留「无填充 base64」这个线上形状(.TrimEnd('=')),并在注释里标成 C-range difference。旧游标没有 ValueKind 字段,解码时按时间处理,这个兼容分支也留着。
JSONRawMessage / Map:Go 的 json.RawMessage 是把原始 JSON 直接嵌进响应,不是当字符串序列化。JsonRawMessageType 继承 ScalarType<JsonElement>,重写 SerializationType(63,表示接受全部 JSON 类型)和 IsValueCompatible,再按 ValueKind 分别调用 SetStringValue、SetNumberValue、SetBooleanValue。写成普通 String 标量,前端解析就会炸。
四个标量做完,schema 的形状才算对上。
四、错误格式也要一模一样
gqlgen 的 error presenter 把 CodedError 报成 message 加 extensions.code/resource/field/value。.NET 侧用自定义异常加错误过滤器复刻:
// CodedException.cs 节选
var builder = ErrorBuilder.FromError(error)
.SetMessage(coded.Message)
.SetExtension("code", coded.Code)
.SetExtension("resource", /* 取自 coded.Extensions,缺失时为 null */)
.SetExtension("field", /* ... */)
.SetExtension("value", /* ... */);
return builder.Build();
三处细节值得记:沿 InnerException 链找 CodedException;privacy deny 转成 permission denied 加 FORBIDDEN;普通异常用 error.Exception.Message 覆盖 HotChocolate 默认的 "Unexpected Execution Error",否则参照实现的错误信息在 .NET 上会被吞掉。
OpenAPI 那套 schema 反过来不带这些元数据,因为 Go 侧没装自定义 presenter。OpenApiGraphQLErrorFilter 做的是 SetCode(null) 加 ClearExtensions(),只留 message、path、locations。两套 schema 的错误格式故意不一样,这是参照实现本来的行为,不是疏漏。
五、内省和上传:两个踩过才知道的细节
HotChocolate 16 默认拒绝内省,请求会拿到 HC0046「Introspection is not allowed for the current request」。gqlgen 默认开放,所以每个请求都得 opt-in:
// GraphQLSetup.cs 节选
internal sealed class IntrospectionRequestInterceptor : DefaultHttpRequestInterceptor
{
public override ValueTask OnCreateAsync(
HttpContext context, IRequestExecutor executor,
OperationRequestBuilder requestBuilder, CancellationToken ct)
{
requestBuilder.AllowIntrospection();
return base.OnCreateAsync(context, executor, requestBuilder, ct);
}
}
base.OnCreateAsync 那行不能省。它负责把 multipart 的 IFileLookup 特性复制到 operation request 上,Upload 标量靠这个找文件。省掉之后 restore(file:) 会报 "specified file could not be found"。注释里专门解释了这层依赖。
六、状态层:Orleans Grain 接住了 Go 的锁和 cron
前面几节都停在 GraphQL 这一层。请求真正落到后端时,状态不在 resolver 里。翻调用关系能看到一条很干净的分界:GraphQL/ 目录里一次 IGrainFactory 或 GetGrain<T>() 都没有,Grain 调用集中在 Management/ 和 Orchestration/ 下的十几个 Grain* 适配类。resolver 靠 [Service] 注入领域服务,服务层再去拿 Grain。API 层不需要知道底下有 Actor。
Go 侧用 mutex 保护的东西,在这里换成了按 key 串行的 Grain:
ChannelGrain的 key 是 channelId,管每通道的指标窗口(600 秒、按秒分槽)、连续失败数、RPM/TPM 和 429 冷却。注释说得直白:Orleans 把单个 activation 的每个 turn 串行化,正好替掉 Go 的 per-channel metrics locks 和进程级 tracker lock。ChannelPoolGrain的 key 是请求模型 ID,负责给候选通道打分排序,adaptive、failover、circuit-breaker、round-robin 四种策略照搬参照实现,按 key 串行替代原来的锁。
也有没搬进去的。ChannelLimiterManager 的阻塞 FIFO 门留在每个 silo 本地,注释标成 C042,理由写得很清楚:它不能塞进 grain scheduler。虚拟 Actor 省掉的是锁,阻塞语义得自己留着。
定时任务从 Go 的 cron 变成 IRemindable 单例 Grain,一共六个:IGcGrain、IAutoBackupGrain、IProviderQuotaCoordinatorGrain、IVideoStorageGrain、IChannelProbeGrain、IChannelCredentialRecoveryGrain,全部用 SingletonKey。启动时得逐个唤醒:
// GrainSchedulerActivator.cs 节选
await grainFactory.GetGrain<IGcGrain>(IGcGrain.SingletonKey)
.EnsureScheduledAsync(now).ConfigureAwait(false);
await grainFactory.GetGrain<IAutoBackupGrain>(IAutoBackupGrain.SingletonKey)
.EnsureScheduledAsync(now).ConfigureAwait(false);
AutoBackupGrain 里有个细节能看出移植有多较真:Orleans reminder 没有一次性触发,最小周期是一分钟,所以 fire path 先重新 arm 下一次,再执行备份。备份失败也不会把整个 cron 弄丢。GrainSchedulerActivator 注册在 UseOrleans 之后,保证 silo 先起来;内存 reminder 表随进程停止而丢失,启动时从当前时刻重排,漏掉的 02:00 不补跑,和 Go 进程重启的行为一致。
集群分两档:
// Program.cs 节选
builder.Host.UseOrleans(silo =>
{
if (orleansCluster.Enabled)
{
silo.UseAdoNetClustering(o => { o.Invariant = "Npgsql"; /* ... */ });
silo.UseAdoNetReminderService(o => { o.Invariant = "Npgsql"; /* ... */ });
}
else
{
silo.UseLocalhostClustering();
silo.UseInMemoryReminderService();
}
silo.AddMemoryGrainStorage("Default");
});
多 silo 用 PostgreSQL 的 AdoNet membership 与 reminders,注释点明了理由:死掉的 silo 能被集群看见,Grain 放置可以漂到存活节点,reminder 也不会跟着某个 silo 一起消失。单 silo 就 localhost clustering 加内存 reminder,行为向参照实现的单进程 cron 看齐。
锁、cron、集群成员关系交给 Orleans 之后,GraphQL 层剩下的是一层薄的无状态入口。前面那些逐字节对齐能安心做,靠的就是这层分界。
七、协议版本:September 2026 与一次刻意的退让
2026 年 11 月 12 日,GraphQL over HTTP 第一版规范发布,名为 September 2026 Edition。它把过去「什么都返回 200」的惯例改掉了:有 data 用 2xx,只有 errors 用 4xx 或 5xx,校验失败 422,data 与 errors 并存用 294,请求体过大 413。
这套代码用的包版本是 HotChocolate.AspNetCore 16.8.0-p.15(写在 Directory.Packages.props 里),并显式启用了正式版:
// GraphQLSetup.cs 节选
internal sealed class GoCompatibleHttpResponseFormatter : DefaultHttpResponseFormatter
{
public GoCompatibleHttpResponseFormatter()
: base(new HttpResponseFormatterOptions
{
HttpTransportVersion = HttpTransportVersion.September2026,
}, new DefaultTimeProvider(), IncrementalDeliveryFormat.Version_0_2) { }
protected override HttpStatusCode OnDetermineStatusCode(
OperationResult result, FormatInfo format, HttpStatusCode? proposedStatusCode)
{
return result.Errors.Any(e => e.Extensions?.ContainsKey("specifiedBy") == true)
? HttpStatusCode.BadRequest
: base.OnDetermineStatusCode(result, format, proposedStatusCode);
}
}
这段覆写是在做一次取舍。规范给校验错误 422,但代码把带 specifiedBy 扩展的错误钉回 400。specifiedBy 是 HotChocolate 挂在规范校验错误上的扩展,也就是说,协议版本升到了正式版,校验失败的状态码仍然保持 Go 侧客户端认识的那个值。类名 GoCompatible 就是这么来的。存量客户端的解析逻辑比一份新标准更硬,这类覆写通常得留到客户端全部升级为止。
我们用同一组请求在 16.7.5(稳定)和 16.8.0-p.15(预览)上跑过对照,结果如下:
| 场景 | Draft20250508(默认) | September2026 |
|---|---|---|
| 查询成功 | 200 · gr+json | 200 · gr+json |
| 字段不存在 | 400 · gr+json | 422 · gr+json |
| data 与 errors 并存 | 200 | 294 |
老客户端 Accept: application/json 且校验失败 |
200 · json | 422 · gr+json |
| 无 Accept 头且校验失败 | 400 · gr+json | 422 · gr+json |
| 非法 JSON | 400 · gr+json | 400 · gr+json |
gr+json 指 application/graphql-response+json。注意倒数第二行:正式版下老客户端连 Content-Type 都变了,因为规范规定只有 2xx 响应才带 application/json。
其余新增码得靠基础设施接住。294 没在 IANA 注册,nginx 的 add_header 默认不覆盖它,要补 always 才不会丢 CORS 和安全响应头;监控口径要从「非 2xx 即失败」改成「含 errors 的响应加 4xx/5xx」,否则升级当天错误率曲线会无故跳一下。
还有个版本陷阱:稳定版 16.7.5 的枚举里没有 September2026,只有等价的 Draft20260903,两者是同一个枚举值的两个名字。Latest 在预览包里依然指向 Draft20250508,升级 NuGet 包不会自动切到正式版行为,必须显式设置。
八、从这套代码里带走的几条
- 验收标准放在线上。跨语言移植用 wire 对比收口,比逐项功能打勾更早暴露问题。schema 内省、错误 extensions、404 包络都算对比项。
- 每处差异留坐标。注释里写清参照实现的「文件路径:行号」和差异编号(C116、C134 等)。半年后回头查,不用重新逆向。
- 显式注册比自动发现可靠。孤立类型、输入对象改名、根节点改名,一律手工钉死,别指望框架推断。
- 别用
Latest。它是浮动别名,某次小版本升级就可能改掉全站状态码。写死具体版本,把变更放进自己的发布节奏。 - 兼容性覆写要留下理由。把 422 改回 400 这类「反规范」的决定,类名和注释得说明是为谁让步,否则下一个人会当成 bug 修掉。
小结
跨语言移植里,resolver 翻译一遍反而最省事。磨人的是那些没人写进文档的默认值:时间格式末尾的零、base64 的填充、错误对象里多出来的一个字段、GET 请求该回 404 还是 405。框架换得越彻底,这些缝隙越多。状态层交给 Orleans 之后,API 层才能薄到只做协议对齐。
这套代码的做法是把每条缝隙都变成可查的条目:能对上的就照抄,对不上的标成差异,为了让存量客户端继续跑而刻意偏离规范的地方,则在 formatter 里显式覆写并留下理由。协议版本升到 September 2026 是顺势,把校验错误钉回 400 是取舍,两件事都写在同一段代码里。
参考
- GraphQL over HTTP, September 2026 Edition:https://http-spec.graphql.org/September2026/
- GraphQL 基金会发布说明(2026-11-12):https://graphql.org/blog/2026-11-12-announcing-the-graphql-over-http-spec/
- Hot Chocolate HTTP Transport 文档:https://chillicream.com/docs/hotchocolate/v16/server/http-transport
- Microsoft Orleans 概览:https://learn.microsoft.com/en-us/dotnet/orleans/overview
欢迎大家扫描下面二维码成为我的客户,扶你上云

浙公网安备 33010602011771号