3.0 KiB

Raw Blame History

`internal` 目录结构优化结论

参考 Go Kratos 的分层方式，顶层保留 app、modules、biz、conf、data、 initialize、integration、security、server、service、worker 十个稳定职责。目录不是越少越好：同一技术角色文件较多时，应在所属层下分组，避免一个目录堆积几十个文件。

当前结构

internal/
  app/                 # 运行时组合根
  modules/             # 静态 catalog 和模块定义
  modules/payment/     # payment 模块定义
  biz/                 # DO、usecase、repo interface
  conf/                # 配置 proto/runtime
  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 中显式注册，直到统一的 runtime contribution 协议落地。

其他目录审查

data 与 integration 已按仓储或 provider 分类，边界和生命周期明确。
biz、service 根目录采用一资源一文件；进一步拆成资源子包会改变 Go 包边界并容易引入循环依赖，本次不做纯视觉拆分。
security 当前只有一个文件，但安全实现是明确的依赖边界，后续认证机制也会在此扩展，因此保留顶层包。

新增目录应至少满足独立依赖方向、状态生命周期或稳定技术角色之一。不要回到一文件一目录，也不要为了减少目录数量把大量不同角色重新铺平。

3.0 KiB Raw Blame History Unescape Escape

internal 目录结构优化结论