企业官网建设流程全解析

Mirror GraphQL API实战指南：查询文章、评论与用户信息的完整示例

【免费下载链接】MirrorA blogging tool powered by GitHub API. Write your blog on GitHub issue.项目地址: https://gitcode.com/gh_mirrors/mirror9/Mirror

Mirror 是一款基于 GitHub API 的开源博客工具，让你直接在 GitHub Issue 上写作和发布文章。本文是一份面向新手的GraphQL API 实战指南，通过完整示例带你掌握如何用 GraphQL 查询文章、评论与用户信息，帮助你理解博客背后的数据流，也为后续二次开发打下坚实基础。

Mirror 是什么？为什么要用 GraphQL API？

Mirror 的核心思路非常简单：把 GitHub 仓库中的 Issue 当作博客文章来管理。你只需要写好 Issue、打上标签，Mirror 就会自动把它渲染成一篇篇排版精美的博文。整个项目源码精简，非常适合作为学习与定制的对象。

与传统的 REST API 相比，GitHub GraphQL API 的优势一目了然：

• 🎯一次请求、按需取数：可以在同一条查询里拿到文章、作者、标签等数据，不多取无用字段
• 📦单一端点：所有查询都发往同一个 GraphQL 端点，无需拼接多个 URL
• 🔄游标分页：通过pageInfo返回的游标（Cursor）实现稳定的上下翻页

Mirror 的所有数据请求都集中在src/api/目录下，其中src/api/fetcher.js是统一的请求入口，src/api/index.js则对外暴露了四个方法，先通过一张表快速认识它们：

GraphQL API 请求入口与身份认证

Mirror 的所有 GraphQL 查询都以 POST 方式发送到 GitHub 的 GraphQL 端点https://api.github.com/graphql，请求体只有一个字段query。认证通过请求头Authorization: bearer <token>完成，而这个 token 在构建时会被加密写入配置，运行时再通过src/helper/secret.js中的解密函数还原，避免明文暴露在网页源码里。

也就是说，无论查询文章、评论还是用户信息，请求的"外壳"完全一样，唯一变化的只有query里的查询语句——一个入口，满足所有数据需求，这正是 GraphQL API 最方便的地方。

如何用 GraphQL 查询文章列表

查询文章列表是博客系统最核心的操作，对应源码src/api/issues.js，查询语句结构如下（简化示意）：

repository(owner: "用户名", name: "仓库名") { issues(first: 10, states: OPEN, orderBy: {field: UPDATED_AT, direction: DESC}) { pageInfo { hasPreviousPage startCursor hasNextPage endCursor } totalCount edges { node { number title author { avatarUrl login url } createdAt labels(first: 3) { edges { node { color name } } } } } } }

从示例可以看出，每个字段都是按需选取的：number是文章编号，title是标题，author是作者信息，labels是文章标签（相当于博客分类）。默认只查询OPEN状态的 Issue，并按UPDATED_AT或CREATED_AT倒序排列，确保最新更新的文章排在最前面。

文章分页查询技巧：游标分页

文章很多时就需要分页。GitHub GraphQL API 采用游标分页而非传统页码：每次查询返回的pageInfo中带有endCursor与hasNextPage，翻下一页时把endCursor作为after参数传入即可；同理，用startCursor与before组合可翻上一页。Mirror 的路由正是通过/after/:cursor与/before/:cursor实现首页上下翻页的。

如何用 GraphQL 查询文章详情

点击一篇文章后，Mirror 会根据文章编号发起详情查询，对应源码src/api/issue.js：

repository(owner: "用户名", name: "仓库名") { issue(number: 1) { title author { avatarUrl login url } bodyHTML updatedAt labels(first: 3) { edges { node { color name } } } comments { totalCount } } }

注意这里用的是issue(number: 1)而不是issues(...)，一字之差含义完全不同：复数形式返回文章列表，单数形式返回单篇文章。返回的bodyHTML是 GitHub 渲染好的 HTML 正文，Mirror 直接把它插入页面即可，无需自己解析 Markdown——这也是用 GitHub API 写博客的一大便利。

如何用 GraphQL 查询评论

评论数据在src/api/comments.js中查询，入口同样是issue(number)，只是进一步展开comments字段：

issue(number: 1) { comments(first: 10, after: "游标") { pageInfo { hasNextPage endCursor } totalCount edges { node { updatedAt bodyHTML author { avatarUrl login url } } } } }

评论默认每次加载 10 条，借助endCursor实现"加载更多"；当hasNextPage为false时说明没有更多评论了。Mirror 在前端还会缓存已加载的评论（见src/index.js中的mirror.comments），重复打开同一篇文章不会重复请求，体验非常顺滑。

如何用 GraphQL 查询用户信息

博客页面顶部需要展示博主信息，这部分由src/api/user.js负责。它同时支持个人用户与 Organization 组织两种对象：

# 个人用户 user(login: "用户名") { name login avatarUrl email websiteUrl url bio } # 组织 organization(login: "组织名") { name login avatarUrl organizationBillingEmail url }

一条查询就能拿到昵称、头像、邮箱、个人主页、简介等全部信息，前端拿到后直接渲染到页面侧边栏。这也是 GraphQL「按需取数」的典型体现——换成 REST 往往要请求多个接口才能凑齐这些字段。

GraphQL 查询失败怎么办？常见问题与调试技巧

• 🔑提示认证失败（401）：检查配置中的 token 是否加密正确、是否拥有对应仓库的读取权限
• 📝返回 errors 数组：GitHub GraphQL 的报错放在响应体的errors字段中，Mirror 在src/api/fetcher.js里会把每个错误的类型和消息拼接后抛出，方便定位
• 🔍提示字段不存在：注意区分issue与issues、user与organization，写错一个单词查询就会失败
• 💾数据不更新：Mirror 对文章、评论做了内存缓存，修改 Issue 后刷新页面即可看到最新内容

总结：用 GraphQL API 打造你的极简博客

通过这份 GraphQL API 实战指南，你应该已经掌握了 Mirror 查询文章、评论与用户信息的完整方法：统一入口src/api/fetcher.js、按需取数的查询语句、游标分页的翻页技巧，以及常见报错的排查思路。如果你是新手，可以直接把 Mirror 克隆到本地（仓库地址 https://gitcode.com/gh_mirrors/mirror9/Mirror），对照src/api/目录下的源码动手实践；想做二次开发的话，只需在src/api/中扩展新的查询方法，就能为博客增加更多 GraphQL 能力。希望这份完整示例能帮你快速上手，享受用 GitHub Issue 写博客的乐趣！🚀

【免费下载链接】MirrorA blogging tool powered by GitHub API. Write your blog on GitHub issue.项目地址: https://gitcode.com/gh_mirrors/mirror9/Mirror