# 3.1 概述与目标

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

## 本章目标

完成本章后，你将能够：

```text
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 为例）

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

```text
○ 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=设置状态。

## 后续章节地图

```text
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 常见问题与排错
```