\App\Http\HelpersApiResponse

统一 API 响应格式

职责：封装全站 JSON 响应的统一结构与语义，以静态工厂方法产出成功、分页、通用失败及 4xx/5xx 错误族的 JsonResponse。

┌────────────────── 分区导航（按此顺序阅读）──────────────────┐ 分区 1 · 成功响应（2xx） success / created / noContent / paginated 分区 2 · 通用失败响应 error 分区 3 · 4xx 客户端错误 badRequest / unauthorized / forbidden / notFound methodNotAllowed / conflict / validationError tooManyRequests 分区 4 · 5xx 服务端错误 serverError └────────────────────────────────────────────────────────────┘

成功响应：{ code: 200, message: "...", data: { ... } } 失败响应：{ code: 4xx/5xx, message: "...", data: null } 分页响应：{ code: 200, message: "...", data: { list: [...], meta: { ... } } }

Summary

Methods

Properties

Constants

success()
created()
noContent()
paginated()
error()
badRequest()
unauthorized()
forbidden()
notFound()
methodNotAllowed()
conflict()
validationError()
tooManyRequests()
serverError()
success()
error()

No public properties found

No constants found

No protected methods found

No protected properties found

N/A

No private methods found

No private properties found

N/A

File: Backend-Admin-PHP/app/Http/Helpers/ApiResponse.php
Package: Application
Class hierarchy: \App\Http\Helpers\ApiResponse
Uses

Methods

success()

success(string  $message = 'ok', mixed  $data = null) : \Illuminate\Http\JsonResponse

成功响应（200 OK）

Parameters

string	$message	提示信息
mixed	$data	业务数据

Returns

\Illuminate\Http\JsonResponse —

Examples

ApiResponse::success('登录成功', ['token' => 'xxx', 'expires_at' => '...'])

created()

created(string  $message = '创建成功', mixed  $data = null) : \Illuminate\Http\JsonResponse

资源创建成功（201 Created）

Parameters

string	$message	提示信息
mixed	$data	新建的资源数据

Returns

\Illuminate\Http\JsonResponse —

Examples

ApiResponse::created('创建成功', $newRecord)

noContent()

noContent() : \Illuminate\Http\JsonResponse

成功但无返回内容（204 No Content）

Returns

\Illuminate\Http\JsonResponse —

Examples

ApiResponse::noContent() → HTTP 204，body 为空

paginated()

paginated(string  $message, \Illuminate\Contracts\Pagination\LengthAwarePaginator  $paginator) : \Illuminate\Http\JsonResponse

分页响应（200 OK，meta 放在 data 内）

Parameters

string	$message	提示信息
\Illuminate\Contracts\Pagination\LengthAwarePaginator	$paginator	分页器实例

Returns

\Illuminate\Http\JsonResponse —

Examples

ApiResponse::paginated('ok', User::paginate())

error()

error(int  $code, string  $message, mixed  $data = null) : \Illuminate\Http\JsonResponse

通用失败响应

Parameters

int	$code	HTTP 状态码（4xx / 5xx）
string	$message	错误信息
mixed	$data	附加数据（如验证错误字段详情）

Returns

\Illuminate\Http\JsonResponse —

Examples

ApiResponse::error(418, '我是一个茶壶')

badRequest()

badRequest(string  $message = '请求参数有误', mixed  $data = null) : \Illuminate\Http\JsonResponse

400 请求参数有误

Parameters

string	$message	错误描述
mixed	$data	附加数据

Returns

\Illuminate\Http\JsonResponse —

unauthorized()

unauthorized(string  $message = '未登录') : \Illuminate\Http\JsonResponse

401 未登录 / token 无效

Parameters

string

$message

错误描述

Returns

\Illuminate\Http\JsonResponse —

forbidden()

forbidden(string  $message = '无权限访问', mixed  $data = null) : \Illuminate\Http\JsonResponse

403 无权限访问

Parameters

string	$message	错误描述
mixed	$data	附加数据（如无权限的权限码）

Returns

\Illuminate\Http\JsonResponse —

notFound()

notFound(string  $message = '资源不存在') : \Illuminate\Http\JsonResponse

404 资源不存在

Parameters

string

$message

错误描述

Returns

\Illuminate\Http\JsonResponse —

methodNotAllowed()

methodNotAllowed(string  $message = '不允许的请求方法') : \Illuminate\Http\JsonResponse

405 不允许的 HTTP 方法

Parameters

string

$message

错误描述

Returns

\Illuminate\Http\JsonResponse —

conflict()

conflict(string  $message = '资源冲突') : \Illuminate\Http\JsonResponse

409 资源冲突（如重复数据、并发编辑冲突）

Parameters

string

$message

错误描述

Returns

\Illuminate\Http\JsonResponse —

validationError()

validationError(string  $message = '参数验证失败', mixed  $data = null) : \Illuminate\Http\JsonResponse

422 参数验证失败

Parameters

string	$message	错误描述
mixed	$data	验证失败的字段详情，通常是 ['field' => ['第一条错误', '第二条错误']]

Returns

\Illuminate\Http\JsonResponse —

tooManyRequests()

tooManyRequests(string  $message = '请求过于频繁，请稍后再试', int  $retryAfter = 60) : \Illuminate\Http\JsonResponse

429 请求过于频繁

Parameters

string	$message	错误描述
int	$retryAfter	多少秒后可以重试（会写入 Retry-After 头）

Returns

\Illuminate\Http\JsonResponse —

serverError()

serverError(string  $message = '服务器内部错误') : \Illuminate\Http\JsonResponse

500 服务器内部错误

Parameters

string

$message

错误描述

Returns

\Illuminate\Http\JsonResponse —

success()

success(string  $message, mixed  $data = null) : \Illuminate\Http\JsonResponse

Parameters

string	$message
mixed	$data = null

Returns

\Illuminate\Http\JsonResponse —

error()

error(int  $code, string  $message, mixed  $data = null) : \Illuminate\Http\JsonResponse

Parameters

int	$code
string	$message
mixed	$data = null

Returns

\Illuminate\Http\JsonResponse —