资源路由必须用复数名词，禁止动词化路径；应建模为名词集合如/users、/products；Laravel的Route::apiResource()自动生成7个标准REST路由；避免单数歧义、深层嵌套、路径式版本控制及硬编码URL，需正确使用HTTP状态码与HATEOAS。
资源路由必须用复数名词，且禁止动词化路径
直接写 /getUsers 或 /deleteProductById 是典型反模式——它暴露实现细节、破坏资源抽象，还让前端无法通过 URL 推断语义。正确做法是把所有资源当作名词集合来建模：/users、/products、/orders。Laravel 的 Route::apiResource('users', 'UserController') 就是基于这个原则自动生成 7 个标准路由（含 index、show、store 等），你不用手动拼 POST /createUser 这种东西。
常见错误包括：
- 用单数
/user表示集合（GET 请求本意是批量获取，单数易误解为“默认用户”） - 嵌套过深，比如
/users/123/posts/456/comments/789—— 实际应拆成/comments?post_id=456&user_id=123或至少限制两层嵌套 - 把过滤逻辑塞进路径，如
/activeUsers，应统一走查询参数：/users?status=active
API 版本控制别硬塞在 URL 路径里
写成 /v1/users 看似直观，但会导致缓存失效、CDN 难配置、客户端升级成本高（所有 URL 都得改）。更合理的做法是用请求头传递版本信息：Accept: application/vnd.myapp.v1+json。Laravel 可配合中间件解析该 header 并路由到对应控制器；Slim 则可用 $app->add(new VersionMiddleware()) 拦截处理。
如果团队坚持路径版本，至少做到两点：
立即学习“PHP免费学习笔记（深入）”；
开箱即用的技能链路由引擎。13 条预定义链覆盖搜索、开发、审查、MLOps、法律、创意等场景，三层路由架构（触发词→SAD反馈→DAG编排），recall@10=96.97%。配置驱动（chains.yaml），零代码扩展。pip install skill-weave-chains 一键安装。
- 版本号只出现在最外层，不随资源变化：
/v1/users✅，/v1/users/v2/profiles❌ - 旧版接口至少保留 6 个月，且每次响应中带
Deprecationheader 提示下线时间 - 避免用日期做版本号（如
/2025-03/users），它暗示“临时性”，实际却要长期维护
HATEOAS 不是锦上添花，而是解耦刚需
没有 HATEOAS 的 API，前端就得硬编码一堆 URL 字符串，比如删用户时调 DELETE /users/123，一旦后端把路径改成 /v2/accounts/123，前端立刻报错。而启用 HATEOAS 后，响应体里会带链接：
{"id": 123, "name": "Alice", "_links": {"self": "/users/123", "delete": "/users/123", "related": "/users/123/posts"}}
PHP 生态里最成熟的是 willdurand/Hateoas 库，用注解驱动，不侵入业务逻辑：
- 在实体类加
@Hateoas\Relation("self", href = "expr('/users/' ~ object.getId())") - 序列化时调用
$hateoas->serialize($user, 'json')即可注入 _links - 注意：不要给每个字段都加 link，只暴露当前资源真正支持的操作（比如只读资源就不该有 delete 链接）
HTTP 状态码不能全用 200 + 自定义 code 字段
返回 {"code": 404, "message": "not found"} 是自我欺骗——HTTP 层已经失败，但状态码还是 200，导致 Nginx 日志、CDN 缓存、前端 axios 拦截器全部失效。必须让状态码真实反映结果：
- 创建成功用
201 Created，并带Locationheader 指向新资源（如Location: /users/456） - 更新部分字段用
PATCH+200 OK，全量替换用PUT+200或204 No Content - 删除成功优先用
204（无 body），若需返回摘要才用200 - 认证失败必须是
401 Unauthorized，权限不足才是403 Forbidden
最容易被忽略的是幂等性约束：同一个 PUT /users/123 请求发十次，结果必须一致；但 POST /users 发十次就得建十个用户。这点不遵守，前端重试机制或网关重放就会出数据污染。
