3.1 概述与目标

概述

本章以项目内置的 example（案例演示，gin_example） 模块为例，从数据库建表到前端页面联调，完整演示开发全流程。学完本章后，你将掌握新增业务模块的标准步骤。

开发流程总览

┌──────────┐
│ 1. 建表   │  创建 gin_ 前缀表（含公共审计字段）
└────┬─────┘
     │
     ▼
┌──────────┐
│ 2. dto   │  internal/model/dto/{module}.go —— 请求/响应契约 + 校验标签
└────┬─────┘
     │
     ▼
┌──────────┐
│ 3. repo  │  internal/repository/{module}.go —— XxxRepo + Base，统一 Ctx(ctx)
└────┬─────┘
     │
     ▼
┌──────────┐
│ 4. service│ internal/service/{module}.go —— sXxx + ModuleSpec 声明 + 手写逻辑
└────┬─────┘
     │
     ▼
┌──────────┐
│ 5. handler│ internal/handler/{module}.go —— 极薄委托，签名固定
└────┬─────┘
     │
     ▼
┌──────────┐
│ 6. 路由   │  router.go 注册表加一条 Bind 声明（RouteSpec 表）
└────┬─────┘
     │
     ▼
┌──────────┐
│ 7. 菜单   │  配置菜单与权限节点（或直接用代码生成器代劳）
└────┬─────┘
     │
     ▼
┌──────────┐
│ 8. 前端   │  ui/src/api + ui/src/views（详见第 9 章）
└──────────┘

第 2～6 步也可以交给 第 10 章 代码生成器 自动完成——生成器产物与手写规约完全一致，本章教你读懂并手工掌握每一步。

开发约定

约定	说明	示例
表名	gin_ 前缀 + 小写下划线	gin_example
字段名	小写下划线	create_user、sort
主键	统一 id，自增	id INT PRIMARY KEY AUTO_INCREMENT
四件套	dto / repository / service / handler 同名成套	example.go × 4
服务实例	type sXxx struct{} + init 注册	var Example *sExample
权限码	sys:模块名:操作	sys:example:page
路由风格	动词命名、全小驼峰方法	GET /api/example/page
日志文案	模块名-动作描述	案例演示-查询分页记录

本章示例覆盖场景

gin_example 是代码生成器的参考模板，涵盖标准 CRUD 的全部典型场景：

• 分页列表（名称模糊、类型/状态等值过滤、字典显示名回填）
• 全量列表（limit 上限）
• 详情查询
• 新增 / 修改（含单图字段 temp 转正）
• 单列状态更新（手写逻辑）
• 删除 / 批量删除（软删除）
• Excel 导入（multipart 文件 + 逐行校验）
• Excel 导出（条件过滤 + 字典翻译 + 文件 URL 返回）
• 权限控制与操作日志（RouteSpec 声明驱动）

涉及文件

internal/model/dto/example.go            # 契约层
internal/repository/example.go           # 数据访问层
internal/service/example.go              # 业务层（ModuleSpec 声明）
internal/handler/example.go              # 接口层
internal/router/router.go                # RouteSpec 注册表
ui/src/api/tool/example.ts               # 前端 API 模块
ui/src/views/tool/example/               # 前端页面