接手一个 ModStart 项目,第一周都在猜框架怎么用

开发示例程序 使用文档
开发示例程序 使用文档

代码能跑,但看不懂:后台那些表格和表单是怎么生成出来的?弹窗怎么开?配置项存在哪儿?为什么改一个 Controller 就会多一个菜单?

这些问题在文档里能找到答案,但文档是散的。开发示例程序把它们收成一个能跑起来的模块:想学哪一块,直接打开对应的后台页面,看代码、改代码、刷新看效果。

装完之后多了什么

只依赖 Vendor,装完后台左侧多一个「开发示例」菜单,点开是一棵三十多个页面的树:

数据表格 Grid

  • 默认数据表格、独立控制表格
  • 多个表格同页、树状表格
  • 自定义视图、行操作自定义

数据表单 Form

  • 默认表单、系统配置表单
  • 复杂布局(分组、分栏、字段联动)
  • 表单动态显示(选了某个值才出现某些字段)
  • 弹窗表单
  • 表单所有组件一览(文本框、下拉、日期、图片、富文本、颜色……)

组件与前端

  • 数据统计卡片、Echarts 图表
  • 图标、布局、Tw 原子类、Vue 组件
  • 前端常用组件一览

其它

  • 数据导出、数据导入
  • 后台任务调度
  • 开发者文档入口

前台还有几个页面:/demo 首页、/demo/member_login_required(需要登录才能访问的示例)、/demo/test 和 /demo/test/{id}(列表 + 详情)。

它最有用的三个地方

第一,表单字段一览。 这一页把所有可用字段排在一张表单上:文本、数字、金额、下拉、单选、多选、开关、日期时间、图片、多图、文件、富文本、颜色、图标、标签、级联、Key-Value……每个字段旁边有说明。做后台时想「有没有现成的字段类型能表达这个」,先来这里翻一遍,比翻源码快。

第二,配置项那一页。 就是截图里那个「简单配置」:一个开关、一个文本框、一个下拉,底下写着命名的建议(模块名_键值)和取值方式(modstart_config('键值'))。系统配置表单是最常写错的一类,很多人的第一版配置会忘记 defaultValue,导致老数据读出来是 null。

第三,接口文档页。 前台有一个自动生成的 API 文档页面,按分类列出接口:新闻分类、新闻列表、新闻分页……每个接口能展开看参数,还能点「Try it out」直接发一次请求。

这一页不是手写的,是 Controller 上的注释生成的:方法上方写 @Api、@ApiDesc、@ApiMethod,参数写 @ApiBodyParam,页面就有了。这份注释同时是给前端看的手册——写接口时顺手写注解,比事后补文档现实。

接口文档页:按「新闻分类」「新闻」分组,每条是一个 POST 接口,展开后有参数表格和「Try it out」按钮

学的时候按这个顺序

不要从 Grid 开始。后台的页面是「列表 → 详情 → 编辑」这条链,先弄懂一条链,剩下的都是变体。

一个建议的路径:

  1. 默认数据表单:一个 Controller 里怎么声明字段、怎么保存。看完改一个字段名,刷新页面看变化。
  2. 默认数据表格:同一套思路,换成列表。注意它和表单共用同一个模型。
  3. 系统配置表单:和上面的表单不是一个东西,但长得像,很多人第一次会混。配置是全局的键值,表单是表里的行。
  4. 弹窗表单:后台里点「编辑」弹一层,这是这套框架最常用的交互,值得单独看。
  5. 前端组件与 Tw 原子类:前台模板怎么写。这一块决定你做出来的页面像不像官方的。
  6. 数据导出、任务调度:等前面熟了再看,属于「加功能」的部分。

每一步都别只看,改一行再刷新。这个模块的价值在于它是可改的:不像文档只能读,改坏了删掉重装就有。

当前台模板的抄写来源

/demo 前台那几个页面是现成的样板:列表页怎么分页、详情页怎么取数据、需要登录的页面怎么写跳转。

新建模块时最省事的做法是复制 Demo 目录、改 config.json 里的名字,再删掉不需要的页面。比从空目录开始写快得多,也不会漏掉 Core/ModuleServiceProvider 里的注册。

但不要把它留在正式站。它的菜单挂在后台,接口是公开的,代码里还带着一堆测试用的写入逻辑(Test 目录里有 UI 测试、Api 测试、Seed 数据)。上线前卸载,或者至少把菜单去掉。

一个容易忽略的细节

模块里的 Lang 目录说明这套框架的界面文案是可以多语言的;Job 目录里是队列任务的示例;Res 里是静态资源。

这三个目录很多人第一次见会跳过,等到要做「后台有个按钮点一下跑十分钟的活」时才想起来找队列,要接第二个语言时才发现文案全是散的。趁着看示例的时候顺手扫一眼,知道东西在哪就行。

更新: 2026-11-12 16:37:38
QQ
微信
客服