87 lines
3.7 KiB
Markdown
87 lines
3.7 KiB
Markdown
# 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` 硬检查 |
|