使用 Postman 测试 GraphQL 接口

1. 概述

本文将介绍如何使用 Postman 对 GraphQL 接口进行测试。✅
对于后端开发人员来说，快速验证接口行为是日常开发的刚需，而 Postman 提供了对 GraphQL 的原生支持，让测试变得简单粗暴又高效。

2. Schema 概览与接口定义

我们以之前 Spring GraphQL 教程中构建的接口为例。其核心 Schema 定义了 Post 和 Author 两种类型：

type Post {
    id: ID!
    title: String!
    text: String!
    category: String
    author: Author!
}
 
type Author {
    id: ID!
    name: String!
    thumbnail: String
    posts: [Post]!
}

同时提供了查询和写入的接口方法：

type Query {
    recentPosts(count: Int, offset: Int): [Post]!
}
 
type Mutation {
    createPost(title: String!, text: String!, category: String) : Post!
}

⚠️ 注意：

字段后的 ! 表示该字段为必填（非空）
Query 返回的是 Post 列表，而 Mutation 返回单个 Post 对象

Postman 支持直接导入 GraphQL Schema，自动生成可用的请求集合：

在 API 模块中点击 New API
选择类型为 GraphQL
粘贴 Schema 并点击 Generate Collection

✅ 优势：导入后，Postman 能提供 GraphQL 语法自动补全，极大提升编写查询效率。

3. 在 Postman 中发送 GraphQL 请求

Postman 原生支持 GraphQL 请求格式。选择请求体类型为 GraphQL 即可：

查询示例（Query）

获取最近一篇帖子的标题、分类及作者姓名：

query {
    recentPosts(count: 1, offset: 0) {
        title
        category
        author {
            name
        }
    }
}

返回结果：

{
    "data": {
        "recentPosts": [
            {
                "title": "Post",
                "category": "test",
                "author": {
                    "name": "Author 0"
                }
            }
        ]
    }
}

写入示例（Mutation）

创建新帖子并返回生成的 id 和 title：

mutation {
    createPost (
        title: "Post", 
        text: "test", 
        category: "test"
    ) {
        id
        title
    }
}

💡 小贴士：

可以省略 query 或 mutation 关键字（使用简写语法），但不推荐在正式环境中使用
缺少操作名（operation name）不利于日志追踪和调试 ❌
若使用 raw 格式发送，需手动添加请求头：Content-Type: application/graphql

4. 使用变量（Variables）

硬编码参数不仅难维护，还容易出错。Postman 提供了 GraphQL VARIABLES 区域，支持以 JSON 格式传入动态变量。

修改查询语句

将 count 和 offset 改为变量传入：

query recentPosts ($count: Int, $offset: Int) {
    recentPosts (count: $count, offset: $offset) {
        id
        title
        text
        category
    }
}

设置变量值

在下方 GRAPHQL VARIABLES 区域填写 JSON：

{
  "count": 1,
  "offset": 0
}

✅ 实际效果：参数与查询逻辑分离，便于复用和批量测试。

5. 总结

Postman 对 GraphQL 的支持非常成熟，具备以下优势：

✅ 原生支持 GraphQL 请求体格式
✅ 支持 Schema 导入与请求集合自动生成
✅ 提供变量管理，避免硬编码
✅ 自动补全 + 语法高亮，提升编写效率

对于团队协作或接口调试，建议将测试集合导出并共享。相关示例可在 GitHub 获取：
https://github.com/eugenp/tutorials/tree/master/spring-boot-modules/spring-boot-graphql

📌 踩坑提醒：别忘了给每个操作加上名字（如 query GetRecentPosts），否则线上出问题时你会后悔没这么做。

Persistence

REST

Security