HotChocolate服务注册必须在ConfigureServices中完成，且AddGraphQLServer()需在AddControllers()之前调用；Query类型须为public并暴露public属性或标记[GraphQLName]；ID参数必须用[ID]标记；端点需通过UseGraphQL中间件启用；自定义标量类型须完整实现ParseResult和Serialize。
HotChocolate服务注册必须在ConfigureServices中完成
不注册IServiceCollection就调用AddGraphQLServer()会导致运行时抛出InvalidOperationException: No service for type 'HotChocolate.IRequestExecutorResolver' has been registered。这是最常见的启动失败原因。
正确做法是：在Program.cs（.NET 6+）或Startup.ConfigureServices中显式添加服务：
services
.AddGraphQLServer()
.AddQueryType<Query>()
.AddMutationType<Mutation>();
- 必须在
AddControllers()之前注册，否则控制器路由会覆盖GraphQL端点 - 若使用Entity Framework Core，需先注册
AddDbContext<appdbcontext>()</appdbcontext>，再注册GraphQL——类型发现依赖已注册的上下文 - 不要在
Configure里调用AddGraphQLServer，它不是中间件配置方法
Query类型必须公开且含public字段/属性或[GraphQLName]标记
HotChocolate默认只暴露public实例成员。若定义了private字段、internal属性，或未加[GraphQLName]的public方法，它们不会出现在Schema中，前端查询会报Cannot query field "xxx" on type "Query"。
示例错误写法：
public class Query
{
private string _name = "test"; // 不可见
internal int Count => 42; // 不可见
public string GetName() => _name; // 方法名驼峰转小写后为"getname"，非标准命名
}
应改为：
public class Query
{
[GraphQLName("name")]
public string Name => "test";
public int Count { get; } = 42;
public User GetUser([ID] string id) => new User { Id = id };
}
- 属性优先于方法；方法需返回值且无参数（或仅接受
IResolverContext）才被自动识别 - ID参数必须用
[ID]特性标记，否则解析失败并报Unable to infer GraphQL type - 返回
IEnumerable<t></t>或IQueryable<t></t>时，HotChocolate会自动推导为[T!]，但IQueryable需配合AddProjections()启用服务端投影
GraphQL端点路径默认是/graphql，但需手动映射中间件
仅注册服务不等于端点可用。若没在Configure中调用UseGraphQL，访问/graphql会返回404。
正确中间件顺序（.NET 6+ Program.cs）：
app.UseRouting();
app.UseAuthentication();
app.UseAuthorization();
app.UseWebSockets();
app.UseGraphQL("/graphql"); // 必须在UseRouting之后、UseEndpoints之前
app.UseGraphQLPlayground(); // 可选，仅开发环境
app.UseEndpoints(endpoints => endpoints.MapControllers());
-
UseGraphQL必须放在UseRouting之后，否则HttpContext.Request.RouteValues为空导致解析异常 - 若同时启用
UseGraphQLPlayground和UseGraphQLAltair，确保只启用一个，避免静态资源冲突 - 生产环境建议禁用Playground，通过
env.IsDevelopment()控制是否注册
自定义标量类型需全局注册且实现IValueNodeConverter
比如想支持DateOnly作为输入/输出类型，直接返回DateOnly会触发Unable to infer GraphQL type。HotChocolate不内置DateOnly映射。
解决路径：
- 定义标量类型类，继承
ScalarType<dateonly></dateonly>并重写ParseResult/Serialize - 在
AddGraphQLServer()链式调用中用AddType<dateonlytype>()</dateonlytype>注册 - 或全局注册：
services.AddGraphQLServer().AddScalarType<dateonlytype>()</dateonlytype>
关键点：若只注册类型但没重写Serialize，JSON序列化仍走默认DateTime逻辑，导致格式错乱；若漏掉ParseResult，客户端传"2023-01-01"会解析失败。
这个环节最容易被跳过——开发者常以为“加了AddType就完事”，结果在变量传入时卡在解析层，错误信息却只显示模糊的Variable '$date' has invalid value。
