laravel-response

社区讨论文章

• 是时候使用 Lumen 8 + API Resource 开发项目了！
• 教你更优雅地写 API 之「路由设计」
• 教你更优雅地写 API 之「规范响应数据」
• 教你更优雅地写 API 之「枚举使用」
• 教你更优雅地写 API 之「记录日志」
• 教你更优雅地写 API 之「灵活地任务调度」

介绍

laravel-response 主要用来统一 API 开发过程中「成功」、「失败」以及「异常」情况下的响应数据格式。

实现过程简单，在原有的 response()->json()进行封装，使用时不需要有额外的心理负担。

遵循一定的规范，返回易于理解的 HTTP 状态码，并支持定义 ResponseCodeEnum 来满足不同场景下返回描述性的业务操作码。

概览

• 统一的数据响应格式，固定包含：code、status、data、message、error
• 内置 Http 标准状态码支持，同时支持扩展 ResponseCodeEnum 来根据不同业务模块定义响应码
• 响应码 code 对应描述信息 message 支持本地化，支持配置多语言
• 合理地返回 Http 状态码
• 根据 debug 开关，合理返回异常信息、验证异常信息等
• 支持格式化 Laravel 的 Api Resource、Api Resource Collection、Paginator（简单分页）、LengthAwarePaginator（普通分页）、Eloquent\Model、Eloquent\Collection，以及简单的 array 和 string等格式数据返回
• 分页数据格式化后的结果与使用 league/fractal （DingoApi 使用该扩展进行数据转换）的 transformer 转换后的格式保持一致，也就是说，可以顺滑地从 Laravel Api Resource 切换到 league/fractal

安装

支持 Laravel 8/Lumen 8 以上版本，自定义业务操作码部分依赖于 jiannei/laravel-enum，需要先进行安装。

配置

Laravel

• 发布配置文件

• 格式化异常响应

在 app/Exceptions/Handler.php 中 引入 use LSvKing\Response\Laravel\Support\Traits\ExceptionTrait; 引入以后，对于 ajax 请求产生的异常都会进行格式化数据返回。

Lumen

• 复制配置文件到 vendor/jiannei/laravel-response/config/response.php，到 config/response.php

• 加载配置

• 格式化异常响应

在 app/Exceptions/Handler.php 中 引入 use LSvKing\Response\Laravel\Support\Traits\ExceptionTrait;

在 app/Http/Controllers/Controller.php 中引入 use LSvKing\Response\Laravel\Support\Traits\ExceptionTrait;

• 注册服务容器

使用

扩展包本身提供了丰富的单元测试用例tests ，也可以直接查看测试用例。

或者查看相应的模板项目:

Laravel 版本 Api 开发初始化项目：laravel-api-starter

Lumen 版本 Api 开发初始化项目：lumen-api-starter

成功响应

• 示例代码

• 返回全部数据（支持自定义内层 data 字段名称，比如 rows、list）

• 分页数据（支持自定义内层 data 字段名称，比如 rows、list）

• 返回简单分页数据（支持自定义内层 data 字段名称，比如 rows、list）

• 返回单条数据

其他快捷方法

失败响应

不指定 meesage

• 未配置多语言响应描述，返回数据

• 配置多语言描述后，返回数据

指定 message

返回数据

指定 code

返回数据

其他快捷方法

异常响应

• 表单验证异常

• Controller 以外抛出异常返回

可以直接使用 abort 辅助函数直接抛出 HttpException 异常

• 其他异常

开启 debug

关闭 debug

message 多语言

TODO

自定义操作码

本地化操作码描述

License

MIT