GraphQL 脚本

GraphQL 脚本

graphql 将文档发送到上游 GraphQL 服务器，不同于通过 Viat 引擎查询数据库的 viat_gql。必须恰好声明一个 graphql 资源。URL、请求头、认证和 TLS/代理策略由资源配置持有，优先使用它而不是把 HTTP 凭证写入源码。没有解释器、main 或 ctx。

完整最小文档

隔离固定服务需提供 Query.hello(name: String!): String!，输入 name: "Ada" 返回 Hello, Ada。配置 upstream 资源指向该服务，保存 scripts/gql_hello.graphql：

# @resource upstream
query Hello($name: String!) {
  hello(name: $name)
}

viat script create --name gql_hello --language graphql --file scripts/gql_hello.graphql
viat script run gql_hello --args '{"name":"Ada"}'
viat script update gql_hello --file scripts/gql_hello.graphql

预期正文 {"hello":"Hello, Ada"}，不是 {"data":...}。服务和资源是前置条件，不是内置功能。本文没有调用真实服务。需项目编辑/运行和上游权限。测试说明离线 GraphQL cassette、端点发布与清理。

变量与操作选择

正文为标准 query/mutation 文档，请求参数作为变量。多个操作时 __operation 选择上游操作名：

viat script run gql_hello --args '{"name":"Ada","__operation":"Hello"}'

优先每个资产一个操作：提取器只取第一个，多个时警告，不会按运行时 __operation 切换。Int/Float/String/ID/Boolean 和列表映射输入 Schema；无默认值的 non-null 必填，声明 GraphQL 默认值后可省略。自定义 scalar/enum/input object 不展开。GraphQL 文档默认值由上游应用，不是模板语言。没有 {{...}} 或 SQL 占位符语法。

输出、失败与预算

运行器仅返回响应的 data。上游 errors 数组只要非空就失败，即使有部分 data，也不能当成功。非成功 HTTP 状态、JSON 错误、网络失败和超时也会失败。静态提取输出描述 data/errors 信封，不是实际运行输出契约，需验证真实结果。

# timeout: N 受部署上限约束。不提供原生 subscription 传输、ViatStream、tasks 或资源 helper。分支、多次请求、工具调用和流式请用 Python/TypeScript。Mutation 有真实副作用，不能假定自动重试安全。Caller_token 认证需要真实调用凭证，排队/延后执行不保留它。

验证固定服务收到的 variables/operationName 和返回 data 对象。先用隔离只读服务，检查错误但不记录上游凭证，明确发布后再公开。删除 gql_hello 前先取消发布并删除一次性端点；删脚本不会删除上游数据。