beego 不内置 graphql 支持，需集成 graphql-go 或 gqlgen；必须用 post 请求并正确解析 json；resolver 应返回标准 go 结构体而非 orm 指针；gqlgen 需每次 schema 变更后重新生成代码；graphql 错误需在 resolver 或 fieldmiddleware 中处理，不可依赖 beego 中间件。
Beego 本身不内置 GraphQL 支持，必须手动集成第三方库（如 graphql-go 或 gqlgen）来提供 GraphQL 端点。直接在 Beego 的 Controller 中处理 GraphQL 请求是可行的，但要注意请求体解析、Schema 执行和错误格式的统一，否则前端 Apollo 客户端会报 Unexpected token 或 Cannot query field。
GraphQL 请求必须走 POST + application/json
Beego 默认对 GET 请求只解析 URL 查询参数，而 GraphQL 查询（尤其是带变量的）几乎总是通过 POST 发送 JSON。如果你用 beego.Router("/graphql", &controllers.GraphQLController{}, "get:Serve")，ctx.Input.RequestBody 为空，json.Unmarshal 必然失败。
- 必须绑定为
"post:Serve"，且确保前端发送的是标准 GraphQL JSON 格式：{"query":"{user{id name}}","variables":{}} - Beego 的
ctx.Input.RequestBody在 POST 时才自动填充，无需手动调用ctx.Input.ParseForm() - 若混用 GET（如调试用
?query=...），需额外判断ctx.Input.Method() == "GET"并从ctx.Input.Query("query")提取，但 Apollo 不支持这种用法，不建议上线
Resolver 函数不能直接返回 Beego ORM 结构体指针
GraphQL 执行器（如 graphql-go/graphql）要求 Resolver 返回能被 JSON 序列化的值，而 Beego 的 orm.QuerySeter.All(&v) 返回的切片若含未导出字段或嵌套指针，会导致 nil 字段被忽略、时间字段变空字符串、甚至 panic。
- 务必用普通 Go 结构体（所有字段首字母大写）做 Resolver 返回类型，例如：
type User struct { ID int `json:"id"` Name string `json:"name"` CreatedAt time.Time `json:"created_at"` } - 避免直接返回
*models.User（假设 models.User 是 Beego ORM 模型），即使它有jsontag —— ORM 结构体常含ormtag 冲突、未导出字段（如IsNew）、或内部缓存指针 - 使用
Copy或构造函数做显式转换，例如：u := User{ID: ormUser.Id, Name: ormUser.Name}，别依赖反射自动映射
Schema 变更后必须重新生成 resolver 接口（gqlgen 场景）
如果选用 gqlgen（推荐用于中大型项目），它的代码生成机制严格依赖 schema.graphql 文件。改了字段名、加了新类型、甚至只是调整了 @goModel directive 的包路径，运行 go run github.com/99designs/gqlgen generate 后，generated.go 里的 Resolver 接口签名会变 —— 但你的实现文件（如 resolver.go）不会自动更新，编译直接报错。
- 每次修改
schema.graphql后，必须先执行gqlgen generate，再检查resolver.go是否实现新接口方法（IDE 通常标红提示） - Beego 的
Controller层应只负责接收请求、调用gqlgen生成的graphql.Handler，不要把 resolver 逻辑写进 controller —— 否则就失去了 gqlgen 的类型安全优势 -
gqlgen默认生成的 handler 不兼容 Beego 的context.Context，需用http.HandlerFunc包一层再挂到 Beego 路由：例如beego.Handler("/graphql", http.HandlerFunc(graphqlHandler))
Beego 的中间件无法直接拦截 GraphQL 字段级错误
GraphQL 的错误是响应体内的 errors 数组（如 {"data":null,"errors":[{"message":"field not found"}]}），不是 HTTP 状态码。Beego 的全局中间件（如 beego.InsertFilter）只能拿到原始 http.ResponseWriter，无法修改已写入的 JSON 响应体。
- 字段级权限、鉴权、日志等逻辑，必须下沉到 resolver 内部，或用
gqlgen的FieldMiddleware（需手动注册） - 想统一加 trace-id 或记录慢查询，得在
gqlgen.Config.ResolverMiddleware中注入，而不是靠 Beego 的Prepare方法 - HTTP 层面的错误（如解析失败、超时）可由 Beego 中间件捕获，但 GraphQL 执行中的 panic 需靠
graphql.UseFieldResolvers或自定义Recovermiddleware 处理
最易被忽略的一点：Beego 的 app.conf 中 EnableDocs = true 会暴露 Swagger 页面，但它对 GraphQL 端点完全无效；GraphQL 的 Playground 必须单独启用（如用 graphql-go/playground），且要确保路由不被 Beego 的静态文件规则拦截（比如 /static/ 规则匹配了 /graphql/*）。
