CatchAdmin 配置详解

系统配置和模块配置的使用指南

CatchAdmin 提供了灵活的配置机制，支持系统级和模块级的配置管理。首先了解系统的核心配置文件：

return [
    /*
    |--------------------------------------------------------------------------
    | catch-admin super admin id
    |--------------------------------------------------------------------------
    |
    | where you can set super admin id
    |
    */
    'super_admin' => 1,

    /*
    |--------------------------------------------------------------------------
    | catch-admin module setting
    |--------------------------------------------------------------------------
    |
    | the root where module generate
    | the namespace is module root namespace
    | the default dirs is module generate default dirs
    */
    'module' => [
        'root' => 'modules',

        'namespace' => 'Modules',

        'default' => ['develop', 'user', 'permission'],

        'default_dirs' => [
            'Http'.DIRECTORY_SEPARATOR,

            'Http'.DIRECTORY_SEPARATOR.'Requests'.DIRECTORY_SEPARATOR,

            'Http'.DIRECTORY_SEPARATOR.'Controllers'.DIRECTORY_SEPARATOR,

            'Models'.DIRECTORY_SEPARATOR,

            'views'.DIRECTORY_SEPARATOR,
        ],

        // storage module information
        // which driver should be used?
        'driver' => [
            // currently, catchadmin support file and database
            // the default is driver
            'default' => 'file',

            // use database driver
            'table_name' => 'admin_modules'
        ],

        /**
         * module routes collection
         *
         */
        'routes' => [],
    ],

    /*
    |--------------------------------------------------------------------------
    | catch-admin response
    |--------------------------------------------------------------------------
    */
    'response' => [
        // it's a controller middleware, it's set in CatchController
        // if you not need json response, don't extend CatchController
        'always_json' => \Catch\Middleware\JsonResponseMiddleware::class,

        // response listener
        // it  listens [RequestHandled] event, if you don't need this
        // you can change this config
        'request_handled_listener' => \Catch\Listeners\RequestHandledListener::class
    ],

    /*
    |--------------------------------------------------------------------------
    | catch-admin auth setting
    |--------------------------------------------------------------------------
    */
    'auth' => [
        'guards' => [
            'admin' => [
                'driver' => 'jwt',
                'provider' => 'admin_users',
            ],
        ],

        'providers' => [
            'admin_users' => [
                'driver' => 'eloquent',
                'model' => \Modules\User\Models\User::class
            ]
        ]
    ],

    /*
   |--------------------------------------------------------------------------
   | database sql log
   |--------------------------------------------------------------------------
   */
    'listen_db_log' => true,

    /*
   |--------------------------------------------------------------------------
   | route config
   |--------------------------------------------------------------------------
   */
    'route' => [
        'prefix' => 'api',

        'middlewares' => [
            \Catch\Middleware\AuthMiddleware::class,
            \Catch\Middleware\JsonResponseMiddleware::class
        ]
    ],
];

配置项详解

超级管理员配置

• super_admin：设置超级管理员的用户 ID，默认为 1。超级管理员不受任何权限限制

模块系统配置

• module 模块相关的核心配置
  • root：模块存放的根目录，默认为 modules
  • namespace：模块的根命名空间，默认为 Modules
  • default：系统默认模块列表，包含 develop、user、common 三个基础模块
  • default_dirs：新建模块时自动生成的默认目录结构
  • driver：模块信息存储驱动，支持 file 和 database 两种方式
  • routes：模块路由集合配置

响应机制配置

• response API 响应相关配置
  • always_json：强制 JSON 响应输出的中间件
  • request_handled_listener：请求处理监听器，用于统一响应格式

认证系统配置

• auth 认证相关配置
  • guards：认证守卫配置，定义了 admin 守卫使用 JWT 驱动
  • providers：用户提供者配置，指定用户模型

开发调试配置

• listen_db_log：是否开启数据库 SQL 查询日志监听，便于开发调试

路由系统配置

• route 全局路由配置
  • prefix：API 路由前缀，默认为 api
  • middlewares：默认应用的中间件列表

配置建议

项目有定制化需求时，优先检查这些配置选项，大多数需求可以通过配置调整来满足，无需修改源码。

模块配置

除了系统级配置，CatchAdmin 还支持模块级的独立配置。每个模块的配置相互独立，互不影响，提高了模块的可移植性。

默认配置方式

模块需要配置时，直接在模块目录下创建 config 目录，系统会自动发现并加载配置文件：

modules/YourModule/
├── config/
│   ├── database.php
│   └── services.php
└── ...

自定义配置路径

如果需要自定义配置文件位置，可以在模块的服务提供者中重写 configPath 方法：

namespace Modules\Test\Providers;

use Catch\CatchAdmin;
use Catch\Providers\CatchModuleServiceProvider;

class TestServiceProvider extends CatchModuleServiceProvider
{
    public function confitPath(): string
    {
        return config_path;
    }
}

配置文件结构

以权限模块为例，典型的模块配置结构如下：

Permissions/
└── config/
    ├── database.php
    └── permissions.php

配置读取方式

模块配置的读取需要包含模块名称作为前缀：

// 错误方式：直接读取配置文件名
config('database')  // ❌ 会读取系统的数据库配置

// 正确方式：模块名.配置文件名.配置键
config('permissions.database.connection')  // ✅ 读取权限模块的数据库配置
config('permissions.permissions.default_role')  // ✅ 读取权限模块的权限配置

配置命名规范

• 模块名：使用小写，与模块目录名一致
• 配置文件名：使用小写，语义明确
• 配置键名：使用下划线命名法

这种设计避免了模块间配置冲突，同时保持了良好的命名空间隔离。