Skip to content

Commit

Permalink
doc: update
Browse files Browse the repository at this point in the history
  • Loading branch information
jiannei committed Mar 13, 2024
1 parent 1df466a commit f713db7
Showing 1 changed file with 54 additions and 54 deletions.
108 changes: 54 additions & 54 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@

实现过程简单,在原有的 `\Illuminate\Http\JsonResponse`进行封装,使用时不需要有额外的心理负担。

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

## 概览

Expand All @@ -38,22 +38,22 @@
- 支持修改 Laravel 特地异常的状态码或提示信息,比如将 `No query results for model` 的异常提示修改成 `数据未找到`
- 支持配置返回字段是否显示,以及为她们设置别名,比如,将 `message` 别名设置为 `msg`,或者 分页数据第二层的 `data` 改成 `list`(res.data.data -> res.data.list)
- 分页数据格式化后的结果与使用 `league/fractal` (DingoApi 使用该扩展进行数据转换)的 transformer 转换后的格式保持一致,也就是说,可以顺滑地从 Laravel Api Resource 切换到 `league/fractal`
- 内置 Http 标准状态码支持,同时支持扩展 ResponseCodeEnum 来根据不同业务模块定义响应码(可选,需要安装 `jiannei/laravel-enum`)
- 内置 Http 标准状态码支持,同时支持扩展 ResponseEnum 来根据不同业务模块定义响应码(可选,需要安装 `jiannei/laravel-enum`)
- 响应码 code 对应描述信息 message 支持本地化,支持配置多语言(可选,需要安装 `jiannei/laravel-enum`)


## 安装

支持 Laravel 5.5.* ~ Laravel 10.* 版本,自定义业务操作码部分依赖于 [jiannei/laravel-enum](https://github.com/Jiannei/laravel-enum),需要先进行安装。
支持 Laravel 5.5.* ~ Laravel 11.* 版本,自定义业务操作码部分依赖于 [jiannei/laravel-enum](https://github.com/Jiannei/laravel-enum),需要先进行安装。

| laravel 版本 | lumen 版本 | response 版本 | enum 版本 |
|------------|------------|-------------| ---- |
| 5.5.* | 5.5.* | ~1.8 | ~1.4 |
| 6.* | 6.* | ^2.0 | ~1.4 |
| 7.* | 7.* | ^3.0 | ^2.0 |
| 8.* | 8.* | ^4.0 | ^3.0 |
| 9.* - 10.* | 9.* - 10.* | ^5.0 | ^3.0 |
| 11.* | 不支持 | ^6.0 | ^3.0 |
| laravel 版本 | lumen 版本 | response 版本 | enum 版本 |
|------------|------------|-------------|---------|
| 5.5.* | 5.5.* | ~1.8 | ~1.4 |
| 6.* | 6.* | ^2.0 | ~1.4 |
| 7.* | 7.* | ^3.0 | ^2.0 |
| 8.* | 8.* | ^4.0 | ^3.0 |
| 9.* - 10.* | 9.* - 10.* | ^5.0 | ^3.0 |
| 11.* | 不支持 | ^6.0 | ^4.0 |


```shell
Expand Down Expand Up @@ -85,7 +85,7 @@ composer require jiannei/laravel-enum "^3.0" -vvv # 可选
# laravel 11.x

composer require jiannei/laravel-response "^6.0" -vvv
composer require jiannei/laravel-enum "^3.0" -vvv # 可选
composer require jiannei/laravel-enum "^4.0" -vvv # 可选
```

## 配置
Expand Down Expand Up @@ -197,7 +197,7 @@ public function array()
return Response::success([
'name' => 'Jiannel',
'email' => '[email protected]'
],'', ResponseCodeEnum::SERVICE_REGISTER_SUCCESS);
],'', ResponseEnum::SERVICE_REGISTER_SUCCESS);
}
```

Expand Down Expand Up @@ -414,7 +414,7 @@ public function fail()
```php
public function fail()
{
return Response::fail('',ResponseCodeEnum::SERVICE_LOGIN_ERROR);
return Response::fail('',ResponseEnum::SERVICE_LOGIN_ERROR);
}
```

Expand Down Expand Up @@ -530,33 +530,33 @@ abort(500102,'登录失败');
<?php
namespace App\Enums;

use Jiannei\Enum\Laravel\Repositories\Enums\HttpStatusCodeEnum;
use Jiannei\Enum\Laravel\Support\Traits\EnumEnhance;

class ResponseCodeEnum extends HttpStatusCodeEnum
enum ResponseEnum: int
{
use EnumEnhance;

// 业务操作正确码:1xx、2xx、3xx 开头,后拼接 3 位
// 200 + 001 => 200001,也就是有 001 ~ 999 个编号可以用来表示业务成功的情况,当然你可以根据实际需求继续增加位数,但必须要求是 200 开头
// 举个栗子:你可以定义 001 ~ 099 表示系统状态;100 ~ 199 表示授权业务;200 ~ 299 表示用户业务..
const SERVICE_REGISTER_SUCCESS = 200101;
const SERVICE_LOGIN_SUCCESS = 200102;
// 举个栗子:你可以定义 001 ~ 099 表示系统状态;100 ~ 199 表示授权业务;200 ~ 299 表示用户业务...
case SERVICE_REGISTER_SUCCESS = 200101;
case SERVICE_LOGIN_SUCCESS = 200102;

// 客户端错误码:400 ~ 499 开头,后拼接 3 位
const CLIENT_PARAMETER_ERROR = 400001;
const CLIENT_CREATED_ERROR = 400002;
const CLIENT_DELETED_ERROR = 400003;
// 业务操作错误码(外部服务或内部服务调用...)
case SERVICE_REGISTER_ERROR = 500101;
case SERVICE_LOGIN_ERROR = 500102;

const CLIENT_VALIDATION_ERROR = 422001; // 表单验证错误
// 客户端错误码:400 ~ 499 开头,后拼接 3 位
case CLIENT_PARAMETER_ERROR = 400001;
case CLIENT_CREATED_ERROR = 400002;
case CLIENT_DELETED_ERROR = 400003;

// 服务端操作错误码:500 ~ 599 开头,后拼接 3 位
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;
case SYSTEM_ERROR = 500001;
case SYSTEM_UNAVAILABLE = 500002;
case SYSTEM_CACHE_CONFIG_ERROR = 500003;
case SYSTEM_CACHE_MISSED_ERROR = 500004;
case SYSTEM_CONFIG_ERROR = 500005;
}
```

Expand All @@ -565,36 +565,36 @@ class ResponseCodeEnum extends HttpStatusCodeEnum
```php
<?php
// lang/zh_CN/enums.php
use App\Repositories\Enums\ResponseCodeEnum;
use App\Repositories\Enums\ResponseEnum;
use Jiannei\Enum\Laravel\Support\Enums\HttpStatusCode;

return [
// 响应状态码
ResponseCodeEnum::class => [
// 成功
ResponseCodeEnum::HTTP_OK => '操作成功', // 自定义 HTTP 状态码返回消息
ResponseCodeEnum::HTTP_INTERNAL_SERVER_ERROR => '操作失败', // 自定义 HTTP 状态码返回消息
ResponseCodeEnum::HTTP_UNAUTHORIZED => '授权失败',
ResponseEnum::class => [
// 标准 HTTP 状态码
HttpStatusCode::HTTP_OK->value => '操作成功',
HttpStatusCode::HTTP_UNAUTHORIZED->value => '授权失败',

// 业务操作成功
ResponseCodeEnum::SERVICE_REGISTER_SUCCESS => '注册成功',
ResponseCodeEnum::SERVICE_LOGIN_SUCCESS => '登录成功',
ResponseEnum::SERVICE_REGISTER_SUCCESS->value => '注册成功',
ResponseEnum::SERVICE_LOGIN_SUCCESS->value => '登录成功',

// 业务操作失败:授权业务
ResponseEnum::SERVICE_REGISTER_ERROR->value => '注册失败',
ResponseEnum::SERVICE_LOGIN_ERROR->value => '登录失败',

// 客户端错误
ResponseCodeEnum::CLIENT_PARAMETER_ERROR => '参数错误',
ResponseCodeEnum::CLIENT_CREATED_ERROR => '数据已存在',
ResponseCodeEnum::CLIENT_DELETED_ERROR => '数据不存在',
ResponseCodeEnum::CLIENT_VALIDATION_ERROR => '表单验证错误',
ResponseEnum::CLIENT_PARAMETER_ERROR->value => '参数错误',
ResponseEnum::CLIENT_CREATED_ERROR->value => '数据已存在',
ResponseEnum::CLIENT_DELETED_ERROR->value => '数据不存在',

// 服务端错误
ResponseCodeEnum::SYSTEM_ERROR => '服务器错误',
ResponseCodeEnum::SYSTEM_UNAVAILABLE => '服务器正在维护,暂不可用',
ResponseCodeEnum::SYSTEM_CACHE_CONFIG_ERROR => '缓存配置错误',
ResponseCodeEnum::SYSTEM_CACHE_MISSED_ERROR => '缓存未命中',
ResponseCodeEnum::SYSTEM_CONFIG_ERROR => '系统配置错误',

// 业务操作失败:授权业务
ResponseCodeEnum::SERVICE_REGISTER_ERROR => '注册失败',
ResponseCodeEnum::SERVICE_LOGIN_ERROR => '登录失败',
ResponseEnum::SYSTEM_ERROR->value => '服务器错误',
ResponseEnum::SYSTEM_UNAVAILABLE->value => '服务器正在维护,暂不可用',
ResponseEnum::SYSTEM_CACHE_CONFIG_ERROR->value => '缓存配置错误',
ResponseEnum::SYSTEM_CACHE_MISSED_ERROR->value => '缓存未命中',
ResponseEnum::SYSTEM_CONFIG_ERROR->value => '系统配置错误',
],
],
];
```
Expand Down

0 comments on commit f713db7

Please sign in to comment.