Laravel 提供了快速开发 API 的完整组件，但规范仍需要团队主动建立。控制器负责 HTTP 协议，Form Request 负责输入校验，策略负责授权，服务层处理业务事务，Resource 负责稳定输出。

核心原则

  • 按 API 版本和资源组织路由，使用 apiResource 保持 REST 方法一致。
  • 把校验规则放进 Form Request，并为业务冲突返回可识别错误码。
  • 用 Policy 或 Gate 处理资源级授权，不在控制器中散落角色判断。
  • 通过 API Resource 明确公开字段、关联和分页结构。
  • 对创建、更新等多步操作使用事务，并为幂等场景设计唯一键。

推荐的实践步骤

控制器接收已经校验的请求数据，调用服务完成写入，然后返回 Resource 和明确状态码。列表接口限制每页大小并按需加载关联，避免 N+1 查询。Feature Test 覆盖身份认证、权限、校验失败、成功响应和数据库状态，确保接口契约在重构后保持稳定。

public function store(StoreUserRequest $request): JsonResponse
{
    $user = $this->service->create(
        $request->validated()
    );

    return (new UserResource($user))
        ->response()
        ->setStatusCode(201);
}

示例用于说明实现思路，实际项目还应结合所使用的框架版本、部署环境和业务约束进行调整。重要配置要进入版本管理，并在测试环境验证后再发布。

常见误区

  • 控制器同时承担校验、授权、事务和模型更新，会快速变得难以测试。
  • 列表接口直接返回全部记录，容易造成慢查询和超大响应。
  • Resource 中访问未预加载的关联，会在序列化阶段触发 N+1 查询。

上线前检查清单

  • 确认“按 API 版本和资源组织路由，使用 apiResource 保持 REST 方法一致”已经通过代码审查或运行验证。
  • 确认“把校验规则放进 Form Request，并为业务冲突返回可识别错误码”已经通过代码审查或运行验证。
  • 确认“用 Policy 或 Gate 处理资源级授权，不在控制器中散落角色判断”已经通过代码审查或运行验证。
  • 确认“通过 API Resource 明确公开字段、关联和分页结构”已经通过代码审查或运行验证。
  • 为失败路径、边界条件和回滚方案准备测试或演练记录。
  • 上线后观察错误率、延迟和资源消耗，确认变化符合预期。

总结

使用 Laravel 构建规范的 REST API的关键在于把隐含假设变成可执行的约束，并通过测试、监控和复盘持续验证。先从影响最大的真实场景开始，小步调整并保留回滚能力，通常比一次性大范围改造更安全，也更容易积累可复用的工程经验。