QQ咨询 官方微信
微信二维码

添加微信好友

官方小程序
百度小程序

百度小程序

微信小程序

微信小程序

头条小程序

头条小程序

关于我们

Fastadmin

FastAdmin 常用封装实战教程:十八个可以直接对照的封装点

 mcp  2026-11-22 10:40:40

FastAdmin 真正省时间的地方,不是模板有多漂亮,而是它把后台开发里反复出现的部分提前封装好了:基类控制器负责列表、增删改查和数据权限,模型基类接管时间戳、字段过滤与类型转换,验证器守住数据入口,权限与站点配置由公共类统一托管,前端用 RequireJS 把表格、表单、上传包成即插即用的模块,最后用一条命令把这些文件全部生成出来。本文按"基类—模型—验证—列表—前端—工具"的顺序拆开十八个常用封装,说明每一层写在哪、怎么开启、容易在哪里踩坑,照着改比从头通读文档更快。

FastAdmin 常用封装

1. 后台基类:继承一次,六个动作全有

所有后台控制器都继承 app\common\controller\Backend。基类里已经写好了 index、add、edit、del、multi、selectpage 六个方法,你只需要声明 protected $model 并在 _initialize() 中赋值为对应的模型实例,列表查询、分页、排序、删除前确认这些细节全部由基类接管。要注意赋值必须写在 _initialize() 里而不是 __construct(),父类构造函数先执行,在构造里赋值会被基类随后的初始化逻辑覆盖成空,页面打开就直接报模型未定义。

2. CRUD 生成器:把整套文件一次生成出来

php think crud -t fa_article --force 会读取数据表结构,一次性生成控制器、模型、验证器、视图、JS 和语言包六类文件;php think menu -c article 再生成权限节点和左侧菜单。生成时字段的中文标签直接取自数据表的 COMMENT,建表阶段把注释写清楚,能省掉大量事后改名的工作。生成结果只是脚手架,字段顺序、列表列宽、搜索项通常仍要手调,别把它当最终产物直接上线。

3. 模型基类:字段读写的统一出口

app\common\model\Base 预设了自动时间戳、软删除和一批通用方法。$append 可以把不存在于数据表的计算字段输出到接口,$visible 与 $hidden 决定哪些字段能出现在 JSON 里,$type 负责把以 JSON 存储的 images 自动转成数组。枚举文案用获取器 getStatusList() 集中管理,模板里直接输出 $row.status_text,将来换文案只改一处,不必在十几个视图里逐个替换,也不会出现同一状态在不同页面叫法不一样的情况。

4. 验证器:数据入口只留一道关

验证器放在 app\common\validate\Base 之下,规则写 $rule,场景写 $scene,提示写 $message。控制器里打开 $this->modelValidate = true,基类就会在 add 和 edit 时自动校验;需要按方法区分场景时再开 $this->modelSceneValidate,场景名与方法名对应。唯一性校验用 unique:表名,字段,批量操作用 batch。校验不通过时基类统一走 $this->error(),前端 Toastr 直接弹出提示,不需要自己拼错误文案。

5. 数据权限:三行配置决定能看到什么

$dataLimit = 'auth' 只显示当前管理员权限范围内的数据,'personal' 按 admin_id 只看到自己创建的内容,'children' 连同下级管理员的数据一起显示。归属字段通过 $dataLimitField 指定。开启后基类会自动把条件拼进列表查询,但手写 SQL、join 子查询和自定义方法不会自动继承这份限制,这些地方要自己补 where,否则权限判断只在前台看着生效,换个入口就能绕过。

6. 关联查询与关联搜索

打开 $this->relationSearch = true,index 中的 with(['category']) 就能让关联表的字段直接出现在列表列和搜索框中,字段名写成 category.name 即可。这层封装的代价是额外的 SQL,数据量大时要确认关联字段建了索引,否则翻页会比预想中慢很多。只做一层关联时用它最省事,多层嵌套建议改成视图或冗余字段,把计算留在写入阶段。

7. Selectpage:不写 ajax 的远程下拉

基类的 selectpage 方法配合 $this->selectpageFields = ['id', 'name'],就得到一个可分页、可搜索的远程数据源。视图里给输入框加上 data-source="article/index"、data-field="name"、data-primary-key="id",前端会自动发起请求、渲染下拉、回填选中值。这层封装的坑在于 data-source 必须指向能返回 selectpage 结构的地址,路径写错时下拉会一直转圈却不报错,排查时先看网络请求的状态码和返回结构。

8. 统一响应:成功和失败只有两种形状

$this->success('保存成功', null, ['id' => $id]) 与 $this->error('余额不足') 会在 ajax 请求时自动输出 code、msg、data 结构的 JSON,普通页面请求则走跳转。约定是 code=1 成功、code=0 失败,前端 Fast.api.ajax 按这个码判断后续动作。自己写的接口也要守住同一约定,否则封装好的前端处理逻辑会直接失效,明明接口通了页面却没有反应。

9. 前端 JS:Table 与 Form 两套封装

public/assets/js/backend/ 下的文件用 RequireJS 定义模块。Table.api.init({extend: {index, add, edit, del, multi, selectpage}}) 声明各操作的地址,Table.api.bindevent(table) 一次挂上批量删除、拖拽排序、状态切换、导出等行为;表单用 Form.api.bindevent($('form[role=form]'))。这两行是后台页面能跑起来的最小配置,地址漏写时按钮不会报错,只会静默无响应,排查顺序是先看 extend 里缺了哪一项。

10. 声明式属性:data-* 比内联脚本可靠

封装后的表单和表格尽量用属性驱动:data-rule 写验证规则,data-source 写数据源,data-url 写提交地址,data-multiple 控制多选,上传控件用 data-mimetype 和 data-maxsize 限制类型与体积。这些属性由 bindevent 统一解析,以后升级框架只改封装、不动页面。混写内联 onclick 会绕过封装,后期换主题或改交互时最难排查的往往就是这些散落在模板里的脚本。

11. 权限 Auth:把判断收进一个实例

权限由 \app\common\library\Auth::instance() 提供,check($rule, $uid) 判断某个节点是否有权,getRuleList() 取当前管理员可见的规则树,getGroups() 取所属角色组。规则节点存在 fa_auth_rule 表里,ismenu 决定是否出现在左侧菜单,父子关系靠 pid 维护,父节点关闭时子节点自动隐藏。控制器的 $noNeedLogin 与 $noNeedRight 可以声明免登录、免鉴权的方法,登录、验证码、上传回调这类接口必须加白名单,否则会被基类直接拦掉。

12. 模板助手与权限按钮

视图里 {:build_heading()} 和 {:build_toolbar()} 生成标题区与工具栏,{$row.xxx} 输出已经处理过的字段,{:__('Title')} 走语言包,{if $auth->check('article/edit')} 控制按钮是否出现。要记住视图只负责隐藏按钮,后端方法里仍要用 $this->auth->check() 再校验一次,否则直接请求 URL 依然能执行,隐藏按钮只是一种体验层的约束,不能当成安全边界。

13. 附件上传与地址输出

\app\common\library\Upload::upload() 是静态入口,文件落到 uploads/日期 目录并写入 attachment 表,返回数组里有 url 和 fullurl;输出时用 cdnurl($url) 补上域名或 CDN 前缀。切换 OSS 或图床时优先修改 Upload 的配置,不要在每个控制器里各写一遍上传逻辑,否则以后更换存储方式要改几十个文件,还很容易漏掉缩略图、水印这些附加处理。

14. 系统配置与站点变量

后台"系统配置"的数据由 \app\common\model\Config 托管,读取时统一用 config('site.字段名'),视图中则可以直接使用全局的 $site 变量,因为基类初始化时已经把站点配置注入模板。新增配置项要在 application/extra/site.php 里补上默认值,再去后台配置页登记,只在控制器里写 config() 并不会自动生成表单项。改完配置前台没变化,先检查配置缓存是否刷新。

15. 多语言:三处语言包,一套键名

语言包分三处:application/admin/lang/zh-cn/ 放后台模块词条,application/common/lang/ 放公共词条,验证器提示也走同一套键。模板里用 {:__('Article')},控制器里用 __('Article'),JS 通过 RequireJS 加载 lang 模块取词。键名建议与控制器或字段同名,翻译时更容易定位;漏翻不会报错,只会原样输出键名,所以页面上莫名出现英文单词时,先怀疑语言包里缺了这一条。

16. 行为与钩子:事件解耦的轻量做法

框架沿用 ThinkPHP 的行为机制做事件解耦:tags.php 里把标签映射到行为类,业务代码里用 Hook::listen('user_register', $user) 触发,行为类实现 run() 接收参数。它和插件钩子是同一套底层机制,区别在于行为类放在应用目录、跟着项目代码走,插件钩子在 addons/ 下、可以后台装卸。埋点、操作日志、注册赠送积分这类轻量逻辑用行为就够,需要跨站点复用的功能再做成插件。

17. 插件:可装卸的功能单元

插件放在 addons/ 目录,主类继承 Addons,方法名与钩子标签保持一致,配置写在 config.php,用 get_addon_config('name') 读取,地址用 addons_url('name://controller/action') 生成。钩子只在后台启用插件后才生效,调试时先确认插件状态,否则代码没错、钩子却静默不触发,很容易把时间浪费在怀疑业务逻辑上。插件里的路由、语言包、静态资源都走自己的目录,别图省事往主应用里塞。

18. 命令行与消息发送

自定义命令在 application/command.php 注册,继承 think\console\Command 重写 configure 和 execute;短信、邮件统一走 app\common\library\Ems::send('sms', $mobile, ['code' => $code]),失败返回错误信息而不是抛异常。把这两类工具收在一处,定时任务、注册流程和后台手动操作才能共用同一套发送逻辑,不会出现验证码模板三处不一致的情况。

结语

这十八个封装点覆盖了 FastAdmin 日常开发的主要路径,判断是否用对了只有一个标准:新增一个业务模块时,你要写的应该只是表结构、业务规则和少量定制视图,而不是再重复一遍分页、验证、权限和上传。如果发现自己在抄上一套控制器,说明某一层封装还没吃透,回头补上比继续堆代码划算。

¥ 打赏
×
如果您觉得文章帮助了您就打赏一下吧
非常感谢你的打赏,我们将继续分享更多优质内容,让我们一起创建更加美好的网络世界!

支付宝扫一扫打赏

微信扫一扫打赏

本文《FastAdmin 常用封装实战教程:十八个可以直接对照的封装点》发布于石头博客文章,作者:mcp,如若转载,请注明出处:https://www.pweb123.com/kuangjia/fastadmin/1248.html,否则禁止转载,谢谢配合!

文章点评

我来说两句 已有0条评论
点击图片更换

添加微信好友