SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场hashnode-api

hashnode-api

编程与开发

查看项目

更新于 10-16 04:44

技能介绍

用途

本技能为 Hashnode GraphQL API 提供全面协助，适用于在 Hashnode 平台上进行博客管理、内容创建和用户交互。当需要构建与 Hashnode 博客或出版物的集成、查询 Hashnode 文章/用户/出版物数据、通过 API 创建发布或管理博客文章、使用 Hashnode 个人访问令牌实现认证、处理 Hashnode 的 GraphQL 查询或变更、调试 Hashnode API 响应或错误码、为 Hashnode 数据设置分页（基于游标或基于偏移）、实现新闻订阅/评论/用户交互，以及从旧版 Hashnode API 迁移到新的 GQL 端点时，应触发本技能。

主要能力

API 端点

所有 Hashnode API 请求通过单一 GraphQL 端点进行：

  • 端点：https://gql.hashnode.com（仅 POST）
  • Playground：在浏览器中访问同一 URL 即可探索 API
  • 旧版 API：https://api.hashnode.com 已停用，需迁移到新端点

认证

  • 大部分查询无需认证即可工作
  • 敏感字段（草稿、邮箱等）需要认证
  • 所有变更操作都需要认证
  • 认证方式：在 Authorization 头中添加个人访问令牌（PAT）
  • 获取 PAT：https://hashnode.com/settings/developer → "Generate New Token"

速率限制

  • 查询：每分钟 20,000 次请求
  • 变更：每分钟 500 次请求

缓存

  • 几乎所有查询响应在边缘缓存
  • 变更数据时缓存自动清除
  • 可在 playground 中查看缓存状态（右下角：HIT/MISS）
  • 重要：始终请求 id 字段以避免陈旧数据

错误码

常见 GraphQL 错误码：

  • GRAPHQL_VALIDATION_FAILED - 查询结构无效
  • UNAUTHENTICATED - 缺少或无效的认证令牌
  • FORBIDDEN - 权限不足
  • BAD_USER_INPUT - 输入数据无效
  • NOT_FOUND - 资源不存在

使用方式

快速参考示例

  1. 获取出版物详情：通过主机名查询出版物的基本信息，包括 id、isTeam、title 和 about.markdown。

  2. 获取最近博客文章：检索出版物的最新 10 篇文章，支持基于游标的分页，返回 id、title、brief、url 以及 pageInfo 中的 endCursor 和 hasNextPage。

  3. 按 slug 获取单篇文章：使用文章 slug 和出版物主机名获取特定文章的完整内容，包括 markdown 和 html 格式。

  4. 基于游标的分页（无限滚动）：将上一次响应中的 endCursor 作为 after 参数来获取下一页。

  5. 基于偏移的分页（传统分页）：使用明确的页码在页面之间导航，返回 hasNextPage、hasPreviousPage、previousPage、nextPage。

  6. 获取实体计数：使用 totalDocuments 字段在不获取全部数据的情况下获取计数。

  7. 获取系列中的文章：获取属于特定系列的所有文章。

  8. 获取静态页面：检索自定义静态页面，如 "About"、"Contact" 等。

  9. 获取单个静态页面：按 slug 获取特定静态页面的内容。

  10. 认证示例 - 获取草稿（需要认证）：草稿只能由出版物所有者通过有效认证查询，需在 Headers 中设置 Authorization 为个人访问令牌。

参考文件

本技能在 references/ 中包含完整文档：

  • api.md - 完整的 Hashnode GraphQL API 文档，包括：GQL Playground 概述、缓存行为与最佳实践、速率限制与认证、状态码与错误处理、分页方法（基于游标和基于偏移）、从旧版 API 的迁移指南、查询与变更示例、可用查询与变更的完整列表。

适用场景

构建博客前端

  • 获取出版物元数据
  • 获取带分页的文章列表
  • 按 slug 显示单篇文章
  • 实现系列/分类导航
  • 显示静态页面（关于、联系）

内容管理仪表板

  • 使用 PAT 认证
  • 列出和管理草稿
  • 发布/更新文章
  • 安排内容
  • 监控分析

新闻订阅集成

  • 订阅/取消订阅用户
  • 获取订阅者数量
  • 管理邮件偏好
  • 跟踪参与度指标

从旧版 API 迁移

  • 将端点从 api.hashnode.com 更新为 gql.hashnode.com
  • 将 REST 调用转换为 GraphQL 查询
  • 更新认证机制（查阅文档）
  • 将旧格式分页调整为基于游标/偏移的分页
  • 为新错误码更新错误处理

限制与注意事项

  • 始终在对象上请求 id 字段以避免陈旧的缓存数据
  • 速率限制较为宽松，但在生产应用中应遵守
  • 缓存行为：大多数响应被缓存；变更操作会自动清除相关缓存
  • 破坏性变更很少，并会在 Discord 上提前公告
  • 旧版 API 已关闭，仅使用 gql.hashnode.com

故障排除

  • 遇到 UNAUTHENTICATED 错误：验证个人访问令牌是否有效、检查 Authorization 头是否正确设置、确保请求的字段需要认证（草稿、邮箱等）
  • 看不到最新数据：始终请求 id 字段以避免陈旧缓存数据、在 playground 中检查响应是 HIT 还是 MISS
  • 查询验证失败：先在 playground 中验证 GraphQL 语法、检查是否提供了必需参数、确保字段名与 schema 匹配
  • 达到速率限制：查询 20k/分钟非常宽松，优化查询；变更 500/分钟限制，尽可能批量操作；在本地使用缓存以减少 API 调用

资源

  • API 文档：https://apidocs.hashnode.com
  • Playground：https://gql.hashnode.com
  • Discord：加入以获取更新和社区支持
  • GraphQL 指南：freeCodeCamp 的初学者友好 GraphQL 指南

本技能根据官方 Hashnode 文档自动生成。如需使用更新后的文档刷新，请使用 https://apidocs.hashnode.com 的最新文档重新生成技能。