---
url: /docs/3.0/server/tips.md
---
# CatchAdmin 开发小技巧

> 实用的开发技巧和经验分享

这里收集了 CatchAdmin 后台管理系统和 Laravel 框架的实用开发技巧，帮助开发者更好地适应框架开发。这些技巧来源于实际项目经验，能够有效提升开发效率。也 👏 欢迎开发者补充更多实用技巧

## 取消路由中间件

CatchAdmin 后台路由默认注册了四个核心中间件：

```php
Catch\Middleware\AuthMiddleware                  // 用户认证中间件
Catch\Middleware\JsonResponseMiddleware          // JSON 响应中间件
Modules\User\Middlewares\OperatingMiddleware     // 操作日志记录中间件
Modules\Permissions\Middlewares\PermissionGate  // 权限验证中间件
```

模块中的路由通常会**全局**应用这些中间件，但某些场景下（如微信公众号验证、第三方回调接口等）并不需要这些中间件。可以使用以下技巧进行灵活控制：

### 取消后台所有公共的中间件

使用 `withoutMiddleware(config('catch.route.middlewares'))` 可以取消所有默认中间件：

```php
Route::withoutMiddleware(config('catch.route.middlewares'))
    ->prefix('wechat')
    ->group(function(){
    Route::prefix('official')->group(function (){
       Route::get('sign', [OfficialAccountController::class, 'sign']);
    });
    //next
});
```

### 取消某个中间件

如果只需要取消特定中间件（如权限验证），可以这样操作：

```php
Route::withoutMiddleware(\Modules\Permissions\Middlewares\PermissionGate::class)
    ->prefix('wechat')
    ->group(function(){
    Route::prefix('official')->group(function (){
       Route::get('sign', [OfficialAccountController::class, 'sign']);
    });
    //next
});
```

## 响应自定义

CatchAdmin 默认使用统一的响应结构，格式如下：

```php
return [
    'message' => '',
    'data' => '',
    'code' => ''
]
```

某些场景下需要自定义响应结构（如第三方 API 对接），可以使用 `ResponseBuilder` 实现灵活的响应格式：

```php
    return ResponseBuilder::code(10000)
                ->with('hello', 'world')
                ->with('hi', 'world')
                ->data($data)
                ->message('Hello world');
```

## 验证属性遇到第一个错误直接返回

Laravel 默认会验证所有规则后再返回错误，这在包含数据库查询的验证规则时会造成性能浪费。例如即使基础验证失败，仍会执行数据库验证：

```php
$request->validate([
            'code' => [
                'required',
                'size:6',
                function (string $attribute, mixed $value, \Closure $fail) use ($request) {
                   // 这里是数据验证 code 码，例如手机验证码
            }]
        ]);
```

为了提升性能，可以使用 `bail` 规则让验证遇到第一个错误就停止：

```php
$request->validate([
            'code' => [
                'bail', // 添加这个属性即可
                'required',
                'size:6',
                function (string $attribute, mixed $value, \Closure $fail) use ($request) {
                   // 这里是数据验证 code 码，例如手机验证码
            }]
        ]);
```

如果使用 `FormRequest` 进行验证，可以通过设置 `stopOnFirstFailure` 属性实现全局的"遇错即停"：

```php
protected $stopOnFirstFailure = true;
```

:::info
通过将 stopOnFirstFailure 属性添加到请求类，一旦发生单个验证失败，它应该停止验证所有属性
:::

## 如何单独显示菜单 不用菜单下拉

:::info
如果是二级菜单，并且只有`一个`二级菜单的情况下，那么只会显示二级菜单。
:::

找到前端项目的文件 `src/layout/components/Menu/index.vue`，找到 `filterMenus` 方法，找到下面的代码

```js
menus?.forEach((m) => {
  if (m.meta?.hidden) {
    return false
  }

  newMenus.push(m)
  /**
    if (isHasOnlyChild(m) && m.children?.length) {
      newMenus.push(
        Object.assign({
          path: m.children[0].path,
          meta: m.children[0].meta,
          name: m.name
        })
      )
    } else {
      newMenus.push(m)
    }*/
})

return newMenus
```

打开注释即可

## 前端支持 Keepalive

`KeepAlive` 功能可以保持标签页面状态，切换时不重新加载，提升用户体验：
![使用菜单配置页面是否生效](https://image.catchadmin.com/202509130914783.png)
:::info
配置完之后记得刷新后台才能生效
:::