把 gqlgen 的 GraphQL 行为搬到 HotChocolate 16:一次 wire-level 对齐实录

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 包不会自动切到正式版行为,必须显式设置。

八、从这套代码里带走的几条

  1. 验收标准放在线上。跨语言移植用 wire 对比收口,比逐项功能打勾更早暴露问题。schema 内省、错误 extensions、404 包络都算对比项。
  2. 每处差异留坐标。注释里写清参照实现的「文件路径:行号」和差异编号(C116、C134 等)。半年后回头查,不用重新逆向。
  3. 显式注册比自动发现可靠。孤立类型、输入对象改名、根节点改名,一律手工钉死,别指望框架推断。
  4. 别用 Latest。它是浮动别名,某次小版本升级就可能改掉全站状态码。写死具体版本,把变更放进自己的发布节奏。
  5. 兼容性覆写要留下理由。把 422 改回 400 这类「反规范」的决定,类名和注释得说明是为谁让步,否则下一个人会当成 bug 修掉。

小结

跨语言移植里,resolver 翻译一遍反而最省事。磨人的是那些没人写进文档的默认值:时间格式末尾的零、base64 的填充、错误对象里多出来的一个字段、GET 请求该回 404 还是 405。框架换得越彻底,这些缝隙越多。状态层交给 Orleans 之后,API 层才能薄到只做协议对齐。

这套代码的做法是把每条缝隙都变成可查的条目:能对上的就照抄,对不上的标成差异,为了让存量客户端继续跑而刻意偏离规范的地方,则在 formatter 里显式覆写并留下理由。协议版本升到 September 2026 是顺势,把校验错误钉回 400 是取舍,两件事都写在同一段代码里。

参考