做项目时发现，很多接口用着费劲：前端要反复适配不同格式的响应、迭代后旧版本直接崩溃、URL 命名混乱看不懂 —— 其实都是没遵循 RESTful 设计规范。分享 3 个核心原则 + 5 个实战避坑技巧，新手也能设计出行业认可的 “好用接口”（面试官常问，建议收藏）。
一、3 个核心原则（必遵守）
- URL 里别加动词！RESTful 的核心是 “资源导向”，URL 只描述 “资源是什么”，用 HTTP 方法（GET/POST/PUT/DELETE）描述 “做什么”。比如：
❌ 错误：/api/getUser（GET 本身就是查询，重复了）、/api/deleteUser/123（DELETE 方法已说明动作）
✅ 正确：查询用户用 GET /api/users/{id}、创建用户用 POST /api/users、更新用户用 PUT /api/users/{id}、删除用户用 DELETE /api/users/{id}
-
响应格式必须统一！不管成功还是失败，返回结构保持一致，前端不用反复写适配逻辑。标准格式：
{ "code": 状态码（200=成功，4xx=客户端错，5xx=服务端错）, "message": 描述信息（成功写"success"，失败写具体原因，比如"手机号格式错误"）, "data": 业务数据（成功返回结果，失败返回null）, "timestamp": 时间戳（便于排查问题）, "requestId": 请求ID（分布式系统排查问题的关键） }
反面例子：成功返回 {“name”:“张三”}，失败返回 {“error”:“参数错”}，前端要写两套解析逻辑，极易出错。
- 版本控制不能少！接口迭代时必须区分版本，避免旧版本用户报错。比如：/api/v1/users（V1 版本）、/api/v2/users（V2 版本），两者并行运行，等所有用户迁移到 V2 后，再逐步下线 V1。
二、5 个实战避坑技巧
- 资源命名用复数！比如 “用户” 用 users，“订单” 用 orders，而不是 user/order，符合 RESTful 惯例，也便于扩展（比如查询多个用户）。
- 过滤条件用查询参数！比如查询 “北京的已完成订单”，别写 /api/orders/beijing/completed，而是用 /api/v1/orders?city=beijing&status=completed，灵活且易维护。
- 避免深层嵌套 URL！比如查询 “用户 123 的订单 456 的详情”，别写 /api/v1/users/123/orders/456/detail，而是用 /api/v1/orders/456?userId=123，层级太深会导致 URL 冗长，且不易扩展。
- 响应数据按需返回！默认返回精简字段，允许前端用 fields 参数指定需要的字段，比如 /api/v1/users/123?fields=id,name,phone，减少数据传输量。
- 明确 HTTP 方法的语义！GET（查询）、POST（创建）、PUT（全量更新）、PATCH（部分更新）、DELETE（删除），别混用（比如用 GET 方法修改数据，会导致缓存问题）。
举个完整正面例子：查询 id=123 的用户，请求是 GET /api/v1/users/123，响应是：
{
"code": 200,
"message": "success",
"data": {"id": 123, "name": "张三", "phone": "138****5678"},
"timestamp": 1620000000000,
"requestId": "req-20240520101000001"
}
