90 lines
3.5 KiB
Markdown
90 lines
3.5 KiB
Markdown
# 3.1 概述与目标
|
||
|
||
:::tip 概述
|
||
本章以项目内置的 **example（案例演示，`gin_example`）** 模块为例，从数据库建表到前端页面联调，完整演示开发全流程。学完本章后，你将掌握新增业务模块的标准步骤。
|
||
:::
|
||
|
||
## 开发流程总览
|
||
|
||
```text
|
||
┌──────────┐
|
||
│ 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 章 代码生成器](/zh/generator/overview.html) 自动完成——生成器产物与手写规约完全一致，本章教你读懂并手工掌握每一步。
|
||
|
||
## 开发约定
|
||
|
||
| 约定 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| 表名 | `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 声明驱动）
|
||
|
||
## 涉及文件
|
||
|
||
```text
|
||
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/ # 前端页面
|
||
```
|