3.1 概述与目标

概述

本章以「案例演示模块（example）」为主线，完整走一遍模块开发全流程：建表 → DAO → 请求与校验 → 逻辑层 → 控制器 → 服务注册与路由 → 权限节点 → 前端联调。章内所有代码均摘自项目真实实现，可直接对照源码阅读。

本章目标

完成本章后，你将能够：

1. 设计符合项目规范的业务表（统一审计列 / del_flag / uk_* 唯一索引 / 注释枚举）
2. 产出并理解 dao/entity/do 四件（gf gen dao 或生成器）
3. 编写 api/v1 请求响应结构体与 gmeta 注解（权限/日志/OpenAPI 一体）
4. 用 ModuleSpec 声明式基座实现逻辑层（筛选/字典/文件字段/钩子）
5. 完成薄层控制器 + 手维护 service 接口 + 路由注册
6. 配置权限节点并完成前端 querySchemas/columns/api 三件套联调

模块开发的两条路径

路径	适用场景	说明
代码生成器	标准 CRUD 模块	一条命令产出全部文件 + 菜单/权限/字典/路由副作用（见第 10 章）
手动编写	复杂业务模块	按本章步骤逐件编写，完全掌控每行代码

两条路径产出的结构完全一致——生成器模板就是按本章规范制作的。建议先读懂本章，再用生成器提效。

模块文件全景（以 example 为例）

一个模块在后端落地需要以下文件（★ 为手工编写，○ 为工具产出）：

○ internal/dao/example.go              数据访问（自定义模板：挂钩子 + Ctx 覆写）
○ internal/dao/internal/example.go     dao 内部实现（勿手改）
○ internal/model/entity/example.go     实体
○ internal/model/do/example.go         数据对象 DO
★ api/v1/example.go                    全部 Req/Res 结构体 + gmeta 注解
★ internal/controller/example.go       薄层控制器（转发 service）
★ internal/service/example.go          手维护接口 + Register + 取用函数
★ internal/logic/example.go            业务实现（ModuleSpec 声明 + 方法委托）
★ internal/router/router.go            追加一行 Bind 注册（生成器自动写入）
★ ui/src/api/tool/example.ts           前端接口模块
★ ui/src/views/tool/example/           前端页面五件套
    index.vue / edit.vue / detail.vue / columns.ts / querySchemas.ts

标准接口清单（七件套 + 扩展）

方法	HTTP	路由模板	说明
Page	GET	/api/example/page	分页（pageNo/pageSize + 筛选）
List	GET	/api/example/list	全量/树形（下拉、树选择）
Detail	GET	/api/example/detail/:id	详情
Add	POST	/api/example/add	新增，返回 {id}
Update	PUT	/api/example/update	修改（body 含 id）
Delete	DELETE	/api/example/delete/:id	软删（del_flag=1）
BatchDelete	DELETE	/api/example/batchDelete	批量删除 body {ids:[]}
Import	POST	/api/example/import	multipart 文件导入（xls/xlsx）
Export	GET	/api/example/export	导出文件
Status	PUT	/api/example/status	状态切换（有 status 列的模块）

命名约定：结构体 {Mod}{Action}Req / {Mod}{Action}Res；controller 方法名 = logic 方法名 = 上表方法名。日志标题为「{模块中文名}-{动作}」（如"案例演示-查询分页记录"），动作映射：page=查询分页记录、list=查询列表、detail=查询详情、add=新增记录、update=修改记录、delete=删除记录、batchDelete=批量删除记录、import=导入数据、export=导出数据、status=设置状态。

后续章节地图

3.2 数据库建表      → 表规范与 example 建表语句
3.3 DAO 数据层      → 四件产出与 dao.Ctx 架构红线
3.4 请求与校验      → api/v1 结构体 + gmeta + gvalid（真实代码）
3.5 逻辑层开发      → ModuleSpec 声明与方法委托（真实代码）
3.6 控制器开发      → 薄层透传（真实代码）
3.7 服务注册与路由   → service 接口三件套 + Bind 注册（真实代码）
3.8 权限节点配置    → 权限码规范与角色勾选
3.9 前端联调指引    → api/columns/querySchemas 三件套
3.10 完整代码清单   → example 模块四件套全文（摘自项目）
3.11 常见问题与排错