86 lines
5.7 KiB
Markdown
86 lines
5.7 KiB
Markdown
# Kra 分层与结构优化计划
|
||
|
||
## 1. 目标与约束
|
||
|
||
本轮优化以现有 Kratos 分层契约为准，不改变 GVA 兼容接口的请求、响应、
|
||
事务和错误语义。目标是收紧 DTO/DO/PO 边界、降低单文件职责密度，并删除
|
||
确认未接入的代码；不按业务资源重建整套子包，也不创建泛化 `utils`。
|
||
|
||
结构决策遵循以下规则：
|
||
|
||
1. DTO 及 JSON/form/binding tag 只放在 `internal/service/dto`。
|
||
2. DO、usecase、repo interface 和领域上下文保留在 `internal/biz`。
|
||
3. PO、GORM/Casbin/缓存/文件存储等实现保留在 `internal/data`。
|
||
4. HTTP 绑定、路由和中间件保留在 `internal/server`；DTO -> DO 转换交给 service。
|
||
5. 只有无业务状态、至少有两个稳定消费者的能力才建立专用 `internal/<name>` 包。
|
||
6. 同包拆文件优先于新建 Go 子包，避免扩大导出面和破坏 Wire/事务协作。
|
||
|
||
## 2. 总体结论
|
||
|
||
静态依赖扫描未发现四层之间的硬性反向 import：`biz` 不依赖 data/service/server，
|
||
`data` 不依赖 service/server/DTO，`service` 不依赖 data/server，`server` 不依赖
|
||
data。当前架构无需推倒重建，重点应放在文件职责和边界收紧。
|
||
|
||
不建议新增 `pkg/utils`。现有 `pkg/adminauth`、`pkg/logging` 已有清晰复用价值；
|
||
其他应用专属能力应留在 `internal`，防止把内部实现误扩成公共 API。
|
||
|
||
## 3. 按模块审查与执行计划
|
||
|
||
| 模块 | 当前判断 | 本轮动作 | 后续动作 |
|
||
| --- | --- | --- | --- |
|
||
| 登录与会话 | `LoginResult` 是传输响应，却位于 service 根包 | 移入 `service/dto` | `TokenAuthentication/AuthClaims` 仍跨到 middleware，待专门设计 service 视图后再收口 |
|
||
| 用户 | handler 构造导出的 `service.UserInput`，边界不够明确 | 将输入模型私有化，新增 DTO request 方法 | `data/user.go` 按 read/write/relations 同包拆分 |
|
||
| API/Casbin | `data/api.go` 混合目录 CRUD、策略和同步 | 同包拆为 `api.go`、`api_policy.go`、`api_sync.go` | 继续保留 `casbin.go` 作为共享持久化辅助，不建 data 子包 |
|
||
| 初始化 | `DatabaseInit` 带 binding tag，却位于 service 根包 | 移入 `service/dto` | 初始化事务和 seed 保持在 data，不拆独立 package |
|
||
| 路由目录/Swagger | 路由分组表由 service 和 server 共同使用 | 抽到无状态的 `internal/routeinfo` | 后续评估与 operation-audit 路由目录合并，避免一次性大改 |
|
||
| 字典 | handler 直接构造 `biz.DictionaryDetailFilter` | 增加 service request 转换入口 | DTO 文件可在自然增长时再按资源拆分 |
|
||
| 媒体 | handler 直接构造 `biz.MediaFilter` | 增加 service request 转换入口 | `MediaConfig` 的 biz 类型暴露可在配置 DTO 整理时一并处理 |
|
||
| 审计/导出 | `page`、`IDsFromQuery` 放在 `audit.go`，但被多个 handler 使用 | 移到 `handler/query.go`，删除未引用 `queryUintValue` | 审计错误映射保留在 handler，它属于 HTTP 展示语义 |
|
||
| 权限/组织 | data 文件较大，但 PO、事务和权限检查高度协作 | 本轮保持行为不动 | `authority.go` 同包拆 CRUD/relations/data-scope；`system.go` 改为更明确的 identity model/constructor 文件 |
|
||
| 配置/热更新 | compat、merge、store、watch、bootstrap 已形成职责组 | 保持现状 | 仅在单文件继续增长时同包拆分，不创建 `internal/data/config` 子包 |
|
||
| 系统指标 | service 直接调用 gopsutil，属于基础设施实现 | 本轮不动，避免扩大改动面 | 建立 biz provider interface，由 data 实现指标采集，service 只转 DTO |
|
||
| 定时任务 | biz 中存在全局可变 registry，worker 负责具体注册 | 本轮不动 | 中期改为向 `TaskUsecase` 注入方法目录；仍不放入 pkg |
|
||
| 公共包 | `pkg/validate` 无任何调用，未接入 Gin/Kratos 链路 | 删除 `pkg/validate` | `biz/pagination.go` 按仓库分层契约保留，不因当前调用少而删除 |
|
||
|
||
## 4. data 层拆分边界
|
||
|
||
### 已执行：API/Casbin
|
||
|
||
- `api.go`：repo 构造、PO、转换、API CRUD 与列表。
|
||
- `api_policy.go`：角色关联、授权判断、policy path 查询与替换。
|
||
- `api_sync.go`：ignore API 与 API registry 同步。
|
||
- `casbin.go`：继续保存跨 repo 使用的 Casbin rule 和数据库辅助函数。
|
||
|
||
这些文件仍为同一个 `package data`，PO 和事务辅助无需导出。
|
||
|
||
### 后续：身份与权限
|
||
|
||
建议在后续单独变更中完成，避免与接口兼容整改混在一起：
|
||
|
||
- `user.go` 拆为读取/装载、写入、用户关系三个文件；
|
||
- `authority.go` 拆为角色 CRUD/用户关系和 strict-auth/data-scope；
|
||
- `system.go` 中共享 PO 与 repo 构造器改用能表达 identity 职责的文件名；
|
||
- 不把 user/authority/menu PO 移到公共 model 包。
|
||
|
||
## 5. 测试文件处理
|
||
|
||
本轮不按文件数量删除测试。现有测试主要保护 GVA 兼容语义、事务原子性、
|
||
Casbin/数据权限、安全、迁移、路由契约、日志路径和调度器行为，删除收益小于
|
||
回归风险。
|
||
|
||
可以在后续纯测试整理中做两类无损合并：
|
||
|
||
- 将少量 service 转换测试合并为按资源命名的 conversion 测试文件；
|
||
- 先用覆盖率确认部门树重复断言，再删除真正被更完整用例覆盖的函数。
|
||
|
||
`transactions_test.go`、`gin_test.go`、认证/安全、策略/数据权限、日志文件、
|
||
任务执行器和初始化 ignore 测试必须保留。
|
||
|
||
## 6. 验收
|
||
|
||
1. `gofmt` 覆盖全部修改的 Go 文件。
|
||
2. `go test ./...` 使用仓库内可写 `GOCACHE` 执行。
|
||
3. 结构调整后重新扫描层间 import 和已删除符号引用。
|
||
4. 任何全量测试失败都区分为本轮回归或已有环境/资源清理问题。
|
||
5. 不修改生成文件，不改变 Wire provider、路由数量或外部 JSON 字段。
|