mirror of
https://github.com/go-admin-team/go-admin.git
synced 2026-09-22 10:33:13 +00:00
zhangwenjian
1d551a10ab
AGENTS.md 是给 AI 编码工具与新贡献者的约定，只记录「不遵守就会出错」的
规则，技术栈版本与命令交由 go.mod 和 Makefile 表达，避免文档与代码脱节。
标准写法指向 app/demo/——那是可编译、有测试的参照物，文档与它冲突时以它
为准。
docs/architecture.md 承载不易从代码直接读出的语义：DataScope 五档的过滤
方式、定时任务的 JobExec 接口、多数据源约束、迁移目录的分工。
内容整理自此前未纳入版本控制的 CLAUDE.md，撰写时逐条对照代码核实，修正
了其中两处失效描述（构建工具已非 Vue CLI；JobExec 的方法是 Exec(interface{})
而非 Run(string)）。CLAUDE.md 现改为指向 AGENTS.md 的软链，两者不再各自
漂移。
86 lines
3.2 KiB
Markdown
86 lines
3.2 KiB
Markdown
# 架构说明
|
||
|
||
> 本文记录**为什么这样设计**与不易从代码直接读出的语义。
|
||
> 编码规范见根目录 `AGENTS.md`，标准写法见 `app/demo/`。
|
||
|
||
## 数据权限（DataScope）
|
||
|
||
`PermissionAction()` 中间件从数据库取出当前用户的 DataScope 存入 `gin.Context`；
|
||
Service 在查询时通过 `actions.Permission(tableName, p)` 这个 GORM Scope 追加 WHERE。
|
||
|
||
实现见 `common/actions/permission.go:62-79`，五档语义：
|
||
|
||
| 值 | 含义 | 过滤方式 |
|
||
|---|---|---|
|
||
| `1` 或其他 | 全部数据 | 不追加条件 |
|
||
| `2` | 本角色关联部门的数据 | `create_by` 属于 `sys_role_dept` 关联部门下的用户 |
|
||
| `3` | 本部门数据 | `create_by` 属于同部门用户 |
|
||
| `4` | 本部门及子部门 | 按 `sys_dept.dept_path` 前缀匹配 |
|
||
| `5` | 仅本人 | `create_by = 当前用户` |
|
||
|
||
**过滤依据是 `create_by` 字段**，因此参与数据权限的表必须内嵌 `models.ControlBy`。
|
||
|
||
总开关：`config/settings.yml` 的 `application.enabledp`。关闭时 `Permission` 直接返回原
|
||
查询，这也意味着**关闭开关后所有数据权限配置立即失效**，排查问题时先确认此项。
|
||
|
||
## 定时任务
|
||
|
||
两类任务，配置在 `sys_job` 表：
|
||
|
||
- **HTTP 任务** —— 按 Cron 表达式请求指定 URL
|
||
- **函数任务** —— 调用注册在 `app/jobs` 中的 Go 函数
|
||
|
||
自定义函数任务需实现 `JobExec` 接口（`app/jobs/type.go:10`）：
|
||
|
||
```go
|
||
type JobExec interface {
|
||
Exec(arg interface{}) error
|
||
}
|
||
```
|
||
|
||
并注册进 `app/jobs/examples.go` 的 `jobList` 映射，键名与 `sys_job` 表中配置的调用目标
|
||
对应。
|
||
|
||
任务内需要数据库连接时，通过 `sdk.Runtime.GetDbByKey("*")` 获取，不要反向 import
|
||
`app/admin/service`。
|
||
|
||
## 配置扩展
|
||
|
||
业务自定义配置写在 `config/extend.go` 中的结构体，对应 `settings.yml` 的 `extend:`
|
||
节点，代码中通过 `config.ExtConfig.Xxx` 访问。
|
||
|
||
配置值支持环境变量占位：在 yml 中写 `${ENV_NAME}`，由 `go-admin-core` 的
|
||
`config/reader/preprocessor.go` 在加载时替换。敏感信息可借此避免写入文件。
|
||
|
||
## 多数据源
|
||
|
||
`WithContextDb` 中间件按请求解析出对应的数据库连接放入上下文，Service 通过 `e.Orm`
|
||
取用。**不要使用全局 DB 变量** —— 那会绕过多租户隔离。
|
||
|
||
多库配置见 `settings.yml` 的 `databases` 与 `registers` 节点，后者用于 dbresolver
|
||
读写分离。
|
||
|
||
## 数据库迁移
|
||
|
||
迁移文件放 `cmd/migrate/migration/version-local/`，文件名前 13 位为 Unix 毫秒时间戳，
|
||
框架按文件名升序执行，已执行版本记录在 `sys_migration` 表。
|
||
|
||
```bash
|
||
go run main.go migrate -c config/settings.yml -g # 生成骨架
|
||
```
|
||
|
||
**已执行过的迁移文件不可修改** —— 版本号已入表，改动不会重跑。需要调整时新建迁移。
|
||
|
||
## 构建注意
|
||
|
||
- 默认构建禁用 CGO；使用 SQLite 需 `make build-sqlite`（带 `-tags sqlite3`）
|
||
- `mode: prod` 时不注册 Swagger 路由
|
||
- dev 模式下 JWT 超时被设为极大值，生产部署前务必确认 `mode` 与 `jwt.secret`
|
||
|
||
## 参考
|
||
|
||
- 编码规范：根目录 `AGENTS.md`
|
||
- 标准 CRUD 模块：`app/demo/`
|
||
- API 文档：`go generate` 生成到 `docs/admin/`，dev 模式下访问
|
||
`/swagger/admin/index.html`
|