927 - API设计规范：让接口像煎饼菜单一样清晰

927 - API设计规范：让接口像煎饼菜单一样清晰

一份好的煎饼菜单，顾客一看就知道点什么、多少钱、什么口味。一份好的API文档，开发者一看就知道调什么接口、传什么参数、返回什么结果。菜单混乱，顾客跑了；API混乱，对接的开发跑了。

一、为什么API设计如此重要？

API是系统对外的"脸面"，好的API让对接效率翻倍，差的API让双方都痛苦：

• 好API： 文档清晰、命名一致、错误明确、版本可控
• 差API： 命名随心所欲、返回结构不一致、错误码看不懂、改了不通知

煎饼摊比喻：好的菜单"煎饼5元、加蛋1元、加火腿2元"一目了然；差的菜单"特色A套餐、豪华B套餐"——鬼知道里面有什么。

二、RESTful API设计原则

2.1 URL设计

资源用名词，操作用HTTP方法：

❌ 错误示范：
GET  /getUsers
POST /createUser
PUT  /updateUser/123
DELETE /deleteUser/123

✅ 正确示范：
GET    /users           获取用户列表
POST   /users