1.4 新手入门指南
概述
本节面向第一次接触本项目的开发者，给出一条最短路径：跑起来 → 看懂一个请求 → 改一个字段 → 开发一个新模块。全程约 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 实战案例。
新手常见误区
注意
- 不要运行
gf gen service——service 接口文件是手工重组维护的，整体运行会覆盖。 - 不要绕过 dao 直连
g.DB()——会绕过全局钩子（软删/租户/审计全部失效）。 - 不要手写 del_flag/tenant_id 条件——
dao.{X}.Ctx(ctx)已自动注入。 - 不要在事务内做 HTTP/文件 IO——bcrypt 等 CPU 操作也要在事务外预计算。
- 前端登录读
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-firstsh
# 前端（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 章「代码生成器」