基于Laravel自定义trait实现统一API接口返回规范

作者: liurongming | 来源:发表于2024-01-10 18:00 被阅读0次

SRM移动开发接口规范
（jwt+dingo）和（passport+dingo）使用
API数据字典2018-08-16
Laravel Passport 401 Unauthentic
SpringMvc自定义ApiVersion前缀注解
RestFul 通用接口设计
laravel JWTAuth实现api接口鉴权(基础篇)
7.9 Trait
OpenAPI介绍-初步认识
Libra JSON-RPC接口

一、效果展示

最终实现效果如下图所示：
支持i18n国际化数据返回，修改不同'locale' => 'zh_CN',返回中文
'locale' => 'en',返回英文。
当前使用版本：PHP Version 8.2.9 、Laravel10x。

image.png

有数据返回：

 public function token(Request $request)
   {
        $request->validate([
            'name' => 'required',
            'password' => 'required',
            'device_name' => 'required',
        ]);

        $user = User::where('name', $request->name)->first();

        if (!$user || !Hash::check($request->password, $user->password)) {
            throw ValidationException::withMessages([
                'email' => ['用户名或密码不正确！'],
            ]);
        }

        return $this->success(["token" => $user->createToken($request->device_name)->plainTextToken]);
}

{
    "code": 200,
    "message": "请求成功",
    "data": {
        "token": "49|SpUVNfkiPQhd8aY2BffAGNmN8e8ywMtHw9L0k2I97c7bf39a"
    }
}

 public function show(Request $request)
 {
        return $this->success(['user' => User::all()]);
 }

{
    "code": 200,
    "message": "请求成功",
    "data": {
        "user": [
            {
                "id": 1,
                "name": "admin",
                "email": "admin@qq.com",
                "email_verified_at": null,
                "created_at": null,
                "updated_at": null
            }
        ]
    }
}

无需数据返回

  public function index()
  {
        return $this->ok();
  }

{
    "code": 200,
    "message": "请求成功"
}

二、实现参考

在app目录下，新建\Helpers\Api子目录

image.png

代码实现如下，

<?php

namespace App\Helpers\Api;

use Illuminate\Http\Response as FoundationResponse;

trait ApiResponse
{
    protected $statusCode = FoundationResponse::HTTP_OK;

    /**
     * @return mixed
     */
    public function getStatusCode()
    {
        return $this->statusCode;
    }

    /**
     * @param $statusCode
     * @return $this
     */
    public function setStatusCode($statusCode)
    {
        $this->statusCode = $statusCode;
        return $this;
    }

    /**
     * 自定义发送数据
     * @param $data
     * @param array $header
     * @return mixed
     */
    public function respond($data, $header = [])
    {
        return Response()->json($data, $this->getStatusCode(), $header);
    }

    /**
     * 生成发送数据
     * @param string $message
     * @param array $data
     * @param $code
     * @return mixed
     */
    private function makeDataAndRespond(array $data, string $message, $code = 200)
    {
        $this->setStatusCode($code ?? 200);

        $arrData = [
            'code' => $this->statusCode,
            'message' => $message
        ];
        $ret = array_merge($arrData, ["data" => $data]);
        return $this->respond($ret);
    }

    /**
     * 仅发送消息
     * @param string $message
     * @param $code
     * @return mixed
     */
    public function message(string $message, $code = 200)
    {
        $this->setStatusCode($code ?? 200);

        $arrData = [
            'code' => $this->statusCode,
            'message' => $message
        ];
        return $this->respond($arrData);
    }

    /**
     * 返回成功
     * http_status始终为200
     * code可以修改
     * 不带data参数
     * @param string|NULL $message
     * @param $code
     * @return mixed
     */
    public function ok(string $message = NULL, $code = 200)
    {
        $this->setStatusCode(200);

        $arrData = [
            'code' => $code ?? 200,
            'message' => $message ?? __("http-statuses.200")
        ];
        return $this->respond($arrData);
    }

    /**
     * 发送数据
     * @param array $data
     * @param string|NULL $message
     * @return mixed
     */
    public function success(array $data, string $message = NULL)
    {
        $code = FoundationResponse::HTTP_OK;
        return $this->makeDataAndRespond($data, $message ?? __("http-statuses." . $code));
    }


    /**
     * 发送失败消息
     * @param $message
     * @param $code
     * @return mixed
     */
    public function failed(string $message = NULL, $code = FoundationResponse::HTTP_BAD_REQUEST)
    {
        return $this->message($message ?? __("http-statuses." . $code), $code);
    }

    /**
     * 已创建
     * @param string|NULL $message
     * @return mixed
     */
    public function created(string $message = NULL)
    {
        return $this->failed($message, FoundationResponse::HTTP_CREATED);
    }

    public function locked(string $message = NULL)
    {
        return $this->failed($message, FoundationResponse::HTTP_LOCKED);
    }

    /**
     * 内部错误
     * @param string|NULL $message
     * @return mixed
     */
    public function internalError(string $message = NULL)
    {
        return $this->failed($message, FoundationResponse::HTTP_INTERNAL_SERVER_ERROR);
    }

    /**
     * 未找到
     * @param string|null $message
     * @return mixed
     */
    public function notFound(string $message = null)
    {
        return $this->failed($message, Foundationresponse::HTTP_NOT_FOUND);
    }

    /**
     * 禁止访问
     * @param string|NULL $message
     * @return mixed
     */
    public function forbidden(string $message = NULL)
    {
        return $this->failed($message, Foundationresponse::HTTP_FORBIDDEN);
    }

    /**
     * 无内容
     * @param string|NULL $message
     * @return mixed
     */
    public function noContent(string $message = NULL)
    {
        return $this->failed($message, Foundationresponse::HTTP_NO_CONTENT);
    }

    /**
     * 未认证
     * @param string|NULL $message
     * @return mixed
     */
    public function unauthorized(string $message = NULL)
    {
        return $this->failed($message, Foundationresponse::HTTP_UNAUTHORIZED);
    }

    /**
     * 网关错误
     * @param string|NULL $message
     * @return mixed
     */
    public function badGateway(string $message = NULL)
    {
        return $this->failed($message, Foundationresponse::HTTP_BAD_GATEWAY);
    }

    /**
     * 未知错误
     * @param string|NULL $message
     * @return mixed
     */
    public function unknownError(string $message = NULL)
    {
        return $this->failed($message, 520);
    }

    /**
     * 版本不支持
     * @param string|NULL $message
     * @return mixed
     */
    public function versionNotSupported(string $message = NULL)
    {
        return $this->failed($message, Foundationresponse::HTTP_VERSION_NOT_SUPPORTED);
    }

    /**
     * 连接超时
     * @param string|NULL $message
     * @return mixed
     */
    public function connectionTimedOut(string $message = NULL)
    {
        return $this->failed($message, 522);
    }

    /**
     * 已存在
     * @param string|NULL $message
     * @return mixed
     */
    public function found(string $message = NULL)
    {
        return $this->failed($message, Foundationresponse::HTTP_FOUND);
    }

    /**
     * 已冲突
     * @param string|NULL $message
     * @return mixed
     */
    public function conflict(string $message = NULL)
    {
        return $this->failed($message, Foundationresponse::HTTP_CONFLICT);
    }

    /**
     * 已不可用
     * @param string|NULL $message
     * @return mixed
     */
    public function gone(string $message = NULL)
    {
        return $this->failed($message, Foundationresponse::HTTP_GONE);
    }

    /**
     * 已接受
     * @param string|NULL $message
     * @return mixed
     */
    public function accepted(string $message = NULL)
    {
        return $this->failed($message, Foundationresponse::HTTP_ACCEPTED);
    }
}

三、使用

在控制器类中，使用use ApiResponse;即可。

image.png
【需要安装laravel-lang】国际化支持。

image.png

<?php

namespace App\Http\Controllers;

use App\Helpers\Api\ApiResponse;
use App\Models\User;
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Hash;
use Illuminate\Validation\ValidationException;

class UserController extends Controller
{
    use ApiResponse;

    public function index()
    {
        return $this->ok();
    }

    public function show(Request $request)
    {
        return $this->success(['user' => User::all()]);
    }

    public function token(Request $request)
    {
        $request->validate([
            'name' => 'required',
            'password' => 'required',
            'device_name' => 'required',
        ]);

        $user = User::where('name', $request->name)->first();

        if (!$user || !Hash::check($request->password, $user->password)) {
            throw ValidationException::withMessages([
                'email' => ['用户名或密码不正确！'],
            ]);
        }

        return $this->success(["token" => $user->createToken($request->device_name)->plainTextToken]);
    }
}

备注：Postman接口设置X-Requested-With=XMLHttpRequest有利于调试，并且有异常都通过接口统一返回。Laravel整体使用非常Nice。

image.png

SRM移动开发接口规范
简介由于目前SRM移动应用API接口返回的的格式比较混乱，为了能够是确保API接口统一规范，定义以下规范，编写是...
（jwt+dingo）和（passport+dingo）使用
Laravel实现dingo+JWT api接口之配置篇Laravel实现dingo+JWT api接口之实战篇 ...
API数据字典2018-08-16
接口异常的处理规范一. 统一的API接口返回(错误信息字典) class Err_Map{const ERRMAP...
Laravel Passport 401 Unauthentic
在做SPA 应用时，如果请求API接口返回401，按照 https://laravel.com/docs/5.5/...
SpringMvc自定义ApiVersion前缀注解
背景由于项目的规范需要，需要统一的api接口形式，由于接口可能存在不同的api版本，所以一般是在api接口url...
RestFul 通用接口设计
一、API接口统一返回类定义接口通用的结果返回类JsonResult，其中包括请求状态码(code)、请求信息(...
laravel JWTAuth实现api接口鉴权(基础篇)
laravel JWTAuth实现api接口鉴权(基础篇)[https://www.cnblogs.com/mg0...
7.9 Trait
trait 是PHP为类只能单继承而实现的代码复用机制。 trait 不能继承，也不能实现接口。 trait 不能...
OpenAPI介绍-初步认识
介绍: OAS就是定义基于http的远程api的文档的一种规范什么是API? API就是应用程序接口接口，比如说...
Libra JSON-RPC接口
JSON-RPC接口规范 1. 概述 Libra客户端API基于JSON-RPC协议。该规范定义了客户端API端点...