后台管理系统

基于dcat-admin、与laravel-wechat的后台管理系统，可以快速开发搭建小程序及其后管平台。

环境与包

• php7.4
• mysql5.7
• laravel: 8.7.5
• dcat-admin: ^2.0
• laravel-wechat: ^6.0
• jwt-auth: ^1.0
• telescope: ^4.0

框架部署

进入框架根目录执行：

# 创建和修改配置文件
cp .env.example .env

# 安装依赖 
composer install

# 执行数据库迁移
php artisan migrate

# 安装与发布admin
php artisan admin:install
php artisan admin:publish

# 发布telescope
php artisan telescope:publish

# 生成APP_KEY
php artisan key:generate
# 生成jwt密钥
php artisan jwt:secret

# storage目录分配权限
chmod -R 777 storage

主要集成项及能力

dcat-admin

dcat-admin是一个只需很少的代码即可快速构建出一个功能完善的高颜值后台系统。
其内置了代码生成器，配合laravel自带的migrate可以快速生成表以及其相关的各类文件（模型、控制器、数据仓库等）。
生成的migration文件，编辑后执行迁移：

php artisan make:migration create-table-users
php artisan migrate

然后使用代码生成器：
增加路由并前往后台增加菜单后可以访问整个模型的管理界面。

$router->resource('users', 'UserController');

更多信息可以参考dcat-admin中文文档。

laravel-wechat

laravel-wechat是基于EasyWeChat的laravel框架SDK。
该SDK封装了各类微信生态开放API，极大程度上简化了微信相关业务的开发工作。
在配置文件config/wechat.php中增加相关配置：

'mini_program' => [
    'default' => [
        'app_id'  => env('WECHAT_MINI_PROGRAM_APPID', ''),
        'secret'  => env('WECHAT_MINI_PROGRAM_SECRET', ''),
        'token'   => env('WECHAT_MINI_PROGRAM_TOKEN', ''),
        'aes_key' => env('WECHAT_MINI_PROGRAM_AES_KEY', ''),
    ],
],

即可通过门面使用小程序相关能力：

use Overtrue\LaravelWeChat\Facade;

// 回调事件
Facade::miniProgram()->server->push(function($message){
    return "欢迎关注 overtrue！";
});

// 发送模板消息
Facade::miniProgram()->template_message->send($params);
// 新增或修改二维码
Facade::miniProgram()->qr_code->set($params);
// 素材上传
Facade::miniProgram()->media->upload($type, $path);
...

其他能力(需在配置文件中增加对应的配置)：

Facade::officialAccount();  // 公众号
Facade::openPlatform();     // 开放平台
Facade::payment();          // 支付
Facade::work();             // 企业微信

Facade::officialAccount('foo'); // `foo` 为配置文件中的名称，默认为 `default`

更新信息和能力参考laravel-wechat。

jwt

集成jwt-auth实现了api的权限校验。可以直接使用中间件auth或者auth:api对api进行鉴权。

Route::middleware('auth:api')->get('/user', function (Request $request) {
    return $request->user();
});

目前已经在api增加了默认启用jwt鉴权的组，可以将需要鉴权的router放入组内：

Route::group([
    'namespace' => '\App\Api',
    'middleware' => 'auth:api'
], function(Router $router) {

    $router->any('test', function() {
        return 'test';
    });
});

也实现了基本的登录、刷新token、登出api：

// 登录
$router->post('/auth/login', [AuthController::class, 'login']);

$router->group([
    'prefix' => 'auth'
], function (Router $router) {
    // 刷新token
    $router->post('refresh', [AuthController::class, 'refresh'])->name('refresh');
    // 登出
    $router->post('logout', [AuthController::class, 'logout'])->name('logout');
});

telescope调试工具

Laravel Telescope 是 Laravel 本地开发环境的绝佳伴侣。Telescope 可以方便查看应用程序的请求、异常、日志条目、数据库查询、排队的作业、邮件、消息通知、缓存操作、定时计划任务、变量打印等。
目前已集成在dcat-admin中，在管理后台顶部可以找到入口。

生产环境可以考虑隐藏或者不安装。

Api标准化输出

增加了针对Api接口的标准化输出，默认对整个api启用。将所有的可json序列化的数据统一转化为标准化输出。
编写api代码时无需关注返回结构，只需要返回对应的数据（即data节点）即可。

$router->any('test', function() {
    return 'test api';      // 字符串
    return 11111;           // 数组
    return ['a' => 1];      // 数组
    return User::find(1);   // 对象
    return User::all();     // 集合
});

将标准化输出：

{
    "code": 0,
    "message": "",
    "data": "test api"
    // "data": 11111
    // "data": {
    //     "a" : 1
    // }
    // "data": {
    //     "id" : 1,
    //     "name": "test",
    //     "mobile": "18888888888",
    //     ...
    // }
    // "data": [
    //     {
    //         "id": 1,
    //         ...
    //     },
    //     ...
    // ]
}

异常处理

对整个api的异常在app\Exceptions\Handler.php统一捕获转换为标准化输出，例如未授权访问的异常会输出：

{
    "code": 401,
    "message": "未授权的访问",
    "data": null
}

系统异常类的错误码主要使用HTTP code，未捕获的则统一使用code: 500。

public function register()
{
    $this->renderable(function(Throwable $e, Request $request) {
        if (strstr($request->getRequestUri(), '/api') || $request->expectsJson()) {
            if ($e instanceof QueryException) {
                return ApiResponse::error(Response::HTTP_INTERNAL_SERVER_ERROR, '数据错误');
            } else {
                return ApiResponse::error(500, '系统繁忙');
            }
            ...
        }
    });
    ...
}

业务异常则创建了app\Exceptions\BizException.php进行管理，不同场景的异常推荐在app\Exceptions目录中按照业务创建文件夹进行归类管理。 业务异常继承BizException，需要覆写异常返回的code和message属性，比如归类到Auth的用户名或密码错误异常AccountOrPassWordInvalidException

<?php

namespace App\Exceptions\Auth;

use App\Exceptions\BizException;

class AccountOrPassWordInvalidException extends BizException
{

    protected $code = 2001;

    protected $message = '用户名或密码错误';

}

抛出异常后将输出：

{
    "code": 2001,
    "message": "用户名或密码错误",
    "data": null
}

业务异常可以自定义输出内容，需要重写BizExcetion中的render()

public function render(Request $request)
{
    return ApiResponse::error($this->getCode(), $this->getMessage(), [
        //some things about exception
    ]);
}

业务异常默认不上报，但可以按需自定义上报内容（如日志上报或告警），需要重写BizExcetion中的report()

public function report()
{
    Log::error('出错了', request()->only('phone', 'password'));
    // other report
}