★ FEATURED ARTICLE 1. 先说我为什么放着现成接口库不用非要自己攒一份“接口超市”上个月我在写一个小程序想在前端页面里直接拉一组公开的景点数据做展示。需求很简单有地址、有图片、有评分就行。结果我去翻各类公共API文档翻了一个下午发现事情远没有“免费”两个字看着那么轻松。有的接口看着文档很全真调起来返回一堆HTML有的接口三个月前还在更新今天直接超时还有一批接口需要复杂的OAuth授权我本来只想做个Demo结果先花了两小时去申请权限。折腾完之后我意识到一个问题市面上的免费公共 API 其实非常多真正缺的不是数量而是一个能按类目快速定位、按可用性兜底的筛选清单。这个念头直接催生了后来这份被我叫作“接口超市”的索引——45个类目1400 个接口每一条我都按自己的方式验过一遍。很多人会觉得你直接搜“公共API列表”不就行了我也这么干过。问题是搜索结果质量参差不齐有的列表一年没更新有的接口已经停止服务但条目还挂在上面。如果你只是做毕设、写博客、跑个黑客松Demo时间成本比接口本身更贵。这份清单的定位一开始就不是“收集”而是“筛选”把看起来能用、实际也能用的接口挑出来按场景分组告诉你在什么项目里值得花时间去试。所以这篇文章不会只给你一份分类表。我会把“45个类目怎么分的”“1400接口怎么验的”“接入项目时最容易踩的坑”这些事情全部摊开讲。无论你是刚接触API的新手还是已经写过几年后端的老手多少都能在里面找到点能用得上的东西。1.1 起因调第三方接口调出一肚子火先说个具体例子。当时我需要在Demo里加一个汇率转换功能直觉告诉我这事肯定有免费接口。我去找了一圈发现好几个接口都需要注册拿Key注册页面还要求填公司信息。我填了个人博客地址转头就忘了这码事。后来找到一个不需要鉴权的公开接口试了一下返回的字段非常简洁就是一个数字。我当时很高兴立刻写进了前端还做了缓存。结果第二天早上再打开页面数字变成空了。排查半天发现那个接口的免费额度是按天算的我头一天下午测试时多刷了几次把当天额度耗光了。最坑的是文档里对这个限制只写了一行字不仔细看根本注意不到。就是这个场景让我下决心如果要做一份公共API清单“额度限制”“鉴权复杂度”“更新频率”这些信息必须和接口本身摆在一起不能只给一个链接。很多开发者被免费API坑了之后第一反应是“换一个接口”却很少有人把每次踩坑的原因记下来。那些被弃用的接口不一定是服务商的问题很可能是调用姿势不对。所以我在整理时给每个类目都加了备注字段专门记这种容易被忽略的坑。1.2 45个类目是怎么分出来的分类这件事听起来简单做起来很容易纠结。比如一个获取用户头像的接口到底算“社交”还是“图像处理”一个返回随机笑话的接口算“娱乐”还是“文本生成”如果分类太粗找接口时还是会大海捞针分类太细每个类目下面只有两三个接口又失去参考价值。我当时先按“使用场景”而不是“数据领域”来切。比如“金融”类目下面不只放货币汇率接口还放股票行情、加密货币实时价格、信用卡号生成这类测试数据再往下细分“支付相关”通常不放公共免费API因为涉及资金安全免费的大多不靠谱。最后我定了45个一级类目每个类目内有30到80个不等的接口总量加起来就是1400多个。还有一个原则宁可类目边界模糊也不要让某个类目变成垃圾筐。比如把“地理信息”和“地图导航”分开前者偏向坐标转换、行政区划数据后者偏向路径规划和地图展示。实际用到的时候边界越清楚越省时间。1.3 这份清单的定位不是收集是筛选我见过有人为了凑数把一些已经失效几个月的接口也写进列表这种列表最大的毛病是“看起来多用起来废”。我给这份清单定的标准很简单每一条都至少有基本的文档链接、请求示例和鉴权说明最好还提供一次真实可用的请求返回。有些接口虽然有各种各样的小毛病——比如偶尔超时、返回字段是缩写——但只要文档能自圆其说、免费额度够个人项目用我就会保留并在备注里写明“使用时要注意什么”。像那种文档半天找不到、请求返回毫无规律、更新日志停在两年以前的接口哪怕功能再诱人我也会标上“慎用”甚至直接砍掉。对我来说“1400 个接口”不是拿来炫耀的数字而是筛选之后的余量。所以你接下来看到的每个类目已经默认排除掉了一半以上“看上去能用”的条目。2. 1400 接口里的高价值区域我反复用到的那些类目整理清单的过程里我被问得最多的一句话是“这么多接口我到底从哪些开始看”我的答案比较直接先看你手头项目的类型不要为了用接口而用接口。但如果你只是想熟悉公共API的生态我可以给你几个我认为性价比最高的区域。2.1 开发工具与代码相关的接口最容易被低估很多人找接口时只盯着数据类比如天气、新闻、股票反而忽略了“开发工具”这个类目。实际上这类接口对开发者往往最有用。比如代码格式转换、域名信息查询、端口扫描检测、正则表达式测试、JWT解码、图片压缩、PDF生成。这些接口的共性是功能单一文档清晰不需要申请复杂权限。它们非常适合嵌进自己写的小工具里。比如我写过一个发布博客前的辅助脚本需要自动把草稿里的外链转成短链这个功能完全可以用一个支持短链生成的公开接口替代自建服务省去了自己维护跳转服务器的麻烦。这类接口还有一个好处因为目标用户就是开发者它们对请求错误、字段缺失的处理通常更规范很少出现返回200却带着一堆HTML页面的情况。就算免费额度低一点在个人项目里也完全够用。2.2 数据类接口天气、汇率、地理位置、新闻数据类是公共API里最庞大的家族也是我最常用的类目。天气接口适合做主页展示、行程提醒、智能家居面板汇率接口适合做记账工具、购物比价、个人财务面板地理位置接口可以用在物流演示、周边搜索原型上新闻接口则经常被用来做信息聚合阅读器。但数据类接口有它的特殊性最典型的就是“缓存策略”。天气数据其实每小时更新一次就够了如果你每次都直接请求远程接口不仅速度慢还会快速耗尽免费额度。我通常的做法是后端加一层本地缓存缓存时间按数据类型设置天气缓存30分钟汇率缓存1小时新闻缓存10分钟。这个细节我在后面会专门讲。选择数据类接口时我会先看两个东西一是数据更新时间二是是否提供字段过滤。有些接口一次返回几十KB的数据其实你只需要其中两个字段。如果支持过滤参数流量和解析压力都会小很多。2.3 内容生成与工具类接口文本处理、二维码、文件转换这类接口很有意思是“做Demo的好帮手”。比如你想给项目加一个二维码分享功能自己用前端库生成也可以但如果你在后端已经有一个聚合层调用一个二维码接口会更省事还能顺便做访问统计。文本处理类接口覆盖也很广从关键词提取、情感分析、语言检测到垃圾信息过滤都有免费的公共API。它的价值在于当你需要快速给用户内容打标签时不必先从训练模型开始。当然免费接口的分析精度通常有限我一般是把结果当成“初步判断”再结合自己的规则做二次过滤。文件转换类接口则更像一个“瑞士军刀”——把图片转格式、把Markdown转PDF、把音频转文字。这类接口的好坏特别依赖服务方是否稳定。所以我在清单里专门维护一个“文件转换”的状态标签一旦接口服务变更或者返回异常我会优先把这条标出问题避免后续使用的人踩坑。2.4 综合评估一份免费API质量的四个维度整理到后来我给自己定了一套评估API质量的框架不是只看“能不能调通”。维度核心问题我的判断标准文档完整度没有示例代码光看字段说明能不能起步至少要有请求参数表、返回示例、错误码说明可用性一周内随机抽三次请求成功率如何数据类接口成功率要高于95%工具类接口应高于98%免费额度透明度免费层是不是明确写着限制如果文档里找不到限制说明我会按“有风险”处理维护活跃度最近一年有没有更新日志一年以上不更新我会降级到“遗留”分区这四个维度不是说每一条都要满分但至少你得知道扣分点在哪里。比如一个维护了很久没更新的接口如果接口本身简单稳定还是可以用的。至少在个人项目里四年没变过的接口比三天两头改字段的接口更让人安心。3. 三步把免费 API 接进自己的项目附可直接抄的示例清单是死的接口是活的。我见过很多开发者收藏了一堆API最终还是卡在“第一次调用”这一步。下面这套流程是我自己试过很多遍之后固定下来的标准动作照着走可以从零开始把一个免费API稳定接入项目。3.1 第一步用调试工具验证接口可用性不管你最后打算用前端还是后端调用第一次验证都建议放在调试工具里做别急着写代码。我一般会开一个HTTP调试工具把接口文档里的请求地址填进去带上默认参数直接看返回结果。下面是一个典型的GET请求示例curl -X GET https://api.example.com/v1/weather?cityhangzhou \ -H Accept: application/json如果返回的是JSON而且结构和你期望的字段对得上第一步就算通过了。这里有一个很多人忽略的点要重点看Content-Type。有些接口虽然返回了JSON内容但响应头里的Content-Type写的是text/plain这时候很多HTTP客户端不会自动解析成JSON浏览器里也可能触发跨域问题。还有一个我常用的验证技巧故意传一个错误参数看接口怎么报错。一个文档完善的接口应该返回400加一个描述性消息而不是200加一个空对象。这个测试能帮你提前预判未来调用出错时你该怎么处理。3.2 第二步前端场景下的调用与跨域处理如果你在浏览器里直接调用第三方API最常遇到的拦路虎就是跨域。很多免费公共API为了安全考虑并不允许任意网页发起请求。这种情况下你有两条路可以走。第一条看接口文档里是否写明“支持跨域”也就是允许浏览器直接调用。支持的话你可以在前端直接写异步请求。拿JavaScript举例子async function fetchWeather(city) { const resp await fetch(https://api.example.com/v1/weather?city${city}); if (!resp.ok) throw new Error(HTTP ${resp.status}); return await resp.json(); }第二条如果你的接口不支持跨域绝不要试图用“禁用浏览器安全检查”的方式带过正确做法是走你自己的后端转发。这样既绕开了跨域问题又可以把API Key和调用逻辑藏在服务端避免泄漏。3.3 第三步后端加一层聚合封装避免被接口波动带崩调用第三方免费API最忌讳的是“把外部接口当成自己服务的一部分”。免费接口随时可能调整格式、限流、甚至临时宕机。如果核心业务逻辑直接和第三方API纠缠在一起对方一抖动你的项目就跟着抖。所以我会在后端加一个轻量聚合层。这个聚合层做的事很简单接收你的前端请求去调用第三方API拿到结果后做字段清洗、缓存和错误兜底再返回给你前端。前端感知不到第三方API的存在它只跟你自己的服务通信。比如用Node.js写一个简单的转发封装const express require(express); const app express(); app.get(/api/weather, async (req, res) { try { const remote await fetch(https://api.example.com/v1/weather?city${req.query.city}); const data await remote.json(); // 这里可以清洗字段、设置缓存决定返回给前端的内容 res.json({ ok: true, data: data }); } catch (err) { res.status(502).json({ ok: false, message: 上游接口暂时不可用 }); } });这个封装的价值在长期运行中才会显现你可以随时替换上游接口只要保证返回格式不变。今天用A接口明天发现额度不够直接换B接口前端一行代码都不用改。4. 真实踩坑记录鉴权、限流、数据不稳定如果只是把接口调通了后面的路才刚走了一半。真正让你头疼的往往是那些文档里没有大写标注的坑。我拿自己踩过的几个典型场景说说。4.1 三种鉴权方式怎么选免费公共API的鉴权方式主要有三种大多数没有中间态。鉴权方式特征适合场景坑点无鉴权直接请求URL测试Demo、一次性脚本额度极容易耗尽容易被滥用封IPAPI Key在Header或Query参数带一个密钥个人项目、可控场景Key千万别写进前端代码OAuth授权先换取Token再访问资源需要用户身份数据的场景流程复杂免费接口里不建议优先尝试无鉴权的接口最方便但也最危险。它意味着任何人都能消耗服务方资源所以这类接口通常有很强的限流策略。如果你在循环里没有做好延时控制可能请求到一半IP就被暂封了。API Key是多数免费接口的主流方式。使用时的最大禁忌就是直接写在浏览器代码里。因为任何人打开你的网页按一下F12都能看到。正确做法是放在后端环境变量里由服务端请求第三方接口。普通个人项目可以这样配置export API_KEYyour_secret_key4.2 429限流之后的重试策略免费API和付费API最大的区别就是限流简单粗暴。文档里写“每分钟60次”但具体到某一天或某个时段可能每分钟只有20次。一旦超过次数服务方会返回429 Too Many Requests。我最初的做法是看到429就立刻重试结果越试越惨最后把当天额度都耗光了。后来改成“指数退避”策略第一次失败等1秒再试第二次等2秒第三次等4秒最多等到30秒。这样既能避开瞬时峰值又不至于把服务方惹毛。另外一个实用技巧是看响应头里的Retry-After字段。很多限流接口会直接告诉你要等多少秒。如果它的值比你的重试间隔大那就以它的值为准。拿JavaScript写一个简化版逻辑async function fetchWithRetry(url, maxRetries 3) { for (let i 0; i maxRetries; i) { const resp await fetch(url); if (resp.status ! 429) return resp; const retryAfter Number(resp.headers.get(Retry-After) || 2); await new Promise(resolve setTimeout(resolve, retryAfter * 1000)); } throw new Error(上游限流重试失败); }4.3 数据结构和字段命名说变就变免费接口最让人头疼的还不是宕机而是“悄悄变化”。今天返回字段叫title过两周变成name了之前图片地址是完整URL突然变成带相对路径的字符串。这种变化一般不会通知你只有你代码里的解析开始报错才发现。我现在处理这个问题会做两件事。第一在聚合层做字段映射把第三方接口的字段名翻译成自己的标准字段名后续即使对方改了名字我只需要改映射层一行代码。第二监控响应结构的关键差异。比如写一个脚本定时拉一次接口检查字段数量、类型和关键字段是否存在一旦发现变化就把它标出来。这个小脚本成本很低但能省掉很多半夜排查问题的痛苦。从数据结构不稳定这个角度讲你能做的最有效策略就是“永远不要只依赖一个免费接口”。准备至少两个备选服务甚至可以把它们封装成同一个函数哪个失败就自动切换另一个。这就是我习惯叫“双保险”的做法。4.4 免费接口的数据质量脏值、缺失、时区问题免费接口的数据质量往往参差不齐。以天气接口为例有的城市完全没有数据返回一个空数组有的返回了温度但湿度字段是空字符串还有的接口时间戳用的是UTC到了你自己项目里不转换成北京时间显示就会差8小时。这类问题说大不大说小不小但如果在数据展示层不做处理用户会直接觉得你的产品有Bug。我的建议是拿到接口数据后先做一个“数据清洗”步骤。比如所有数字字段都先转成数字类型所有空字符串先转成null或默认值时间字段一律统一成时间戳或指定时区。做清洗的时候还要考虑边界情况比如接口返回的图片地址已经失效你的前端就会出现一张裂图。像这种问题可以在清洗阶段就用默认占位图兜底宁可显示一张“暂无图片”也比渲染一个破裂的图片标识要优雅得多。5. 如果你也想维护一份公共API清单这些坑要先知道写完这份清单之后有不少人问我“我也想整理一份该怎么开始”说实话整理公共API清单看起来只是分类和链接实际维护起来比想象中费时间。下面这几个坑是我踩过了才明白的。5.1 验证1400接口可用性的批量做法手动一个一个打开接口文档验证不现实我当时写了一个简单的批量检测脚本思路是读清单里的每个接口URL发送一个简单的HEAD或GET请求判断返回状态码是不是2xx或3xx。因为很多接口的测试请求并不需要完整参数有时候不带参数也会返回一个默认结果或错误提示只要不是网络不通就说明主机还活着。这个脚本需要注意两个问题之一是不能同时发太多请求否则你的IP很容易被对方封掉。我设置的是每10个请求暂停2秒再随机打乱顺序尽量模拟自然流量。之二是有一些接口必须带有效参数才肯回应直接请求根路径会返回404这种就不能只看状态码还得结合请求示例去判断。验证脚本跑完一轮只是开始真正的维护难点是“定期复验”。公共API的服务状态每个月都可能变化。我现在会每隔一两个月重新跑一遍完整验证把新增接口加进去把失联接口移到待确认区。这样清单才不会慢慢变成一堆过期链接。5.2 分类体系别一上来就求全我一开始分类很激进把接口按“数据来源”分比如政府、企业、社区。后来发现同一个接口可能既属于政府来源又属于地理信息还会被用在新闻类项目里一张条目根本不知道往哪里放。所以后来我改成“按调用场景”来分这个前面已经说过。还有一个经验是不要为了一两条接口单独开一个新类目。比如“宠物相关”如果只有一个狗脸识别接口放进“图像识别”里比单独列一个类目要合理得多。类目数量宁少勿多等到某个类目下面攒到十几条了再拆出来也不迟。维护文档的时候我会给每个类目配一个简单的“适合场景”说明。比如“金融”类目下面写一句“适合做个人记账、汇率展示不建议涉及真实交易”。这样搜索的人一眼就能判断这个类目是不是自己需要的省得点进去看半天还不知道用途。5.3 文档和示例请求的维护节奏很多公共API列表只给一个主页链接这在我看来体验很差。至少要记录几样东西接口基本地址、鉴权方式、是否需要申请Key、一个简单的请求示例、还有更新日期。这些信息一开始不过几十个字但能极大提升使用效率。我现在维护的条目最长的一条可以有几百字备注最短的一条可能只有三行。备注不是说要写成论文而是要把“怎么开始用”讲明白。尤其当接口返回的数据格式比较特殊时我会直接贴一小段JSON示例这样别人复制过去就知道怎么解析了。维护节奏上我不强求每天更新但每次跑完批量验证后我一定会把失败接口的记录整理出来逐个确认是临时故障还是永久停止服务临时故障的保留停服的立刻标为失效并挪到备份区。始终记住一件事一份清单的价值不在于条目数量而在于每条信息是否还能信得过。6. 写给自己和后来者的一些实话整理并维护这份免费公共 API 清单是我最近几个月做得最费工夫但回报也最直接的一件事。那些接口帮我把好几个Demo项目都快速跑通了省去了自己搭数据服务的成本。更重要的是这个过程让我对“依赖第三方服务”这件事有了更清醒的认识。我现在的习惯是任何一个免费公共接口默认先当“不稳定”对待而不是默认“能用”。接入之前先想好如果它挂了怎么办如果它限流了怎么办如果它数据结构变了怎么办把这三个问题想清楚再写下第一行调用代码后面会少很多临时救火的场景。接下来我打算再给这份清单加两个东西。一个是为每个类目补一份“典型项目案例”告诉大家这个类目的接口一般用在什么项目里方便新手照着做。另一个是做一个简单的本地离线检索版哪怕对方服务全挂了至少清单本身还能当资料查。这些都是慢功夫但我觉得值得做。如果你也想做一份类似的东西我的建议是别贪多先从自己最常用的五个类目开始把每条接口的文档看透、摸清踩坑点再慢慢扩。一千个接口的清单如果每个只能给你一个链接那它的价值其实很低反过来一百个接口的清单每个都写清“怎么用、有什么坑”那它就是一份很值钱的资产。
阅读完成 · 觉得有帮助？
