64 lines
3.0 KiB
Markdown
64 lines
3.0 KiB
Markdown
# `internal` 目录结构优化结论
|
||
|
||
参考 Go Kratos 的分层方式，顶层保留 `app`、`modules`、`biz`、`config`、`global`、
|
||
`data`、`initialize`、`integration`、`security`、`server`、`service`、`worker` 等
|
||
稳定职责。目录不是越少越好：同一技术角色文件较多时，应在所属层下分组，避免
|
||
一个目录堆积几十个文件。
|
||
|
||
## 当前结构
|
||
|
||
```text
|
||
internal/
|
||
app/ # 应用组合根
|
||
modules/ # 静态 catalog 和模块定义
|
||
modules/payment/ # payment 模块定义
|
||
biz/ # DO、usecase、repo interface
|
||
config/ # Viper 配置、快照和热更新
|
||
global/ # 进程级共享资源
|
||
data/ # PO、repo、数据库和迁移
|
||
initialize/ # 首次安装和配置编排
|
||
integration/ # 外部 I/O provider
|
||
security/ # JWT 和安全实现
|
||
server/
|
||
handler/ # Gin handler，按资源命名
|
||
middleware/ # 认证、审计、限流、恢复等中间件
|
||
router/ # 各资源路由及 Routes 聚合
|
||
httpx/ # system HTTP 响应和 cookie 适配
|
||
service/
|
||
dto/ # HTTP 请求、响应和查询 DTO，按模块命名
|
||
worker/ # 任务运行时
|
||
```
|
||
|
||
## 本次调整
|
||
|
||
- DTO 从 `service` 根目录归档到 `service/dto`。
|
||
- handler、middleware、router、HTTP helper 分别归档到 `server` 子包。
|
||
- 子目录内文件直接使用资源名，例如 `handler/payment.go`、
|
||
`router/payment.go`、`dto/payment.go`，不保留重复角色前缀。
|
||
- Wire 直接装配 `handler.ProviderSet` 和 `router.ProviderSet`，server 根目录只
|
||
负责 Gin/Swagger 生命周期。
|
||
- `security/adminauth/token.go` 合并为 `security/token.go`；单文件子包没有
|
||
独立边界时不继续拆分。
|
||
- 删除只转发 `pkg/protoutil` 的 `utils/configutil`。
|
||
|
||
## `internal/app` 为什么只保留应用组合
|
||
|
||
`modules/catalog.go` 是静态模块注册点，负责按依赖顺序汇总各模块
|
||
`Definition()`；`app/runtime.go` 只负责任务注册和依赖注入后的路由组合。
|
||
这样模块定义不再和应用组合逻辑混在一起，也不能误并入 `biz`、`service` 或
|
||
`data`。
|
||
|
||
Catalog 只能自动汇总静态模块贡献；新增模块若提供运行时路由或依赖型任务，仍需
|
||
在 cmd/Wire 中显式注册。
|
||
|
||
## 其他目录审查
|
||
|
||
- `data` 与 `integration` 已按仓储或 provider 分类，边界和生命周期明确。
|
||
- `biz`、`service` 根目录采用一资源一文件；进一步拆成资源子包会改变 Go 包
|
||
边界并容易引入循环依赖，本次不做纯视觉拆分。
|
||
- `security` 当前只有一个文件，但安全实现是明确的依赖边界，后续认证机制也会
|
||
在此扩展，因此保留顶层包。
|
||
|
||
新增目录应至少满足独立依赖方向、状态生命周期或稳定技术角色之一。不要回到
|
||
一文件一目录，也不要为了减少目录数量把大量不同角色重新铺平。
|