RESTful API设计原则与最佳实践深度解析

003、RESTful API设计原则与最佳实践深度解析

上周排查一个线上问题，用户反馈订单状态偶尔会“跳变”。查日志发现前端轮询订单状态时，某次请求返回了完整的用户资源对象，里头包含历史状态字段，前端解析逻辑没处理好，直接显示了旧状态。问题的根源是什么？API端点设计违反了资源隔离原则——一个查询订单状态的接口，却返回了完整的用户资源。今天我们就聊聊RESTful API设计里那些容易踩坑的细节。

从资源建模开始

设计API的第一步不是想URL怎么拼，而是识别系统中的核心资源。订单就是订单，用户就是用户，别混在一起。我见过有人把/api/getOrderDetail?userId=123&orderId=456这种RPC风格的接口硬说成RESTful，这就像把自行车说成新能源车——不是加个轮子就能上路。

资源用名词复数，别用动词。/orders比/getAllOrders顺眼得多。HTTP方法已经表达了动作：GET获取，POST创建，PUT全量更新，PATCH部分更新，DELETE删除。那种所有请求都用POST，然后在body里塞个action: "delete"的做法，相当于用螺丝刀敲钉子——能干活，但看着难受。

URL设计的讲究

层级关系用嵌套要适度。/users/123/orders/456表达“用户123的订单456”很清晰，但别嵌套太深。超过三层就该想想是不是资源建模有问题。我调试过一个