如何使用x-hasura-admin-secret访问指定Hasura控制台

一、验证凭据并进入Hasura控制台 #

• 准备好你的Hasura服务访问根域名，直接在浏览器输入https://[你的Hasura服务域名]/console打开控制台入口
• 页面弹出Admin Secret校验框时，把你拿到的x-hasura-admin-secret对应字符串完整粘贴进去，确认后即可进入控制台
• 进入控制台后点击顶部「Data」标签，查看所有已存在的新闻相关数据表，记下表名、需要用到的字段名（比如id、标题、封面、发布时间、正文等）
• 点击顶部「API」标签进入接口调试页，复制地址栏中/console/api/api-explorer前缀部分的根路径，拼接上/v1/graphql就是后续Flutter端要请求的接口端点，格式一般为https://[你的Hasura服务域名]/v1/graphql

二、Flutter端集成配置 #

• 打开项目根目录下的pubspec.yaml，添加graphql_flutter依赖：

dependencies:
  flutter:
    sdk: flutter
  graphql_flutter: ^5.1.2

• 执行flutter pub get拉取依赖包
• 打开项目入口文件（默认是lib/main.dart），初始化GraphQL客户端，必须将admin secret加入默认请求头，参考代码如下，替换对应占位符即可：

import 'package:flutter/material.dart';
import 'package:graphql_flutter/graphql_flutter.dart';
import 'news_list_page.dart';

void main() async {
  await initHiveForFlutter(); // 初始化graphql_flutter的本地缓存，必须调用
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    // 配置请求链接，替换为你自己的Hasura GraphQL端点
    final HttpLink httpLink = HttpLink(
      'https://[你的Hasura服务域名]/v1/graphql',
      defaultHeaders: {
        'x-hasura-admin-secret': '替换为你拿到的secret完整字符串',
      },
    );

    // 组装客户端实例
    final ValueNotifier<GraphQLClient> client = ValueNotifier(
      GraphQLClient(
        link: httpLink,
        cache: GraphQLCache(store: HiveStore()),
      ),
    );

    // 注入客户端到整个应用
    return GraphQLProvider(
      client: client,
      child: MaterialApp(
        title: '新闻客户端',
        theme: ThemeData(primarySwatch: Colors.blue),
        home: const NewsListPage(),
      ),
    );
  }
}

• 编写GraphQL查询语句，字段必须和你在Hasura控制台看到的表结构完全一致，假设新闻表名为news，示例查询如下：

// 新闻列表查询语句，按发布时间倒序拉取
const String fetchNewsQuery = r'''
query FetchNewsList {
  news(order_by: {publish_time: desc}) {
    id
    title
    summary
    cover_url
    publish_time
  }
}
''';

• 编写新闻列表页，用Query组件拉取并渲染数据，参考代码：

class NewsListPage extends StatelessWidget {
  const NewsListPage({super.key});

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('新闻列表')),
      body: Query(
        options: QueryOptions(
          document: gql(fetchNewsQuery),
          fetchPolicy: FetchPolicy.cacheAndNetwork, // 优先读缓存，同时拉取最新数据
        ),
        builder: (QueryResult result, {refetch, fetchMore}) {
          // 加载中状态
          if (result.isLoading) {
            return const Center(child: CircularProgressIndicator());
          }
          // 请求异常
          if (result.hasException) {
            return Center(
              child: Padding(
                padding: const EdgeInsets.all(16.0),
                child: Text('数据加载失败：${result.exception.toString()}'),
              ),
            );
          }
          // 解析数据渲染列表
          final List newsData = result.data!['news'] as List;
          return RefreshIndicator(
            onRefresh: () async => refetch?.call(),
            child: ListView.builder(
              padding: const EdgeInsets.all(8),
              itemCount: newsData.length,
              itemBuilder: (context, index) {
                final item = newsData[index];
                return Card(
                  margin: const EdgeInsets.only(bottom: 8),
                  child: ListTile(
                    leading: item['cover_url'] != null
                        ? Image.network(item['cover_url'], width: 80, fit: BoxFit.cover)
                        : Container(width: 80, color: Colors.grey[200]),
                    title: Text(item['title'] ?? ''),
                    subtitle: Text(item['publish_time'].toString().split('T').first),
                  ),
                );
              },
            ),
          );
        },
      ),
    );
  }
}

三、常见问题排查 #

• 控制台无法登录：检查服务地址是否正确，secret字符串前后不要留空格、不要漏字符
• Flutter端请求返回401：检查请求头的键名是否为x-hasura-admin-secret，有没有拼写错误，secret值是否完整
• 请求返回字段校验错误：回到Hasura控制台Data标签页，核对表名、字段名，GraphQL强类型校验，名称大小写、拼写错误都会直接报错
• 注意：admin secret是最高权限凭据，仅适合本地开发调试使用，正式上线前必须替换为JWT或权限webhook鉴权方案，避免凭据泄露导致数据被篡改

内容的提问来源于stack exchange，提问作者Chirag Maurya