FastAdmin二次开发需遵循四大核心约定：控制器必须继承app\admin\controller\Admin，模型用访问器+追加属性而非改库，表格JS配置在Controller.initTable()中调整，业务逻辑通过插件事件解耦。

FastAdmin 不仅适合二次开发，而且是 PHP 后台框架中为数不多把“可二次开发性”设计进骨架里的成熟方案——前提是别把它当黑盒用，得摸清它的约定和钩子位置。

控制器继承链不能绕开 app\admin\controller\Admin

很多新手直接新建控制器不继承基类，结果权限校验失效、$this->auth 为空、JS 初始化失败。FastAdmin 的后台逻辑（如菜单权限、数据范围过滤、登录态保持）全依赖这个父类的 initialize() 和中间件链。

• 必须继承 \app\admin\controller\Admin，不是 think\Controller 或空类
• 若需重写 index 方法，先复制 application/admin/library/traits/Backend.php 中的 index()，再修改，否则会丢失分页、搜索、多选等默认行为
• 自定义方法加权限注解，比如 /** @permission 订单导出,export */，否则在角色配置页看不到该权限项

模型层改字段别硬改数据库，优先用访问器+追加属性

比如商品表没「屏幕供应商」字段，但规格数据存在 JSON 字段 spec_rel 里——这时不该 ALTER TABLE 加字段，而该在模型里用 $append + getXXXAttr 动态计算：

protected $append = ['screen_supplier'];
public function getScreenSupplierAttr($value, $data)
{
return $data['spec_rel'][0]['value'] ?? '未知';
}

这样前端模板直接用 {$row.screen_supplier}，不用改数据库、不污染原始结构，升级时也不冲突。

• 避免在模型里写 Db::name('goods')->where(...)->find() 这类硬查询，破坏 ORM 封装和缓存机制
• 验证规则统一走 $validate 属性或 validate() 方法，别在控制器里手写 if 判断
• 自动完成字段（如 createtime）建议用 $autoWriteTimestamp = true，而非手动赋值

表格 JS 配置别改全局 bootstrapTable，默认参数藏在 table.js 里

想禁用 Excel 导出？不是删 HTML 按钮，而是改 JS 初始化里的 showexport: false；想隐藏列切换按钮？设 showcolumns: false。这些都在 public/assets/js/backend/xxx.js 的 Controller.initTable() 调用中。

• 所有表格行为由 bootstrapTable 驱动，参数名大小写敏感（如 showToggle ≠ showtoggle）
• 搜索字段默认只搜 id，要扩展成多字段，得改 searchFields 参数，比如 searchFields: 'title,category_id,status'
• 跨页选择（checkboxHeader）默认关闭，开启后记得同步后端 multi 方法支持批量操作逻辑

插件和事件机制才是解耦关键，别直接改 application/admin 下的核心文件

订单状态变更要触发供应商备货？别在 Order.php 控制器里写业务逻辑，而是挂事件钩子：

public function onOrderStatusChange($order)
{
    if ($order->order_status == 3 && $order->pay_status == 1) {
        hook('supplier_prepare_stock', $order);
    }
}

然后在插件目录（addons/supplier/）里监听这个事件。升级 FastAdmin 时，核心代码一覆盖就丢功能；插件目录不动，逻辑就稳。

• 插件安装后自动注册服务提供者，无需手动 require
• 事件名用英文小写+下划线，避免驼峰，防止 Windows 下大小写不敏感导致加载失败
• 权限控制尽量走注解或 Auth::instance()->check('rule') ，别靠 session 变量硬判断

真正卡住二次开发进度的，从来不是功能写不出来，而是没意识到 FastAdmin 的“约定大于配置”有多强——它不拦你自由发挥，但一旦偏离路径，就会在权限、分页、导出、搜索这些看似琐碎的地方反复报错。把控制器继承、模型访问器、JS 表格参数、插件事件这四条线理顺，剩下的就是填业务了。