Laravel文档应明确区分HTTP状态码（表征通信结果）与业务错误码（描述具体原因），如403仅表示请求不合法，而code:1003才表达“操作未授权”；需按REST动词+资源组合说明典型状态码及Laravel响应示例，并补充202、429等高频非标状态码使用场景。
在 Laravel 文档中清晰展示不同 HTTP 状态码对应的业务含义，关键不是罗列所有状态码，而是聚焦常见场景、区分协议层与业务层、并给出可落地的示例结构。文档要让开发者一眼明白“什么情况下该用哪个状态码”，同时避免混淆 HTTP 状态码和自定义业务错误码。
明确分层：HTTP 状态码 ≠ 业务错误码
文档开头需强调核心原则：HTTP 状态码描述通信结果（如 404 表示资源不存在），业务错误码（如 code: 1002）描述具体原因（如“用户余额不足”）。两者必须分离，不可混用。
- 错误写法：
return response(['code' => 403, 'msg' => '权限不足'], 403);—— 把业务含义塞进状态码，破坏语义 - 推荐写法：
return response(['code' => 1003, 'msg' => '操作未授权'], 403);—— 状态码表征请求合法性，code 字段承载业务逻辑 - 对外 API 文档中，应单独列出“HTTP 状态码说明表”和“业务错误码说明表”，不交叉解释
按动词+资源组合标注典型状态码
避免泛泛而谈“200 是成功”，而是结合 RESTful 操作习惯，说明每个接口动作下最可能返回的状态码及触发条件。
Laravel Cloud
下载
Laravel Cloud（cloud.laravel.com）。此技能用于处理所有 Laravel Cloud 请求，包括搜索和读取数据。只要任务涉及 Laravel Cloud，即使用此技能。
- GET /api/users/{id}：200（存在且可读）、404（ID 不存在）、403（有权限限制但当前用户无权访问）
- POST /api/orders：201（创建成功）、400（参数校验失败）、422（语义校验失败，如库存不足）、401（未登录）
- DELETE /api/posts/{id}：204（删除成功，无响应体）、404（资源已不存在）、409（存在关联数据，禁止删除）
用真实 Laravel 响应代码片段辅助说明
每类状态码配一段简短、可复制的控制器返回示例，突出状态码设置方式和响应结构一致性。
- 返回 404：
return response(['code' => 2001, 'msg' => '文章未找到'], 404); - 返回 422（验证失败）：
return response(['code' => 422, 'msg' => '验证失败', 'errors' => $validator->errors()], 422); - 返回 201（资源创建）：
return response(['code' => 0, 'msg' => '创建成功', 'data' => $post], 201)->header('Location', route('posts.show', $post));
补充非标准但高频的实用状态码说明
除 RFC 标准外，实际项目中有些状态码虽不强制，但已成为事实约定，值得在文档中标注使用场景和注意事项。
- 202 Accepted：适用于异步任务（如导出、批量处理），响应体应含 task_id 或轮询地址
- 429 Too Many Requests：配合 Laravel 的速率限制中间件，需在文档中说明触发阈值和重试建议（如 Retry-After 头）
- 412 Precondition Failed：用于乐观锁场景（如带 If-Match ETag 的更新），提示客户端先获取最新版本
