# 1.4 新手入门指南

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

## 学习路线图

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

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

1. 准备环境：Go 1.27+、Node 18+（pnpm）、MySQL 8.0 —— 见 [2.1 开发环境准备](/zh/quickstart/environment.html)
2. 导入种子数据库脚本 —— 见 [2.2 数据库初始化](/zh/quickstart/database-init.html)
3. 按需调整 `config/config.yaml` —— 见 [2.3 配置文件与环境变量](/zh/quickstart/env-vars.html)
4. `make run` 启动后端（Windows 用 `make.bat run`），`pnpm dev` 启动前端
5. 登录后台，确认能看到菜单与仪表盘

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

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

- [4.2 请求处理链路](/zh/architecture/request-flow.html)
- [4.4 反射元数据驱动机制](/zh/architecture/bind-mechanism.html)
- [8.1 统一响应格式](/zh/api-spec/response.html)

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

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

项目内置 `gin_example` 示例模块，覆盖标准 CRUD 的全部典型场景。跟着 [第 3 章 模块开发实战](/zh/guide/overview.html) 从建表开始，依次完成：

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

完成后对照 [3.11 完整代码清单](/zh/guide/code-list.html) 核对自己的实现。

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

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

```bash
make gen TABLES="gin_example|示例表"
```

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

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

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

## 新手常见误区

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