搜「和风天气API接口调用教程」的人,多半已经注册完账号、拿到一串 Key,然后卡在第一次请求返回 401 或 400 上。这篇不铺概念,按申请、拼请求、发请求、读响应的顺序走一遍,把每一格该填什么、填错了现象是什么写清楚。跑通之后要做产品还得继续看文档,但第一版能出数据,剩下的都好办。
搜「和风天气API接口调用教程」的人,多半已经注册完账号、手里攥着一串 Key,然后卡在第一次请求返回 401 或 400 上。这事儿不难,难在没人告诉你每一格该填什么、填错了界面会报什么。下面按申请、拼请求、发请求、读响应的顺序走一遍。
先说个判断:如果你已经能拿到 200 但数据不对,那说明鉴权过关了,问题在参数;如果压根连不上,先别改代码,去看 Host 用错没用错。这两种情况的排查方向完全相反,混着查最费时间。跑通一次最简请求之后,剩下的都是往上加字段。
申请这一步,先分清你拿到的是哪种凭证
控制台里的东西不是拿到 Key 就完事。有的账号要先建「项目」,Key 挂在项目下面;有的直接给你一串凭证。你不先看清楚自己处在哪一层,后面贴进代码的那串可能根本不是调用用的。进控制台先找有没有项目这一层,有就先建一个,再进去看凭证页。
凭证形态也可能不止一种:有的跟着具体接口走,有的能通吃多个接口;网页端用的那串和给后端用的那串不一定是一回事。把网页上显示的那串直接复制进后端代码,是很多人第一次 401 的直接原因。判断办法很简单,看凭证页面有没有写适用范围,写了就按它来。
- 项目
- 控制台里凭证的上一层容器,没有这层的账号可以直接看凭证
- Key 存放
- 进环境变量优先;如果进 git,先写进 .gitignore 再提交
- 适用范围
- 凭证页面会标注这个 Key 能用在哪类接口,贴代码前对一眼
还有个顺序问题:别急着把 Key 塞进正式项目。先建一个空目录、一个 .env、一行读取环境变量的代码,把最简请求跑通再往项目里搬。搬家过程里漏掉环境变量的加载,是第二次踩坑的常见场景。
拼请求之前,先确认 Host 和你的位置参数
地址这块是最容易想当然的地方。公共域和专属域是两套,账号类型决定你该用哪个。用错的现象不是参数报错,而是连不上或者连接被直接拒掉,所以很多人会误以为是网络问题,去查代理、查防火墙,绕一大圈。先对照文档确认你的账号对应哪套 Host。
Location 参数也有讲究。填地名和填经纬度两种写法,返回精度不一样,匹配到的地点也可能不一样。第一次调的时候,照文档给的示例格式原样抄一遍,不要自己发挥。格式对了再换成你实际要查的地点,这样出问题时能确定是格式还是数据的事。
| 你填的东西 | 常见填错的样子 | 大概率现象 |
|---|---|---|
| Host | 拿公共域的地址配专属账号 | 连不上,看起来像网络问题 |
| Location | 地名中间多空格、经纬度顺序反了 | 400,或者返回一个不相干的地点 |
| 参数名 | 大小写混了、多一个下划线 | 400,报参数不识别 |
| 请求头 | Key 贴在 URL 里而不是请求头 | 401,先核对位置再怀疑封号 |
参数别一上来就堆满。先用最简的一组拿到一份当前天气,确认链路从头到尾通了,再往上加字段、加语言、加单位。每加一组就发一次,出错时才知道是哪一组带进来的。这个习惯在换成正式业务参数之后会省很多事。
把请求发出去,然后逐字段对响应
先用 curl 或 Postman 发一次,别急着写代码。理由很实在:出问题时你能分清是请求本身有问题,还是你写的客户端有问题。发的时候把完整 URL、请求头、状态码都留一份记录,后面换语言重写时直接对照这份记录,比翻聊天记录靠谱。
- 拼出完整 URL按文档示例把 Host、路径、Location 和参数拼齐,参数用工具做个编码,别手敲
- 带上请求头把 Key 放在文档指定的头字段里,确认大小写和拼写
- 发出去并留存保存完整请求和原始响应体,不只是保存状态码;后面排查全靠这份原始记录
- 先读错误字段响应里除数据外还有状态码和错误信息字段,先看它们,再解析业务数据
解析失败的时候,第一件事是把原始响应体整个打印出来。很多「字段读不到」的问题,其实是响应外面包了一层、或者编码不是你以为的那种,字段名本身没写错。看到 JSON 就直接按文档字段去取,跳过看外层结构,是新手最常犯的动作。
报错和额度:三处最常踩的地方
401 这一类,先核对请求头,而不是怀疑账号被封。常见就三种:Key 根本没带、带的位置不对、凭证类型和接口不匹配。对着凭证页面的适用范围一项一项核,通常几分钟就能定位。核完还不对,再看是不是复制时把首尾空格带进去了。
400 这一类,重点看 Location 格式和参数名。参数名多一个下划线、大小写差一个字母,都会直接 400,不会给你「大概是这个意思」的宽容。拿文档的参数表逐条对一遍,比猜快。地名格式的,先原样抄示例;经纬度的,确认顺序没反。
额度这块要提前看清口径:按次算还是按天算,不同接口是不是分开算。本地联调时把循环测试的间隔拉开,别拿调试把额度耗掉。至于具体额度是多少,去站内页面核对当时的数字,别记在纸上,规则会变。
跑通之后,把这些数字留到站内核对
第一版能出数据,后面就是做产品的事。但接口规格、额度口径、延迟基线这些数字别凭印象记,去站内按类型筛一遍,把当时的口径截下来。后面行为变了、或者要接第二家天气接口时,你手里有可以对照的基准。
- 模型和接口规格对比,到 /models 按类型筛,别把规格记在纸上
- 写完第一版客户端,去 /tools/speed-test 量一次延迟基线,以后变慢才知道跟谁比
- 要接多家第三方接口,先看 /tools 里的目录页,口径对齐了再写适配层
- 各家 API 价格口径不一样,到 /price-watch 看当时的价格变动记录
顺带提一句,这套流程放到别的天气或第三方接口上也大致成立:先分清凭证类型,再确认 Host,再控制参数复杂度,最后读响应里的错误字段。区别只在字段名和参数表。习惯养成了,换接口就是换文档的事。
下一步把第一版请求跑通后,用站内的测速页量一次基线,并到模型与接口目录里对齐规格口径,后面加字段、换接口都有参照。→常见问题
和风天气 API 的 Key 能不能直接写在前端代码里?
不建议。前端代码打包后 Key 是明文可见的,别人拿去就能消耗你的额度。稳妥做法是自己起一层后端或 Serverless 转发,Key 放在服务端环境变量里,前端只调你自己的接口。如果只是本地临时验证,注意别把带 Key 的文件提交到仓库。
第一次请求返回 401,是不是账号或 Key 被封了?
先别往封号上想。绝大多数 401 是请求头里没带凭证、带了但格式不对,或者拿的是另一种用途的 Key 去调了不匹配的接口。把请求头打印出来逐字看一遍,再去控制台确认这个 Key 归属哪个项目。真要怀疑封禁,先看看控制台有没有提示。
本地调试时响应正常,上线后偶尔超时,从哪里查?
先区分是网络慢还是你自己的代码慢。在服务器上直接发同样的请求,看耗时;如果服务器上就慢,看出口网络和 DNS 解析。另外注意别在请求里塞太大的时间范围或过多字段,返回体越大越容易超时,可以先把字段收敛到够用为止。