如何实现Express框架下GraphQL API与Playground的安全访问控制

一、接口与Playground访问控制实现 #

要实现类似Instagram不对外暴露Playground、仅授权人员可访问的效果，按以下层级配置即可：

• 第一层：环境维度开关Playground
  你当前配置里全局写死graphiql: true属于生产环境高危配置，首先改成环境变量驱动：仅本地/开发环境开启Playground，生产环境直接将该参数设为false，从根源关闭公网调试入口。
• 第二层：前置中间件做访问拦截
  不要把权限校验逻辑散落在各个GraphQL resolver中，统一在/graphql路由前加Express中间件做拦截：
  • 判断请求是否为Playground访问（特征为GET请求、Accept头包含text/html），生产环境下这类请求直接返回404，不暴露GQL服务存在性；如果确实需要给内部人员开放生产Playground，额外加IP白名单、管理员令牌校验，仅放通授权来源。
  • 所有对GQL接口的请求，统一在中间件做鉴权，校验不通过直接返回401/403，不需要走到后续的GraphQL解析流程。
• 第三层：上下文注入做细粒度权限控制
  鉴权通过后，把解析出的用户身份、权限信息注入到GraphQL的context中，各个resolver可以直接读取上下文信息做字段级、操作级的权限判断。
• 额外加固：生产环境建议搭配查询深度限制、查询复杂度校验、请求频率限制，避免被恶意复杂查询打垮服务或拖取数据。

二、GraphQL鉴权令牌传递方式 #

完全可以沿用你在REST API开发中的习惯，将鉴权令牌放在请求Headers中传递，这也是GraphQL生态的标准实践，没有任何兼容性问题：

• 常规接口调用时，和REST接口逻辑完全一致，将令牌放在Authorization请求头中，格式通常为Bearer <令牌内容>，在前置Express中间件中解析该头部完成校验即可。
• 开发环境使用Playground调试时，直接在Playground的设置面板中配置固定请求头，带上鉴权令牌即可，不需要调整传递逻辑。
• 不推荐将令牌放在URL查询参数、请求体的variables字段中传递：查询参数容易被网关、代理、服务日志记录导致泄露，放在请求体中需要每个请求额外处理令牌字段，增加不必要的维护成本。

适配后的完整参考配置 #

const express = require('express');
const { graphqlHTTP } = require('express-graphql');
const schema = require('./your-schema-path');
// 替换为你实际使用的token校验逻辑，比如JWT校验
const verifyToken = require('./your-token-verify-func');
const app = express();

// 通用鉴权中间件，和REST接口鉴权逻辑完全复用
const authMiddleware = (req, res, next) => {
  const authHeader = req.headers.authorization;
  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    return res.status(401).json({ error: 'Unauthorized' });
  }
  const token = authHeader.replace('Bearer ', '');
  try {
    const userInfo = verifyToken(token);
    // 将用户信息挂载到req对象，后续传给GQL上下文
    req.user = userInfo;
    next();
  } catch (err) {
    return res.status(401).json({ error: 'Invalid token' });
  }
};

// 运行环境判断
const isDevEnv = process.env.NODE_ENV === 'development';

app.use(
  "/graphql",
  // 生产环境全接口启用鉴权，开发环境可按需放开
  ...(isDevEnv ? [] : [authMiddleware]),
  // Playground访问拦截中间件
  (req, res, next) => {
    const isPlaygroundRequest = req.method === 'GET' && req.accepts('html');
    if (isPlaygroundRequest && !isDevEnv) {
      // 生产环境直接返回404，对外隐藏Playground入口
      return res.status(404).send('Not Found');
    }
    next();
  },
  graphqlHTTP((req) => ({
    schema,
    graphiql: isDevEnv,
    // 将用户信息注入GQL上下文，供所有resolver使用
    context: {
      currentUser: req.user
    }
  }))
);

app.listen(3000, () => {
  console.log('Service running on port 3000');
});

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