Laravel 开发Api规范

一，修改时区

配置 config/app.php 文件

// 时区修改，感觉两者皆可，自己根据实际情况定义
'timezone' => 'PRC', // 大陆时间

二，设置 Accept 头中间件

accept头即为客户端请求头，做成中间件来使用。Accept 决定了响应返回的格式，设置为 application/json, 遇到的所有报错 Laravel 会默认处理为 JSON 格式。

生成中间件

php artisan make:middleware AcceptHeader

<?php
namespace App\Http\Middleware;
use Closure;
class AcceptHeader
{public function handle($request, Closure $next){$request->headers->set('Accept', 'application/json');return $next($request);}
}

添加到全局中间件
修改文件 app/http/Kernel.php

protected $middlewareGroups = ['web' => [...],'api' => [\App\Http\Middleware\AcceptHeader::class,...],
];

二，统一封装响应码

Enum 枚举，新建app/Enums/ResponseEnum.php

<?phpnamespace App\Enums;class ResponseEnum
{// sevming/laravel-response 默认以 '|' 作为分割错误码与错误信息的字符串public const INVALID_REQUEST = '无效请求|21001';// 001 ~ 099 表示系统状态；100 ~ 199 表示授权业务；200 ~ 299 表示用户业务/*-------------------------------------------------------------------------------------------*/// 100开头的表示 信息提示，这类状态表示临时的响应// 100 - 继续// 101 - 切换协议/*-------------------------------------------------------------------------------------------*/// 200表示服务器成功地接受了客户端请求const HTTP_OK = [200001, '操作成功'];const HTTP_ERROR = [200002, '操作失败'];const HTTP_ACTION_COUNT_ERROR = [200302, '操作频繁'];const USER_SERVICE_LOGIN_SUCCESS = [200200, '登录成功'];const USER_SERVICE_LOGIN_ERROR = [200201, '登录失败'];const USER_SERVICE_LOGOUT_SUCCESS = [200202, '退出登录成功'];const USER_SERVICE_LOGOUT_ERROR = [200203, '退出登录失败'];const USER_SERVICE_REGISTER_SUCCESS = [200104, '注册成功'];const USER_SERVICE_REGISTER_ERROR = [200105, '注册失败'];const USER_ACCOUNT_REGISTERED = [23001, '账号已注册'];/*-------------------------------------------------------------------------------------------*/// 300开头的表示服务器重定向,指向的别的地方，客户端浏览器必须采取更多操作来实现请求// 302 - 对象已移动。// 304 - 未修改。// 307 - 临时重定向。/*-------------------------------------------------------------------------------------------*/// 400开头的表示客户端错误请求错误，请求不到数据，或者找不到等等// 400 - 错误的请求const CLIENT_NOT_FOUND_HTTP_ERROR = [400001, '请求失败'];const CLIENT_PARAMETER_ERROR = [400200, '参数错误'];const CLIENT_CREATED_ERROR = [400201, '数据已存在'];const CLIENT_DELETED_ERROR = [400202, '数据不存在'];// 401 - 访问被拒绝const CLIENT_HTTP_UNAUTHORIZED = [401001, '授权失败，请先登录'];const CLIENT_HTTP_UNAUTHORIZED_EXPIRED = [401200, '账号信息已过期，请重新登录'];const CLIENT_HTTP_UNAUTHORIZED_BLACKLISTED = [401201, '账号在其他设备登录，请重新登录'];// 403 - 禁止访问// 404 - 没有找到文件或目录const CLIENT_NOT_FOUND_ERROR = [404001, '没有找到该页面'];// 405 - 用来访问本页面的 HTTP 谓词不被允许（方法不被允许）const CLIENT_METHOD_HTTP_TYPE_ERROR = [405001, 'HTTP请求类型错误'];// 406 - 客户端浏览器不接受所请求页面的 MIME 类型// 407 - 要求进行代理身份验证// 412 - 前提条件失败// 413 – 请求实体太大// 414 - 请求 URI 太长// 415 – 不支持的媒体类型// 416 – 所请求的范围无法满足// 417 – 执行失败// 423 – 锁定的错误/*-------------------------------------------------------------------------------------------*/// 500开头的表示服务器错误，服务器因为代码，或者什么原因终止运行// 服务端操作错误码：500 ~ 599 开头，后拼接 3 位// 500 - 内部服务器错误const SYSTEM_ERROR = [500001, '服务器错误'];const SYSTEM_UNAVAILABLE = [500002, '服务器正在维护，暂不可用'];const SYSTEM_CACHE_CONFIG_ERROR = [500003, '缓存配置错误'];const SYSTEM_CACHE_MISSED_ERROR = [500004, '缓存未命中'];const SYSTEM_CONFIG_ERROR = [500005, '系统配置错误'];// 业务操作错误码（外部服务或内部服务调用）const SERVICE_REGISTER_ERROR = [500101, '注册失败'];const SERVICE_LOGIN_ERROR = [500102, '登录失败'];const SERVICE_LOGIN_ACCOUNT_ERROR = [500103, '账号或密码错误'];const SERVICE_USER_INTEGRAL_ERROR = [500200, '积分不足'];//501 - 页眉值指定了未实现的配置//502 - Web 服务器用作网关或代理服务器时收到了无效响应//503 - 服务不可用。这个错误代码为 IIS 6.0 所专用//504 - 网关超时//505 - HTTP 版本不受支持/*-------------------------------------------------------------------------------------------*/
}

三，封装 API 返回的统一消息（ApiResponse）

在 app/Helpers 目录下创建 ApiResponse.php 文件

<?phpnamespace App\Helpers;use App\Enum\ResponseEnum;
use App\Exceptions\BaseException;
use Illuminate\Http\JsonResponse;
use Illuminate\Pagination\LengthAwarePaginator;
use Illuminate\Support\Collection;trait ApiResponse
{/*** 成功* @param null $data* @param array $codeResponse* @return JsonResponse*/public function success($data = null, $codeResponse = ResponseEnum::HTTP_OK): JsonResponse{return $this->jsonResponse('success', $codeResponse, $data);}/*** 失败* @param array $codeResponse* @param null $data* @param null $error* @return JsonResponse*/public function fail($codeResponse = ResponseEnum::HTTP_ERROR, $data = null): JsonResponse{return $this->jsonResponse('fail', $codeResponse, $data);}/*** json响应* @param $status* @param $codeResponse* @param $data* @param $error* @return JsonResponse*/private function jsonResponse($status, $codeResponse, $data): JsonResponse{list($code, $message) = $codeResponse;return response()->json(['status' => $status,'code' => $code,'message' => $message,'data' => $data ?? null,]);}/*** 成功分页返回* @param $page* @return JsonResponse*/protected function successPaginate($page): JsonResponse{return $this->success($this->paginate($page));}private function paginate($page){if ($page instanceof LengthAwarePaginator) {return ['total' => $page->total(),'page' => $page->currentPage(),'limit' => $page->perPage(),'pages' => $page->lastPage(),'list' => $page->items()];}if ($page instanceof Collection) {$page = $page->toArray();}if (!is_array($page)) {return $page;}$total = count($page);return ['total' => $total, //数据总数'page' => 1, // 当前页码'limit' => $total, // 每页的数据条数'pages' => 1, // 最后一页的页码'list' => $page // 数据];}/*** 业务异常返回* @param array $codeResponse* @param string $info* @throws BaseException*/public function throwBaseException(array $codeResponse = ResponseEnum::HTTP_ERROR, string $info = ''){throw new BaseException($codeResponse, $info);}
}

四，创建项目异常捕获 Exception 文件

异常分为两种，一种是要给前端返回展示的，比如表单验证，一种是不需要给前端展示的，比如服务器内部错误。

在 app/Exceptions 目录下创建 BaseException.php 文件用于服务器内部异常的抛出

<?phpnamespace App\Exceptions;use Exception;
class BaseException extends Exception
{/*** 基础异常构造函数* @param array $codeResponse 状态码* @param string $info 自定义返回信息，不为空时会替换掉codeResponse 里面的message文字信息*/public function __construct(array $codeResponse, $info = ''){[$code, $message] = $codeResponse;parent::__construct($info ?: $message, $code);}
}

自定义返回异常
修改 app/Exceptions 目录下的 Handler.php 文件

<?phpnamespace App\Exceptions;use App\Enum\ResponseEnum;
use Illuminate\Foundation\Exceptions\Handler as ExceptionHandler;
use Illuminate\Validation\ValidationException;
use Throwable;
use App\Helpers\ApiResponse;
use Symfony\Component\HttpKernel\Exception\MethodNotAllowedHttpException;
use Symfony\Component\HttpKernel\Exception\NotFoundHttpException;class Handler extends ExceptionHandler
{use ApiResponse;/*** A list of exception types with their corresponding custom log levels.** @var array<class-string<\Throwable>, \Psr\Log\LogLevel::*>*/protected $levels = [//];/*** 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 to the session on 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) {//});}public function render($request, Throwable $exception){   //判断只接管api部分的异常if ($request->is('api/*')) {// 请求类型错误异常抛出if ($exception instanceof MethodNotAllowedHttpException) {$this->throwBaseException(ResponseEnum::CLIENT_METHOD_HTTP_TYPE_ERROR);} // 参数校验错误异常抛出elseif ($exception instanceof ValidationException) {$this->throwBaseException(ResponseEnum::CLIENT_PARAMETER_ERROR, $exception->getMessage());} // 路由不存在异常抛出elseif ($exception instanceof NotFoundHttpException) {$this->throwBaseException(ResponseEnum::CLIENT_NOT_FOUND_ERROR);} // 自定义错误异常抛出elseif ($exception instanceof BaseException) {return response()->json(['status' => 'fail','code' => $exception->getCode(),'message' => $exception->getMessage(),'data' => null,]);//系统异常} else {//生产模式if (config('app.debug')) {return response()->json(['status' => 'fail','code' => 500,'message' => "服务器内部错误！",'data' => null,]);} else {return response()->json(['status' => 'fail','code' => 500,'message' => $exception->getMessage(),'data' => null]);}}}return parent::render($request, $exception);}
}

五，使用

路由定义如下

Route::prefix('v1')->name('api.v1.')->group(function() {Route::get('version', function() {return 'this is version v1';})->name('version');//限速，每分钟只能请求10次Route::get('test', [TestController::class,'test'])->middleware(['throttle:10,1']);Route::post('login', [TestController::class,'login']);Route::post('register', [TestController::class,'register']);Route::group(['middleware' => 'auth.jwt'], function () {Route::get('user', [TestController::class,'user']);Route::get('logout', [TestController::class,'logout']);Route::get('refresh', [TestController::class,'refresh']);});
});