lumen Restful Api 接口规范输出格式整合

配置统一输出格式

修改 app\Http\Controllers\Controller.php 控制器文件

添加以下内容：

    /**
     * 获取成功输出
     * @param array $data
     * @param string $tip
     * @param int $httpCode
     * @return mixed
     */
    public function success($data=array(),$tip='请求成功',$httpCode=200){
        return response()->json(array(
            'status' => 200,
            'success'=>false,
            'data'=>$data,
            'tip'=>$tip
        ),$httpCode);
    }


    /**
     * 错误提示输出
     * @param $erroeCode
     * @param string $tip
     * @param int $httpCode
     * @return mixed
     */
    public function error($erroeCode,$tip='请求失败',$httpCode=400){
        return response()->json(array(
            'status' => $httpCode,
            'success'=>false,
            'error'=>array(
                'code'=>$erroeCode,
                'message'=>trans("errorCode.{$erroeCode}")
            ),
            'tip'=>$tip
        ),$httpCode);
    }

使用

在控制器内直接调用

//成功
return $this->success();

//错误
return $this->error(40004);

返回格式说明

• 返回错误信息

参数名	类型	说明
status	int	http状态码
success	blood	是否获取成功
error	object	错误信息
-- code	int	错误码
-- message	string	错误信息
tip	string	提示信息

{
    "status": 400,
    "success": false,
    "error": {
        "code": 40004,
        "message": "参数无效"
    },
    "tip": "请求失败"
}

• 返回结果格式

参数名	类型	说明
status	int	http状态码
success	blood	是否获取成功
data	object或array	返回的结果数据
-- xxx	~	~
-- xxx	~	~
-- xxx	~	~
tip	string	提示信息

{
    "status": 200,
    "success": true,
    "data": {
        "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIU...",
        "token_type": "bearer",
        "expires_in": 3600
    },
    "tip": "请求成功"
}

添加状态码配置

• 添加http状态码提示信息文件到目录 resources\lang\zh-CN\httpCode.php

httpCode.php 内容如下:

'客户端应继续其请求',
    101=>'切换协议。服务器根据客户端的请求切换协议。只能切换到更高级的协议，例如，切换到HTTP的新版本协议',

    200=>'请求成功',
    201=>'成功请求并创建了新的资源',
    202=>'已经接受请求，但未处理完成',
    203=>'非授权信息',
    204=>'服务器成功处理，但未返回内容。',
    205=>'服务器处理成功，用户终端（例如：浏览器）应重置文档视图。',
    206=>'服务器成功处理了部分请求',

    300=>'（多种选择） 针对请求，服务器可执行多种操作',
    301=>'（永久移动） 请求的资源已永久移动到新位置',
    302=>'临时移动） 服务器目前从不同位置的资源响应请求，但请求者应继续使用原有位置来进行以后的请求。',
    303=>'（查看其他位置） 请求者应当对不同的位置使用单独的 GET 请求来检索响应时，服务器返回此代码',
    304=>'（未修改） 自从上次请求后，请求的资源未修改过。 服务器返回此响应时，不会返回资源内容。',
    305=>'（使用代理） 请求者只能使用代理访问请求的资源。 如果服务器返回此响应，还表示请求者应使用代理。',
    307=>'（临时重定向） 服务器目前从不同位置的资源响应请求，但请求者应继续使用原有位置来进行以后的请求。',

    400=>'（错误请求） 服务器不理解请求的语法',
    401 =>'（未授权） 请求要求身份验证。 对于需要登录的资源，服务器可能返回此响应。',
    403=>'（禁止） 服务器拒绝请求',
    404=>'（未找到） 服务器找不到请求的资源',
    405=>'（方法禁用） 禁用请求中指定的方法',
    406=>'（不接受） 无法使用请求的内容特性响应请求的资源',
    407=>'（需要代理授权） 此状态代码与 401（未授权）类似，但指定请求者应当授权使用代理',
    408=>'（请求超时） 服务器等候请求时发生超时',
    409=>'（冲突） 服务器在完成请求时发生冲突。 服务器必须在响应中包含有关冲突的信息',
    410=>'（已删除） 如果请求的资源已永久删除，服务器就会返回此响应',
    411=>'（需要有效长度） 服务器不接受不含有效内容长度标头字段的请求',
    412=>'（未满足前提条件） 服务器未满足请求者在请求中设置的其中一个前提条件',
    413=>'（请求实体过大） 服务器无法处理请求，因为请求实体过大，超出服务器的处理能力',
    414=>'（请求的 URI 过长） 请求的 URI（通常为网址）过长，服务器无法处理（请求的 URI 过长） 请求的 URI（通常为网址）过长，服务器无法处理',
    415=>'（不支持的媒体类型） 请求的格式不受请求页面的支持',
    416=>'（请求范围不符合要求） 如果页面无法提供请求的范围，则服务器会返回此状态代码',
    417=>'（未满足期望值） 服务器未满足"期望"请求标头字段的要求',

    500=>'（服务器内部错误） 服务器遇到错误，无法完成请求。',
    501=>'（尚未实施） 服务器不具备完成请求的功能。 例如，服务器无法识别请求方法时可能会返回此代码。',
    502=>'（错误网关） 服务器作为网关或代理，从上游服务器收到无效响应。（错误网关） 服务器作为网关或代理，从上游服务器收到无效响应。',
    503=>'（服务不可用） 服务器目前无法使用（由于超载或停机维护）。 通常，这只是暂时状态。',
    504=>'（网关超时） 服务器作为网关或代理，但是没有及时从上游服务器收到请求。',
    505=>'（HTTP 版本不受支持） 服务器不支持请求中所用的 HTTP 协议版本。',

];

• 添加错误码提示信息文件到目录 resources\lang\zh-CN\errorCode.php

errorCode.php 内容如下:

'未知错误',
    //客户端错误
    40001=>'参数不能为空',
    40002=>'参数不齐全',
    40003=>'参数错误',
    ...
    //服务端错误
    50001=>'服务端错误',
    ...

];

调用方式：trans 函数

//调用
trans("httpCode.404");

trans("errorCode.40001");


//json
return Responder::error(50001,trans('errorCode.50001'))->respond();

输入图片说明

框架报错返回 json 格式配置

修改文件 app\Exceptions\Handler.php

把 function render 修改 如下：

   /**
     * Render an exception into an HTTP response.
     *
     * @param  \Illuminate\Http\Request  $request
     * @param  \Exception  $exception
     * @return \Illuminate\Http\Response|\Illuminate\Http\JsonResponse
     */
    public function render($request, Exception $e)
    {

        //框架自带数据验证错误信息返回处理
        if($e instanceof \Illuminate\Validation\ValidationException){
            $errors = $e->errors();
            return $this->errorEcho($e->status,reset($errors)[0]);
        }

        if(method_exists($e,'getStatusCode')){
            //json返回 http错误提示信息
            $http_code = $e->getStatusCode();
            switch ($http_code){
                case $http_code>=400:
                    return $this->errorEcho($e->getStatusCode(),$e->getMessage());
                    break;
                default:
                    return parent::render($request, $e);
            }
        }

        return parent::render($request, $e);

    }

    
    /**
     * 自定义输出格式
     * @param  $httpCode
     * @param  $msg
     * @return \Illuminate\Http\Response
     */
    private function errorEcho($httpCode,$msg=''){
        if($msg == ''){
            $msg = trans("httpCode.{$httpCode}");
        }
        return response()->json(array(
            'status' => $httpCode,
            'success'=>false,
            'error'=>array(
                'code'=>$httpCode,
                'message'=>$msg
            )
        ),$httpCode);
    }