Lei-Admin 开发文档

本文档帮助开发者快速了解 Lei-Admin 框架的开发规范和最佳实践。

框架概述

Lei-Admin 是基于 Laravel 12 构建的模块化后台管理框架，核心技术栈：

技术	版本	说明
Laravel	^12.0	PHP 框架
Livewire	^4.2	动态组件
Tailwind CSS	4.x	CSS 框架
DaisyUI	5.x	UI 组件库

核心特性

模块化架构：业务功能按模块组织，独立管理
RBAC 权限：基于角色的访问控制
安装向导：Web 界面完成系统安装
插件扩展：支持模块上传安装

目录结构

lei-admin/
├── app/
│   ├── Support/
│   │   ├── ModuleManager.php    # 模块管理器
│   │   └── helpers.php          # 辅助函数
│   ├── Services/
│   │   ├── MenuService.php      # 菜单服务
│   │   └── PermissionService.php # 权限服务
│   └── Http/Middleware/
│       ├── CheckPermission.php  # 权限中间件
│       └── ModuleEnabled.php    # 模块启用检查
├── config/
│   ├── lei-admin.php            # 框架配置
│   └── modules.php              # 模块配置
├── modules/                     # 模块目录
│   ├── Admin/                   # 管理员模块（核心）
│   ├── Permission/              # 权限模块（核心）
│   ├── System/                  # 系统设置（核心）
│   ├── FileManager/             # 文件管理（核心）
│   ├── ModuleManager/           # 模块管理（核心）
│   └── Install/                 # 安装模块（核心）
└── resources/
    └── css/app.css              # 设计系统样式

模块开发

创建模块

php artisan module:make Blog

模块结构

modules/Blog/
├── Config/
│   ├── config.php         # 模块配置
│   ├── menus.php          # 菜单配置
│   └── permissions.php    # 权限节点
├── Database/
│   ├── Migrations/        # 数据库迁移
│   └── Seeders/           # 数据填充
├── Http/
│   └── Controllers/       # 控制器
├── Livewire/              # Livewire 组件
├── Models/                # 模型
├── Providers/
│   └── BlogServiceProvider.php
├── Resources/views/       # 视图
├── Routes/web.php         # 路由
└── module.json            # 模块描述

module.json 示例

{
    "name": "Blog",
    "alias": "blog",
    "description": "博客管理模块",
    "version": "1.0.0",
    "priority": 100,
    "providers": [
        "Modules\\Blog\\Providers\\BlogServiceProvider"
    ]
}

ServiceProvider 示例

<?php
namespace Modules\Blog\Providers;
use Illuminate\Support\ServiceProvider;
use Livewire\Livewire;class BlogServiceProvider extends ServiceProvider
{
    public function boot(): void
    {
        // 加载路由
        $this->loadRoutesFrom(__DIR__ . '/../Routes/web.php');
        
        // 加载视图（命名空间：blog）
        $this->loadViewsFrom(__DIR__ . '/../Resources/views', 'blog');
        
        // 加载迁移
        $this->loadMigrationsFrom(__DIR__ . '/../Database/Migrations');
        
        // 注册 Livewire 组件（重要：不要加命名空间前缀）
        Livewire::component('blog-list', \Modules\Blog\Livewire\BlogList::class);
    }
}

路由定义

Routes/web.php 示例

<?php
use Illuminate\Support\Facades\Route;
use Modules\Blog\Http\Controllers\BlogController;Route::prefix('admin')
    ->middleware(['web', 'admin.auth', 'module:Blog'])
    ->group(function () {
        Route::get('blogs', [BlogController::class, 'index'])
            ->name('backend.blogs.index');
        Route::get('blogs/create', [BlogController::class, 'create'])
            ->name('backend.blogs.create');
        Route::post('blogs', [BlogController::class, 'store'])
            ->name('backend.blogs.store');
    });

路由命名规范

后台路由前缀：backend.
资源路由：backend.{resource}.{action}
示例：backend.blogs.index, backend.blogs.create

控制器

控制器示例

<?php
namespace Modules\Blog\Http\Controllers;
use App\Http\Controllers\BaseController;
use Modules\Blog\Models\Blog;
class BlogController extends BaseController
{
    public function index()
    {
        return view('blog::blogs.index');
    }
    public function create()
    {
        return view('blog::blogs.create');
    }
    public function store()
    {
        $validated = request()->validate([
            'title' => 'required|max:255',
            'content' => 'required',
        ]);
        Blog::create($validated);        return redirect()
            ->route('backend.blogs.index')
            ->with('success', '创建成功');
    }
}

视图开发

布局继承

@extends('admin::layouts.app')
@section('content')
<div class="banner-gradient p-8 mb-8">
    <h1 class="text-2xl font-semibold text-white">页面标题</h1>
</div><div class="content-section">
    <!-- 内容 -->
</div>
@endsection

常用 CSS 类

类名	说明
`banner-gradient`	蓝色渐变横幅
`content-section`	内容区块（白色背景圆角）
`stat-card-large`	统计卡片
`input-modern`	现代输入框
`table-modern`	现代表格
`settings-row`	设置项行

表单示例

<div class="content-section">
    <form action="{{ route('backend.blogs.store') }}" method="POST">
        @csrf
        <div class="settings-row">
            <div>
                <div class="settings-label">标题</div>
                <div class="settings-desc">文章标题</div>
            </div>
            <div class="settings-control">
                <input type="text" name="title" class="input-modern" required>
            </div>
        </div>
        <div class="flex justify-end mt-6">
            <button type="submit" class="btn btn-primary">保存</button>
        </div>
    </form>
</div>

Livewire 组件

创建组件

<?php
namespace Modules\Blog\Livewire;
use Livewire\Component;
use Modules\Blog\Models\Blog;
class BlogList extends Component
{
    public string $search = '';
    public function render()
    {
        $blogs = Blog::query()
            ->when($this->search, fn($q) => $q->where('title', 'like', "%{$this->search}%"))
            ->latest()
            ->paginate(10);        return view('blog::livewire.blog-list', compact('blogs'));
    }
}

注册组件（重要）

在 ServiceProvider 中注册时，不要加模块命名空间前缀：

// ✅ 正确
Livewire::component('blog-list', \Modules\Blog\Livewire\BlogList::class);// ❌ 错误
Livewire::component('blog::blog-list', \Modules\Blog\Livewire\BlogList::class);

使用组件

<livewire:blog-list />

权限控制

定义权限节点

在 Config/permissions.php 中定义：

<?phpreturn [
    'blog' => [
        'label' => '博客管理',
        'children' => [
            'blog.view' => ['label' => '查看博客'],
            'blog.create' => ['label' => '创建博客'],
            'blog.edit' => ['label' => '编辑博客'],
            'blog.delete' => ['label' => '删除博客'],
        ],
    ],
];

控制器中检查权限

public function __construct()
{
    $this->middleware('permission:blog.view')->only('index', 'show');
    $this->middleware('permission:blog.create')->only('create', 'store');
}

视图中检查权限

@can('blog.create')
    <a href="{{ route('backend.blogs.create') }}" class="btn btn-primary">新建</a>
@endcan

代码中检查权限

if (admin()->can('blog.delete')) {
    // 有权限
}

菜单配置

Config/menus.php 示例

<?phpreturn [
    [
        'label' => '博客管理',
        'icon' => '<svg>...</svg>',
        'route' => 'backend.blogs.index',
        'permission' => 'blog.view',
        'priority' => 50,
    ],
];

带子菜单

<?phpreturn [
    [
        'label' => '内容管理',
        'icon' => '<svg>...</svg>',
        'children' => [
            [
                'label' => '文章列表',
                'route' => 'backend.blogs.index',
                'permission' => 'blog.view',
            ],
            [
                'label' => '分类管理',
                'route' => 'backend.categories.index',
                'permission' => 'category.view',
            ],
        ],
    ],
];

数据库

创建迁移

php artisan make:migration create_blogs_table --path=modules/Blog/Database/Migrations

运行迁移

# 运行所有迁移
php artisan migrate
运行指定模块迁移
php artisan migrate --path=modules/Blog/Database/Migrations

常见问题

1. Livewire 组件找不到

错误：Unable to find component: [xxx]

原因：组件注册时使用了命名空间前缀

解决：

// 改为不带前缀
Livewire::component('blog-list', BlogList::class);

2. 视图找不到

错误：View [xxx] not found

原因：视图命名空间未正确加载

解决：确保 ServiceProvider 中正确加载视图：

$this->loadViewsFrom(__DIR__ . '/../Resources/views', 'blog');

3. 路由未生效

原因：模块未启用或路由未加载

解决：

检查 storage/modules/enabled.json 中是否包含模块
确保 ServiceProvider 中调用了 loadRoutesFrom()

4. 权限不生效

原因：权限节点未同步到数据库

解决：

php artisan permission:sync

5. 样式不生效

原因：CSS 未编译

解决：

npm run build

辅助函数

// 获取当前登录管理员
admin()
// 检查模块是否启用
module_enabled('Blog')
// 获取模块配置
module_config('Blog', 'key', 'default')// 检查权限
admin()->can('blog.view')