RESTful API URL设计规范详解

本文深入剖析了RESTful API在PHP环境下的URL设计核心规范，强调PHP本身并无内置REST支持，必须通过框架或原生逻辑严谨实现——URL须严格使用复数名词标识资源、彻底禁用动词，动作语义交由HTTP方法承载；嵌套资源需克制（建议不超过两层），版本号必须显式置于路径而非Header或查询参数；路由必须显式绑定HTTP方法，杜绝模糊分发；更重要的是，真正的RESTful实践绝非仅改路径名，而是URL设计、HTTP方法、状态码、响应格式与错误结构的深度协同——忽略任一环节，都只是徒有其表的伪REST。

PHP 本身不内置 RESTful 路由或架构，所谓“PHP 的 RESTful 架构”本质是用 PHP（配合框架或原生逻辑）实现符合 REST 原则的 URL 设计、HTTP 方法映射和资源响应。URL 规范不是靠语言强制，而是靠开发者约定 + 路由层约束。

URL 必须以名词复数表示资源，禁止动词

REST 的核心是“资源”，不是“动作”。把 /api/user/getById 或 /api/deleteUser 这类写法换成 /api/users 和 /api/users/123。动词应通过 HTTP 方法体现：GET 查、POST 新增、PUT/PATCH 修改、DELETE 删除。

常见错误包括：

• /api/getUsers → 应为 /api/users（GET 已隐含“获取”）
• /api/createOrder → 应为 /api/orders（POST 请求体带数据）
• /api/users/list?status=active → 应为 /api/users?status=active（过滤是查询参数，不是路径动词）

嵌套资源要克制，避免超过两层深度

嵌套用于表达强所属关系，比如订单属于用户，可用 /api/users/123/orders；但若再嵌套到订单下的商品项（/api/users/123/orders/456/items），就容易失控。此时更合理的是扁平化：用查询参数关联，如 /api/items?order_id=456。

判断是否该嵌套的关键是：

• 该子资源是否**只在父资源上下文中存在且无独立生命周期**？
• 是否频繁被一起读取或批量操作？
• API 消费者是否真的需要这个层级语义？还是只是开发者图方便写路由？

版本号必须放在 URL 路径中，不能只靠 Header

虽然 RFC 允许用 Accept: application/vnd.myapi.v2+json，但实践中绝大多数 PHP 框架（Laravel、Slim、Symfony）默认不解析这种 header 做路由分发，而且调试、缓存、CDN、日志追踪都更难。直接写成 /api/v1/users 或 /v2/users 更可靠。

注意点：

• 版本号是路径段，不是查询参数（?v=2 不可取）
• 初始上线建议从 v1 开始，不要用 v0 或无版本
• 不要在同一个 URL 上混用多个版本逻辑（例如用 if 判断 $_GET['v'] 分支）——这违背了 URL 即资源标识的原则

PHP 路由实现时，必须显式声明支持的 HTTP 方法

原生 PHP 没有路由表，靠 $_SERVER['REQUEST_METHOD'] 和 parse_url($_SERVER['REQUEST_URI']) 手动分发极易出错。即使使用框架，也要检查是否真正绑定了方法，而不是只靠 URL 匹配。

例如 Laravel 中正确写法是：

Route::get('/api/v1/users', [UserController::class, 'index']);
Route::post('/api/v1/users', [UserController::class, 'store']);
Route::put('/api/v1/users/{id}', [UserController::class, 'update']);
Route::delete('/api/v1/users/{id}', [UserController::class, 'destroy']);

错误写法包括：

• 全部用 Route::any() 然后在控制器里 switch $_SERVER['REQUEST_METHOD'] —— 绕过框架方法校验，OPTIONS 预检失败，CORS 易出问题
• 没声明 HEAD 或 OPTIONS，导致前端 fetch 自动预检失败，报 405 Method Not Allowed
• 用 $_GET 模拟 PUT/PATCH（如 ?_method=PUT），破坏 REST 纯度，且 Nginx/Apache 可能拦截

最易被忽略的一点：URL 规范只有在与 HTTP 方法、状态码、响应格式（如统一 application/json）、错误结构（如 { "error": { "code": "not_found", "message": "User not found" } }）协同时才真正成立。单独改路径名，其他全照旧，只是徒有其表。

今天关于《RESTful API URL设计规范详解》的内容介绍就到此结束，如果有什么疑问或者建议，可以在golang学习网公众号下多多回复交流；文中若有不正之处，也希望回复留言以告知！