签入版本

2026-10-20 21:53:26 +08:00
parent 5cc3da657c
commit b33799aa63
427 changed files with 32547 additions and 1 deletions
@@ -0,0 +1,170 @@
+# 1.4 新手入门指南
+
+:::tip 概述
+本节面向第一次接触本项目的开发者，给出一条最短路径：跑起来 → 看懂一个请求 → 改一个字段 → 开发一个新模块。全程约 1 小时。
+:::
+
+## 学习路径总览
+
+```mermaid
+graph TD
+    A[克隆代码] --> B[初始化数据库]
+    B --> C[启动后端 :8000]
+    C --> D[启动前端 :9100]
+    D --> E[登录 admin/123456]
+    E --> F[读懂一个请求的完整链路]
+    F --> G[照着 example 模块仿写]
+    G --> H[用生成器生成新模块]
+    H --> I[阅读第 3 章模块开发实战]
+
+    style A fill:#e8f5e9
+    style E fill:#e8f5e9
+    style I fill:#fff3e0
+```
+
+## 第一步：跑起来
+
+```sh
+# 1. 导入数据库（MySQL）
+#    库名：easygoadmin.goframe.elevue（注意库名含点）
+mysql -uroot -p easygoadmin.goframe.elevue < document/mysql/easygoadmin.goframe.elevue.sql
+
+# 2. 检查 manifest/config/config.yaml（数据库/Redis 连接信息）
+
+# 3. 启动后端
+go build -o bin/admin-server.exe main.go && ./bin/admin-server.exe
+
+# 4. 启动前端（新终端）
+cd ui && pnpm install && pnpm dev
+```
+
+访问前端页面，使用 **admin / 123456** 登录（超管，角色 `ROLE_SUPER_ADMIN`）。
+
+## 第二步：读懂一个请求的完整链路
+
+以「用户管理 → 列表页」为例，一个 `GET /api/user/page` 请求经过：
+
+```text
+前端 useHttp.get('/user/page')
+  → axios 拦截器（带 Authorization: Bearer xxx）
+    → 中间件链：CORS → Response → RateLimit → Demo → JWT → Tenant → OperationLog
+      → Bind 包装层：读 gmeta 元数据 → HasPerm("sys:user:page") 权限校验
+        → 参数解析（gvalid 校验）→ CUser.Page
+          → service.User().Page
+            → logic.sUser.Page → userSpec.Page（ModuleSpec 流水线）
+              → dao.User.Ctx(ctx)（自动注入 del_flag=0 + tenant_id）
+                → 数据库
+  ← 统一信封 {"code":0,"ok":true,"msg":"操作成功","data":{records:[…],total:…}}
+  ← OperationLog 中间件异步落库（GET 查询默认记录）
+```
+
+建议打断点或加日志逐层跟踪一次，比读十遍文档更有效。
+
+## 第三步：改一个字段感受全流程
+
+以「职级管理」为例，给 `goframe_level` 表加一个 `remark` 备注字段：
+
+```sql
+ALTER TABLE goframe_level ADD COLUMN remark varchar(255) DEFAULT '' COMMENT '备注';
+```
+
+然后：
+
+```sh
+# 刷新 dao（entity/do 同步更新）
+gf gen dao -c hack/config.yaml
+```
+
+手工补齐四处：`api/v1/level.go` 的 Req/Res 结构体加 `Remark` 字段 → `logic/level.go` 的 ToData 加映射 → 前端 `querySchemas.ts`/`edit.vue`/`columns.ts` 加展示项 → `go build ./...` 重启。
+
+这个过程就是日常开发的最小闭环。熟练后大部分此类变更可以用生成器的覆盖模式批量完成。
+
+## 第四步：看懂 example 模块
+
+`internal/logic/example.go` 是官方完整样板，演示了基座的全部常用声明：
+
+ 筛选（LikeFields/EqFields）
+ 字典文本（SerializeMaps → {field}Text）
+ 状态切换（Status 方法）
+ Excel 导入导出（Import/Export + ChunkQuery）
+ 前端五件套（`ui/src/views/tool/example/`：index/edit/detail/columns/querySchemas）
+
+第 3 章模块开发实战全程以它为参照。
+
+## 第五步：跑一遍生成器
+
+用库中真实存在的 `goframe_example` 表练手（命令可直接执行）：
+
+```sh
+# 预览（不落盘，查看将产出的文件与内容）
+go run ./cmd/generator -tables "goframe_example|案例演示表" -preview
+
+# 生成（example 已完整实现——将演示幂等保护：文件全跳过、菜单/字典/路由查重命中）
+go run ./cmd/generator -tables "goframe_example|案例演示表"
+
+go build ./...   # 编译并重启
+```
+
+开发**新模块**时同样命令把表名换成你的表（如 `"goframe_xxx|中文名"`），生成后在「角色管理」为角色勾选新模块的权限节点。登录后在「系统管理 → 代码生成」页面也能操作（Web 界面）。完整实战见 [10.8 实战案例](./generator/demo)。
+
+## 新手常见误区
+
+:::warning 注意
+1. **不要运行 `gf gen service`**——service 接口文件是手工重组维护的，整体运行会覆盖。
+2. **不要绕过 dao 直连 `g.DB()`**——会绕过全局钩子（软删/租户/审计全部失效）。
+3. **不要手写 del_flag/tenant_id 条件**——`dao.{X}.Ctx(ctx)` 已自动注入。
+4. **不要在事务内做 HTTP/文件 IO**——bcrypt 等 CPU 操作也要在事务外预计算。
+5. **前端登录读 `data.access_token`**（下划线命名），这是 OAuth2 惯例例外，勿改驼峰。
+:::
+
+## 常用命令速查
+
+项目根目录执行（Windows 环境无 make，可直接用等价 go/gf 命令；Makefile 提供 run/build/test/vet/fmt/gen/clean 目标供类 Unix 环境使用）：
+
+```sh
+# 编译与运行
+go build ./...                                  # 全量编译
+go build -o bin/admin-server.exe main.go        # 编译产物
+./bin/admin-server.exe                          # 运行（:8000）
+go run main.go                                  # 开发直接运行
+
+# 质量门禁
+go test ./...                                   # 测试（sqlite 集成 + hooks MySQL 集成）
+go vet ./...                                    # 静态检查
+gofmt -l .                                      # 格式检查（无输出=通过）
+
+# 表结构变更后刷新 dao（service 手维护，勿运行 gf gen service）
+gf gen dao -c hack/config.yaml
+
+# 代码生成（文件+菜单+字典+路由，幂等）
+go run ./cmd/generator -tables "goframe_example|案例演示表"              # 一键生成
+go run ./cmd/generator -tables "goframe_example|案例演示表" -preview     # 仅预览
+go run ./cmd/generator -tables "goframe_example|案例演示表" -batch       # 批量统计
+
+# 整库迁移（五方言互迁，含结构+注释+索引+数据+序列）
+go run ./cmd/migrator -src-type=mysql -src-host=127.0.0.1 -src-hostport=3306 \
+  -src-database=easygoadmin.goframe.elevue -src-username=root -src-password=root \
+  -dst-type=pgsql -dst-host=127.0.0.1 -dst-hostport=5432 \
+  -dst-database=easygoadmin.goframe.elevue -dst-username=postgres -dst-password=123456 \
+  -drop-target-first
+```
+
+```sh
+# 前端（ui/ 目录）
+pnpm install          # 安装依赖
+pnpm dev              # 开发服务器
+pnpm build            # 生产构建
+pnpm type:check       # vue-tsc 类型检查
+pnpm lint:eslint      # ESLint 修复
+
+# Windows 重启（端口 8000）
+netstat -ano | findstr ":8000" | findstr LISTENING
+taskkill /F /PID <pid>
+```
+
+## 下一步阅读
+
+ 想快速搭环境：第 2 章「快速入门」
+ 想开发业务模块：第 3 章「模块开发实战」
+ 想理解设计原理：第 4 章「架构设计」
+ 想偷懒用生成器：第 10 章「代码生成器」