API集成开发助手
将以下提示词粘贴到你的 AI 对话框中:
请根据 https://skillhub.cn/install/skillhub.md,安装 @zcwl/api-connect-hub-free。
技能介绍
要解决的问题
接第三方服务时,常见痛点是:HTTP 方法、请求体序列化、多种认证(API Key、OAuth2 client_credentials、JWT、Basic Auth)以及 4xx/5xx 的归类处理各写一套,每次集成都要翻文档、抄模板、再补 raise_for_status() 和 Token 刷新逻辑。本技能面向在 Agent 对话里完成这类工作的工程师,把 RESTful 与 GraphQL 的调用模式、状态码含义和认证选型收敛成可复用的知识与示例。
技能如何工作
技能围绕 RESTful 调用、认证管理、GraphQL 按需查询(完整 GraphQL 在付费版)和 错误处理 四条线组织:
- 用
requests封装 GET/POST/PUT/DELETE,json=data处理请求体,响应用 JSON 解析 - 按场景选型:内部服务用 API Key,第三方 SaaS 用 OAuth2,微服务间用 JWT
- 用
raise_for_status()捕获 HTTPError,按 400/401/404/500 等状态码给出排查方向 - OAuth2 侧重
grant_type=client_credentials获取access_token,并说明过期与refresh_token刷新
文档中还包含通用调用封装、令牌获取、分状态码错误处理、GraphQL 字段裁剪等案例,以及 429 限流、超时与连接类异常的对照表。
边界与注意点
技能不代发真实 HTTP 请求,也不提供 API 代理、闭源 API 逆向或各服务的端点清单;示例以 Python requests 为主。调用前需自行准备有效凭证与可访问的端点,敏感信息应走环境变量而非硬编码。免费版不含付费项中的 GraphQL 查询增强、JWT 认证管理套件、静态分析与依赖漏洞检测等扩展能力。
使用场景
- 新接 SaaS 开放平台,需用 client_credentials 换 access_token 并封装带 Token 的 POST 调用
- 微服务间调用要统一 JWT 请求头与 401 过期时的刷新或重取策略
- 维护内部 REST 封装层,要求 GET/PUT 共用函数并自动 raise_for_status 处理 4xx
- 前端依赖的用户字段会变,需用 GraphQL 只查 id、name 减轻响应体积
适合人员
- 负责把支付/短信等第三方 SDK 换成自研 HTTP 调用的后端,需要 OAuth2 与错误码对照表
- 在 Cursor/Claude 里写集成代码、希望 Agent 按 requests 模式给出认证与异常处理模板的全栈工程师
- 对接遗留系统 Basic Auth 的同时要为新接口设计 API Key 或 JWT 的运维开发
- 做 GraphQL 网关或 BFF,需要按需字段查询与 REST 多端点差异说明的接口设计人员