mirror of https://github.com/go-admin-team/go-admin.git synced 2026-09-21 18:20:50 +00:00

Files

T

zhangwenjian 1d551a10ab docs📝: 新增 AGENTS.md 与架构说明

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 的软链，两者不再各自
漂移。

2026-08-14 16:49:48 +08:00

3.2 KiB

Raw Blame History

架构说明

本文记录为什么这样设计与不易从代码直接读出的语义。编码规范见根目录 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）：

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 表。

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

3.2 KiB Raw Blame History Unescape Escape