API设计实战案例：手把手教你构建天气查询接口

API 设计实战案例：从零构建一个天气查询 接口

你在开发一个小程序，需要实时获取城市天气。最直接的方式不是自己去爬气象局网页，而是调用一个结构清晰、易于使用的API。这背后，就是API设计的功夫。

我们以设计一个天气查询API为例，看看实际项目中该怎么动手。

假设你的产品只需要展示“城市今天的温度、天气状况、风速”。不需要历史数据、不需要逐小时预报。这时候，接口就不该堆一堆用不上的字段，简洁才是王道。

用户输入城市名，返回三个关键信息就够了。比如请求北京天气，响应应该是这样：

{
  "city": "北京",
  "temperature": "26°C",
  "condition": "晴",
  "wind_speed": "3.5m/s"
}

别整花里胡哨的路径。用户要查天气，就用 /weather 最直白。城市名通过查询参数传进来：

GET /weather?city=上海

如果城市名带空格或中文，浏览器会自动编码，服务端再解码处理就行。这种设计谁看了都懂，前端同事接起来也省心。

城市输错了，比如“北平”，查不到怎么办？不能返回200加个错误提示。正确做法是返回404：

HTTP/1.1 404 Not Found
{
  "error": "City not found"
}

参数没传city？那是客户端犯错，返回400更合适。服务器炸了？500甩出去，顺便记个日志排查问题。这些状态码就像交通信号灯，各司其职，前后端沟通才顺畅。

上线三个月后，产品经理说要加“空气质量”字段。直接往原接口加？万一老版本App崩溃了呢。聪明的做法是发布v2：

GET /v2/weather?city=深圳

v1照常运行，v2慢慢推广。等所有客户端都切过去了，再下线旧版。这种小细节，能避免半夜被报警电话吵醒。

你这个接口火了，有人写脚本每秒请求几百次。不设防的话，服务器资源很快就被耗尽。简单加个限流策略：

同一个IP每分钟最多60次请求。超过就返回429：

HTTP/1.1 429 Too Many Requests
{
  "error": "Rate limit exceeded"
}

用Redis记录每个IP的请求次数，几行代码就能搞定。别等到系统瘫痪才想起来补漏。

真实的API设计，就是在功能、性能和维护性之间找平衡。不是写完能跑就行，而是要考虑谁会调、怎么调、出问题怎么查。每一个字段、每一个状态码，都是在和未来对话。