在开发一个天气应用时，你可能会调用某个城市的实时气温数据。如果接口是 /getWeather?city=beijing，你能一眼看懂它的用途；但如果接口写成 /api/v1/data/123?id=456&type=2，你得翻文档、猜参数，甚至要抓包分析。这就是好API和烂API的区别。
统一风格，减少认知负担
一个团队多人协作时，最怕每个人写一套风格。有人用大写字母开头，有人下划线分隔，有人偏爱缩写。结果项目里出现 /getUserInfo、/add_user、/delUser 这种混搭，读代码像解谜。
建议采用小驼峰或中划线命名，并在整个项目中保持一致。比如全部使用小驼峰：
/userInfo
/userFriends
/updateUserProfile用对HTTP方法，别乱来
GET不是万能的“获取”按钮。它应该只用来查询数据，不能修改服务器状态。如果你看到一个GET请求把用户删了，那这设计就有问题。
正确做法是：
- GET 获取资源
- POST 创建资源
- PUT 全量更新
- PATCH 部分更新
- DELETE 删除资源
比如创建一个新任务：
POST /tasks
{
"title": "买牛奶",
"completed": false
}状态码别随便凑合
有些开发者图省事，所有成功都返回200，错误全用500。但客户端需要知道具体发生了什么。
合理的做法是：
200 OK - 请求成功
201 Created - 资源创建成功
400 Bad Request - 参数错误
401 Unauthorized - 未登录
403 Forbidden - 没权限
404 Not Found - 资源不存在
429 Too Many Requests - 请求太频繁
500 Internal Server Error - 服务器出错当用户连续登录失败被限流时，返回429比直接给个500更有意义。
版本控制留余地
上线后需求变了，接口也得跟着变。但老用户还在用旧版，不能一刀切。
在URL或请求头里带上版本号，比如：
/v1/users
/v2/users这样新功能可以在v2里加字段，老系统继续跑v1，平稳过渡。
返回结构尽量稳定
有时候成功返回一个对象，失败却只返回一段文字，前端处理起来特别麻烦。
统一包装响应体，结构更可控：
{
"code": 0,
"message": "success",
"data": {
"userId": 123,
"name": "Alice"
}
}即使出错，也保持这个结构，只是code非零，data可能为空。前端解析逻辑就能复用。
文档不是摆设
再规范的设计，没文档也白搭。用Swagger或Postman生成可交互文档，字段含义、示例、必填项都列清楚。
比如一个分页接口，注明 page 和 limit 的默认值是多少，最大能取多少，避免前端瞎试。
好的API设计，就像设计一把好用的钥匙——插进去顺滑，拧得动，还能适配未来的锁。