6.19 案例演示模块

概述

案例演示模块（goframe_example，tool 域）是官方完整样板：七件套 + 状态切换 + Excel 导入导出 + 文件字段 + 字典填充，前端五件套齐备。第 3 章模块开发实战全程以它为参照。

接口清单

七件套 + PUT /api/example/status（sys:example:status）
  + POST /api/example/import（sys:example:import）
  + GET  /api/example/export（sys:example:export）
sys:example:{page|list|detail|add|update|delete|batchDelete|status|import|export}

后端声明（真实代码，摘自 internal/logic/example.go）

// exampleSerializeMaps 枚举字段到字典编码的映射
// {field}Text 由基座自动填充
var exampleSerializeMaps = map[string]string{
	"status": "example_status",
}

// exampleSpec 案例演示模块声明
//
// 采用声明式实现：查询、输出与规则均在声明中定义，方法仅做委托
var exampleSpec = ModuleSpec[v1.ExampleItem, v1.ExampleItem, v1.ExampleDetailRes]{
	Model:         dao.Example.Ctx,
	LikeFields:    []string{"name"},
	EqFields:      []string{"type", "status"},
	OrderBy:       "sort, id",
	SerializeMaps: exampleSerializeMaps,
	FileFields: []string{
		"avatar",
	},
	FileSaveDir: "example",
	ToData:      exampleToData,
}

覆盖的基座能力：Like/Eq 筛选、默认排序、字典文本填充、单文件字段两段式、全量表单转换。

扩展方法（手写示范）

• Status：非标准方法手写实现（dao 直接 Update 单列）
• Import：excel.ReadSheet 逐行校验写入，返回成功/失败统计与逐行原因
• Export：exampleSpec.applyFilters 与列表同套筛选 → DictGetText 枚举转文本 → excel.WriteSheet

完整代码见 3.10 完整代码清单。

前端五件套（ui/src/views/tool/example/）

文件	职责
index.vue	列表页（分页表格 + querySchemas 筛选 + 增删改入口）
edit.vue	新增/编辑弹窗表单
detail.vue	详情视图
columns.ts	表格列配置（图片列 ElAvatar 渲染示范）
querySchemas.ts	筛选表单配置（Input/Select 示范）

接口模块：ui/src/api/tool/example.ts（getExamplePage/exampleAdd…）。

学习路径建议

1. 跑通页面：登录 → 工具 → 案例演示 → 增删改查/导入导出全流程点一遍
2. 对照后端：api/v1/example.go（gmeta+gvalid）→ logic/example.go（spec+委托）
   → controller/service（透传/接口）→ dao/example.go（钩子+Ctx）
3. 改一个字段：加 remark 列 → 四处补齐（3.3 改字段实战）
4. 仿写新模块：以 example 为骨架手动写一遍，或用生成器产出后对照差异

生成器视角

example 也是生成器产物的示范形态（ModuleSpec 基座风格的完整可用实现）。生成器对含枚举注释/图片列的表会产出同样的模式：

go run ./cmd/generator -tables "goframe_example|案例演示表"   # 产出与 example 同构的全套文件