79 lines
4.3 KiB
Markdown
79 lines
4.3 KiB
Markdown
# 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 常见问题与排错
|
||
```
|