171 lines
6.7 KiB
Markdown
171 lines
6.7 KiB
Markdown
# 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 章「代码生成器」
|