如何在VSCode中构建Laravel API统一返回结构 Laravel标准化接口返回格式实现

<?php

namespace App\Traits;

use Illuminate\Http\JsonResponse;
use Symfony\Component\HttpFoundation\Response as HttpResponse;

trait ApiResponse
{
    /**
     * 成功响应
     *
     * @param mixed $data
     * @param string $message
     * @param int $code
     * @return JsonResponse
     */
    protected function success($data = [], string $message = '操作成功', int $code = 200): JsonResponse
    {
        return $this->jsonResponse($data, $message, $code, HttpResponse::HTTP_OK);
    }

    /**
     * 业务逻辑失败响应
     *
     * @param string $message
     * @param int $code
     * @param int $httpStatus
     * @return JsonResponse
     */
    protected function fail(string $message = '操作失败', int $code = 400, int $httpStatus = HttpResponse::HTTP_BAD_REQUEST): JsonResponse
    {
        return $this->jsonResponse(null, $message, $code, $httpStatus);
    }

    /**
     * 统一的JSON响应结构
     *
     * @param mixed $data
     * @param string $message
     * @param int $code
     * @param int $httpStatus
     * @return JsonResponse
     */
    private function jsonResponse($data, string $message, int $code, int $httpStatus): JsonResponse
    {
        return response()->json([
            'code' => $code, // 业务状态码
            'message' => $message,
            'data' => $data,
        ], $httpStatus); // HTTP状态码
    }

    /**
     * 未授权响应
     *
     * @param string $message
     * @return JsonResponse
     */
    protected function unauthorized(string $message = '未授权'): JsonResponse
    {
        return $this->fail($message, 401, HttpResponse::HTTP_UNAUTHORIZED);
    }

    /**
     * 资源未找到响应
     *
     * @param string $message
     * @return JsonResponse
     */
    protected function notFound(string $message = '资源未找到'): JsonResponse
    {
        return $this->fail($message, 404, HttpResponse::HTTP_NOT_FOUND);
    }

    // ... 还可以添加更多如 validationError, forbidden 等方法
}

<?php

namespace App\Http\Controllers\Api;

use App\Http\Controllers\Controller;
use App\Traits\ApiResponse;
use Illuminate\Http\Request;

class UserController extends Controller
{
    use ApiResponse;

    public function show(Request $request, $id)
    {
        // 假设从数据库获取用户
        $user = ['id' => $id, 'name' => '张三', 'email' => 'zhangsan@example.com'];

        if (!$user) {
            return $this->notFound('用户不存在');
        }

        return $this->success($user, '获取用户信息成功');
    }

    public function store(Request $request)
    {
        $validatedData = $request->validate([
            'name' => 'required|string|max:255',
            'email' => 'required|email|unique:users',
        ]);

        // 模拟创建用户
        // User::create($validatedData);

        return $this->success(['id' => 123, 'name' => $validatedData['name']], '用户创建成功', 201);
    }

    // ... 其他方法
}

<?php

namespace App\Exceptions;

use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Throwable;
use Illuminate\Http\JsonResponse;
use Illuminate\Validation\ValidationException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;
use Symfony\Component\HttpFoundation\Response as HttpResponse;

class Handler extends ExceptionHandler
{
    /**
     * A list of the exception types that are not reported.
     *
     * @var array<int, class-string<Throwable>>
     */
    protected $dontReport = [
        //
    ];

    /**
     * A list of the inputs that are never flashed for validation exceptions.
     *
     * @var array<int, string>
     */
    protected $dontFlash = [
        'current_password',
        'password',
        'password_confirmation',
    ];

    /**
     * Register the exception handling callbacks for the application.
     *
     * @return void
     */
    public function register()
    {
        $this->reportable(function (Throwable $e) {
            //
        });
    }

    /**
     * Render an exception into an HTTP response.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Throwable  $exception
     * @return \Symfony\Component\HttpFoundation\Response
     */
    public function render($request, Throwable $exception)
    {
        // 检查请求是否是API请求，例如：
        // 1. 请求头中 Accept 包含 application/json
        // 2. 请求路径以 /api/ 开头
        // 3. 请求是 AJAX 请求
        if ($request->expectsJson() || $request->is('api/*')) {
            // 统一的错误响应结构
            $response = [
                'code' => 500, // 默认业务错误码
                'message' => '服务器内部错误',
                'data' => null,
            ];
            $httpStatus = HttpResponse::HTTP_INTERNAL_SERVER_ERROR; // 默认HTTP状态码

            if ($exception instanceof ValidationException) {
                // 处理验证错误
                $response['code'] = 422;
                $response['message'] = '请求参数校验失败';
                $response['data'] = $exception->errors(); // 包含详细的验证错误信息
                $httpStatus = HttpResponse::HTTP_UNPROCESSABLE_ENTITY;
            } elseif ($exception instanceof NotFoundHttpException) {
                // 处理404错误 (路由或资源未找到)
                $response['code'] = 404;
                $response['message'] = '请求的资源或路由不存在';
                $httpStatus = HttpResponse::HTTP_NOT_FOUND;
            } elseif ($exception instanceof \Illuminate\Auth\AuthenticationException) {
                // 处理认证失败
                $response['code'] = 401;
                $response['message'] = '未授权或认证失败';
                $httpStatus = HttpResponse::HTTP_UNAUTHORIZED;
            } elseif ($exception instanceof \Illuminate\Auth\Access\AuthorizationException) {
                // 处理授权失败 (无权限)
                $response['code'] = 403;
                $response['message'] = '无权限访问此资源';
                $httpStatus = HttpResponse::HTTP_FORBIDDEN;
            }
            // ... 还可以根据需要处理其他特定异常，如 ModelNotFoundException, QueryException 等

            // 对于生产环境，避免暴露详细的错误信息
            if (config('app.env') === 'production' && !($exception instanceof ValidationException)) {
                // 在生产环境，对于非验证错误，只返回通用错误信息
                $response['message'] = '服务器内部错误，请稍后重试。';
            } else {
                // 开发环境下可以暴露更详细的错误信息
                // $response['debug_message'] = $exception->getMessage();
                // $response['trace'] = $exception->getTraceAsString();
            }

            return response()->json($response, $httpStatus);
        }

        // 非API请求，交给父类处理，通常会渲染HTML错误页面
        return parent::render($request, $exception);
    }
}