1.4 新手入门指南

:::tip 概述本页给出一条从"跑起来"到"独立开发模块"的最短学习路径。按顺序完成各阶段后，你将具备在本项目上进行二次开发的全部基础能力。 :::

学习路线图

┌──────────┐
│ 阶段一    │  把项目跑起来（后端 + 前端 + 数据库）
└────┬─────┘
     │
     ▼
┌──────────┐
│ 阶段二    │  读懂一次请求的完整链路
└────┬─────┘
     │
     ▼
┌──────────┐
│ 阶段三    │  跟做 example 模块，走完四件套开发
└────┬─────┘
     │
     ▼
┌──────────┐
│ 阶段四    │  掌握代码生成器与前端联调
└────┬─────┘
     │
     ▼
┌──────────┐
│ 阶段五    │  按生产标准部署上线
└──────────┘

阶段一：把项目跑起来（约 30 分钟）

准备环境：Go 1.27+、Node 18+（pnpm）、MySQL 8.0 —— 见 2.1 开发环境准备
导入种子数据库脚本 —— 见 2.2 数据库初始化
按需调整 config/config.yaml —— 见 2.3 配置文件与环境变量
make run 启动后端（Windows 用 make.bat run），pnpm dev 启动前端
登录后台，确认能看到菜单与仪表盘

阶段二：读懂请求链路（约 1 小时）

以一次登录或分页查询为例，跟踪请求从 Gin 入口经过中间件链、反射路由、handler、service 到 repository 的全过程：

建立"声明在哪里、逻辑在哪里、数据从哪进哪出"的全景认知。

阶段三：跟做 example 模块（约 2 小时）

项目内置 gin_example 示例模块，覆盖标准 CRUD 的全部典型场景。跟着第 3 章模块开发实战从建表开始，依次完成：

建表 → dto → repository → service → handler → RouteSpec 声明 → 权限配置 → 前端联调

完成后对照 3.11 完整代码清单核对自己的实现。

阶段四：代码生成器（约 1 小时）

手工走通流程后，用生成器把同样的模块自动生成一遍：

make gen TABLES="gin_example|示例表"

对比生成产物与手写代码的差异，理解模板体系 —— 见第 10 章代码生成器。随后阅读第 9 章前端开发掌握前端页面与 API 模块的编写规范。

阶段五：部署上线（约 1 小时）

按第 11 章运维部署完成一次生产部署演练：环境规划 → 数据库初始化 → 后端构建 → 前端构建 → Nginx/Docker 装配 → 安全加固检查。

新手常见误区

误区	正确做法
在 service 里直接拿 `*gorm.DB`	统一 `repository.NewXxxRepo().Ctx(ctx)`
用物理删除清理数据	一切删除走软删除，特殊场景用 `WithPhysicalDelete(ctx)` 显式放行
在 handler 写业务逻辑	handler 只做委托，逻辑进 service
绕过 RouteSpec 手动注册路由	新接口一律在 RouteSpec 表加声明
富文本正文直接存 HTML	正文内本站文件用 `[IMG_URL]` 占位符
新增配置键不更新 .env.example	两者必须同步，`make check-config` 硬检查

3.7 KiB Raw Blame History Unescape Escape