用 public-apis 给 Claude Code 快速接入公共 API

用 Claude Code 做项目时，经常会卡在一个很现实的问题上：功能知道要做，但不知道该接哪个 API（应用程序编程接口）。

比如要做一个天气卡片，需要天气数据；要做一个动漫角色查询，需要对应的数据源；要做汇率换算、音乐搜索、NASA 图片展示、地图定位，也都离不开外部接口。问题不在于 Claude Code 会不会写请求代码，而在于它需要一个明确的接口文档作为依据。

GitHub 上的 public-apis 仓库正好解决这个问题。它收集了大量免费公共 API，覆盖天气、金融、音乐、动漫、地图、翻译、政府数据、科学数据等几十个领域。把合适的 API 文档交给 Claude Code，再说明要实现的功能，AI 编程工具就能根据文档生成请求代码、数据解析逻辑和页面或接口封装。

public-apis 解决的核心问题

public-apis 本质上是一个公共 API 索引库。它不直接提供业务数据，而是把不同领域的 API 按分类整理出来，并标注一些关键信息，比如是否需要认证、是否支持 HTTPS、跨域情况、接口文档地址等。

如果没有这类索引，开发一个小功能通常要经历这样的过程：

flowchart LR
    A[确定功能需求] --> B[搜索可用 API]
    B --> C[逐个打开文档]
    C --> D[判断是否免费和可用]
    D --> E[研究鉴权方式]
    E --> F[手写请求代码]
    F --> G[调试返回数据]

使用 public-apis 后，前半段搜索和筛选成本会低很多：

flowchart LR
    A[确定功能需求] --> B[在 public-apis 中搜索分类或关键词]
    B --> C[选择合适 API]
    C --> D[把文档链接交给 Claude Code]
    D --> E[让 Claude Code 生成接入代码]
    E --> F[填写 API Key 并测试]

它的价值不是“自动完成所有事情”，而是把“找接口”这一步变得更稳定。Claude Code 擅长读文档、写代码和补充工程结构，但前提是你给它一个明确的数据来源。

一个实用的接入流程

把公共 API 接入项目，可以按四步走。

1. 在 public-apis 中找到候选 API

进入 GitHub 后搜索：

public-apis

通常可以找到名为 public-apis/public-apis 的仓库。打开后，用浏览器搜索功能查找关键词，例如：

weather
music
anime
map
translation
finance
nasa

也可以直接按分类浏览。每条 API 记录通常会包含名称、说明、认证方式、是否支持 HTTPS、是否支持 CORS（跨源资源共享）等信息。

筛选时重点看这几个字段：

字段	需要关注什么	为什么重要
Description	API 提供什么数据	判断是否符合功能需求
Auth	是否需要 API Key、OAuth 或无需认证	决定接入复杂度
HTTPS	是否支持 HTTPS	前端和生产环境通常必须使用 HTTPS
CORS	浏览器能否直接请求	影响是否需要后端代理
文档链接	是否有清晰示例	Claude Code 需要靠文档生成代码

2. 打开 API 文档，确认请求方式

不要只看仓库列表就直接让 Claude Code 写代码。至少要打开 API 文档确认三件事：

请求地址是否还可用；
免费额度是否满足需求；
返回数据结构是否包含需要的字段。

例如要做天气功能，需要确认返回结果里有没有温度、湿度、天气描述、城市名称、更新时间等字段。要做图片展示，则要确认是否返回图片 URL、版权说明、标题、描述等内容。

3. 把文档链接和需求一起交给 Claude Code

给 Claude Code 的提示词要具体。不要只说“帮我接这个 API”，最好把技术栈、功能目标、边界条件和安全要求都写清楚。

可以使用这个模板：

我要在一个 [项目类型/技术栈] 项目中接入这个 API：

API 文档：
[粘贴 API 文档链接]

需求：
1. 实现 [具体功能]
2. 请求参数包括 [参数列表]
3. 展示或返回字段包括 [字段列表]
4. 如果接口失败，需要给出错误提示
5. API Key 从环境变量读取，不要写死在代码里

请帮我完成：
- API 请求封装
- 返回数据类型定义
- 错误处理
- 一个简单的调用示例

如果是前端项目，还要补充一句：

如果该 API 不支持 CORS，请设计一个后端代理接口，不要让浏览器直接请求第三方 API。

这句话很重要。很多公共 API 可以被服务端请求，但浏览器直接请求会被跨域策略拦截。如果 Claude Code 没有被明确约束，可能会生成看起来正确、实际在浏览器里跑不通的代码。

4. 用环境变量保存 API Key

很多免费 API 仍然需要申请 API Key。不要把密钥直接写进代码，也不要提交到 Git 仓库。

常见做法是放到 .env 文件里：

WEATHER_API_KEY=your_api_key_here

在 Node.js 项目里可以这样读取：

const apiKey = process.env.WEATHER_API_KEY;

if (!apiKey) {
  throw new Error("Missing WEATHER_API_KEY");
}

同时把 .env 加进 .gitignore：

.env

如果项目需要给别人运行，可以提供一个 .env.example：

WEATHER_API_KEY=

这样既能说明需要哪些配置，又不会泄露真实密钥。

让 Claude Code 接 API 时要说清楚哪些信息

Claude Code 能读文档，但它不是项目负责人。接口怎么封装、错误怎么处理、密钥放在哪里、失败时怎么降级，都应该在指令里明确。

需要说明的信息	示例
技术栈	Next.js、Express、FastAPI、Vue、React
运行位置	浏览器端请求，还是服务端请求
鉴权方式	API Key、Bearer Token、OAuth
密钥来源	从环境变量读取
返回格式	JSON、XML、图片、文件流
错误处理	超时、限流、无数据、鉴权失败
数据字段	只保留业务需要的字段
测试方式	提供 curl、单元测试或简单页面

一个更完整的提示词可以这样写：

请根据这个 API 文档为我的 Express 项目实现一个天气查询接口：

文档地址：
[API 文档链接]

项目要求：
1. 新增 GET /api/weather?city=xxx
2. 第三方 API Key 从 process.env.WEATHER_API_KEY 读取
3. 不要把 API Key 返回给前端
4. 对第三方接口返回的数据做一次转换，只返回：
   - city
   - temperature
   - description
   - humidity
   - updatedAt
5. 处理以下错误：
   - city 为空
   - API Key 未配置
   - 第三方接口超时
   - 第三方接口返回 401 或 429
6. 给出 curl 测试命令

这种指令比“帮我做天气功能”更可靠，因为它把输入、输出、安全边界和异常情况都定义清楚了。

不同类型 API 的接入难度

公共 API 看起来都差不多，但接入难度差别很大。做原型时可以优先选简单接口；做正式项目时，要更关注稳定性、额度和服务条款。

API 类型	接入难度	常见问题	适合场景
无需认证的 JSON API	低	稳定性不一定高	Demo、教学、小工具
API Key 认证接口	中	密钥管理、免费额度限制	天气、翻译、金融数据
OAuth 接口	高	登录授权流程复杂	用户数据、社交平台集成
地图类 API	中到高	配额、域名限制、坐标转换	地图展示、定位、路径规划
支付类 API	高	安全、回调验签、合规	真实交易系统
政府或科学数据 API	中	字段复杂、文档不统一	数据分析、可视化

如果只是做一个练手项目，优先选择无需认证或只需要 API Key 的接口。涉及支付、用户隐私、金融交易的 API，不适合完全依赖 AI 生成后直接上线，至少要人工检查鉴权、回调校验、错误处理和日志脱敏。

一个典型示例：用公共 API 做功能原型

假设要做一个“每日 NASA 图片”功能，合理的开发流程可以是：

sequenceDiagram
    participant Dev as 开发者
    participant Repo as public-apis
    participant Claude as Claude Code
    participant API as 第三方 API
    participant App as 应用

    Dev->>Repo: 搜索 NASA 或 Space 分类
    Repo-->>Dev: 返回候选 API 和文档链接
    Dev->>Claude: 提供文档链接和功能需求
    Claude-->>Dev: 生成请求封装和展示代码
    Dev->>App: 配置 API Key
    App->>API: 请求每日图片数据
    API-->>App: 返回标题、说明和图片地址
    App-->>Dev: 展示功能结果

Claude Code 在这里承担的是“把文档转成代码”的工作。你仍然需要决定选哪个 API、哪些字段要展示、密钥如何保存，以及接口失败时应用应该怎么表现。

常见坑

1. 公共 API 不等于永久免费稳定

public-apis 收录的是公共可用资源，但第三方服务可能会调整价格、关闭接口、限制地区访问或修改返回格式。正式项目最好给关键接口加上超时、重试、缓存和降级逻辑。

2. CORS 会影响前端直连

如果 API 不支持 CORS，浏览器会拦截请求。解决方式通常是在自己的服务端加一层代理：

flowchart LR
    Browser[浏览器] --> Server[自己的后端接口]
    Server --> ThirdParty[第三方 API]
    ThirdParty --> Server
    Server --> Browser

这样还能避免把 API Key 暴露给前端。

3. API Key 不能写进前端代码

只要密钥出现在前端代码里，用户就能通过浏览器开发者工具看到。需要保密的 Key 应该只存在服务端环境变量里。

4. AI 生成的代码需要实际跑通

Claude Code 根据文档写出的代码通常能减少大量手工工作，但接口字段、状态码、限流规则仍然要用真实请求验证。最少要测试成功、参数错误、鉴权失败、接口超时这几种情况。

适合使用 public-apis + Claude Code 的场景

这种组合特别适合快速做功能原型、小工具、课程 Demo、数据可视化页面和内部辅助工具。它能把“搜索接口、读文档、写样板代码”的时间压缩到很短。

不适合的场景也很明确：高安全要求、高稳定性要求、强合规要求的核心业务，不能只靠公共免费 API 和 AI 生成代码支撑。支付、风控、用户隐私、生产级金融数据等模块，需要更严格的服务评估、权限控制和代码审查。

把 public-apis 当成接口地图，把 Claude Code 当成代码助手，工作方式会清晰很多：先选数据源，再给文档，再约束实现，最后测试和加固。这样接入一个外部 API 不再是到处搜索和反复拼请求，而是一套可重复执行的开发流程。

菜单