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'];
<p>public function getScreenSupplierAttr($value, $data)
{
return $data['spec_rel'][0]['value'] ?? '未知';
}这样前端模板直接用 {$row.screen_supplier}，不用改数据库、不污染原始结构，升级时也不冲突。
立即学习“PHP免费学习笔记（深入）”；
- 避免在模型里写
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 表格参数、插件事件这四条线理顺，剩下的就是填业务了。
