chore: import 分组规范 + 文档同步 + config 修复

2026-06-15 16:52:20 +08:00
parent 7d1c78f965
commit b23a169925
32 changed files with 143 additions and 90 deletions
--- a/README.md
+++ b/README.md
@@ -33,21 +33,32 @@

 ```
 backend/
-├── cmd/server/            # 应用入口（main.go）
+├── cmd/server/                # 应用入口（main.go：极简 fx 装配）
 ├── internal/
-│   ├── handler/           # HTTP Handler 与 Swagger 注解
-│   ├── service/           # 业务逻辑
-│   ├── repository/        # 数据访问
-│   ├── model/             # GORM 数据模型
-│   ├── types/             # 请求/响应 DTO
-│   ├── middleware/        # Gin 中间件
-│   └── task/              # 定时任务与后台作业
-├── pkg/                   # 可复用组件（config、database、auth、logger、redis、storage 等）
-├── docs/                  # swagger 生成产物（docs.go / swagger.json / swagger.yaml）
-├── start.sh               # 启动脚本（自动 swag init）
-├── docker-compose.yml     # 本地容器编排
-├── .env.example           # 环境变量示例
-└── go.mod                 # Go Module 定义
+│   ├── app/                   # uber-go/fx 装配层（唯一依赖注入入口）
+│   │   ├── module.go          # 聚合根 Module
+│   │   ├── infra_module.go    # Logger/DB/Redis/Storage/Email/JWT/Casbin + Lifecycle
+│   │   ├── container_module.go # Container 聚合 + 路由/HTTP/任务生命周期
+│   │   ├── repository_module.go # Repository Provider（占位，Container 模式暂未启用）
+│   │   ├── service_module.go   # Service Provider（占位）
+│   │   ├── handler_module.go   # Handler Provider（占位）
+│   │   ├── server_module.go    # HTTP 服务器模块（占位）
+│   │   └── task_module.go      # 后台任务模块（占位）
+│   ├── container/             # 过渡期手动 DI 容器（fx 迁移期的聚合层）
+│   ├── handler/              # HTTP Handler 与 Swagger 注解
+│   ├── service/              # 业务逻辑（接口 + 实现）
+│   ├── repository/           # 数据访问（接口 + GORM 实现）
+│   ├── model/                # GORM 数据模型与响应结构
+│   ├── types/                # 请求/响应 DTO
+│   ├── errors/               # 统一错误定义（apperrors）
+│   ├── middleware/           # Gin 中间件
+│   └── task/                 # 定时任务与后台作业
+├── pkg/                      # 可复用组件（config、database、auth、logger、redis、storage、email、utils）
+├── docs/                     # swagger 生成产物（docs.go / swagger.json / swagger.yaml）
+├── start.sh                  # 启动脚本（自动 swag init）
+├── docker-compose.yml        # 本地容器编排
+├── .env.example              # 环境变量示例
+└── go.mod                    # Go Module 定义
 ```

 ## ✅ 前置要求
@@ -113,6 +124,9 @@ backend/
 | `JWT_SECRET` | JWT 签名密钥 | `change-me` |
 | `EMAIL_ENABLED` | 是否开启邮件服务 | `true` |
 | `EMAIL_SMTP_HOST` / `EMAIL_SMTP_PORT` | SMTP 配置 | `smtp.example.com` / `587` |
+| `ENVIRONMENT` | 应用环境（用于 service 层 `IsTestEnvironment()` 短路） | `production` |
+| `SECURITY_ALLOWED_ORIGINS` | CORS 允许的来源（逗号分隔） | `*` |
+| `SECURITY_ALLOWED_DOMAINS` | 头像/材质 URL 允许的域名（逗号分隔） | `localhost,127.0.0.1` |

 更多变量请参考 `.env.example` 与 `.env.docker.example`。

@@ -132,11 +146,21 @@ golangci-lint run (若已安装)

 ## 🧱 架构说明

- **分层设计**：Handler -> Service -> Repository -> Model，层次清晰、职责单一。
- **依赖管理器**：`pkg/*/manager.go` 使用 `sync.Once` 实现线程安全单例（DB / Redis / Logger / Storage / Email / Auth / Config）。
+- **分层设计**：Handler → Service → Repository → Model，层次清晰、职责单一。
+  - Handler 不得直连 `*gorm.DB` 或 `*Repository`，必须通过 Service。
+  - Service 不得持有 `*gorm.DB`，所有数据访问通过 Repository 接口。
+- **依赖注入（uber-go/fx）**：
+  - `internal/app/` 是唯一的依赖装配入口。每个基础设施 / 仓储 / 服务作为 `fx.Provider` 注册。
+  - **生命周期管理**：DB / Redis / Storage / Logger / HTTP Server / Task Runner 通过 `fx.Lifecycle` 的 `OnStart` / `OnStop` Hook 统一管理，彻底替代散落在 `main()` 的 `defer Close()` 链。
+  - **优雅关闭**：`fx.New(app.Module(cfg)).Run()` 监听 `SIGINT` / `SIGTERM`，按依赖逆序触发 `OnStop`，先关 HTTP Server（30s 超时），再关 Task Runner，最后关 DB/Redis。
+  - **Dev/Test 自动回退**：Redis 连接失败且环境为 `development` / `test` / `dev` / `USE_MINIREDIS=true` 时自动启用 `miniredis`。
+  - **启动时错误检查**：循环依赖、缺失 Provider、Provider 返回 error 全部在 `fx.New()` 阶段立即检测。
+- **错误与响应统一**：
+  - 错误统一在 `internal/errors/`（别名 `apperrors`），通过 `errors.Is/As` 匹配。
+  - 响应统一使用 `model.Response` / `model.PaginationResponse` / `model.NewErrorResponse`。
+  - Middleware 错误响应也走 `model.NewErrorResponse`，不再使用裸 `gin.H`。
+- **配置优先级**：`config.Load()` 读取 `.env` → 环境变量 → viper 默认值；`*config.Config` 由 `fx.Supply` 注入。
 - **Swagger 注解**：所有 Handler、模型、DTO 均补齐 `@Summary` / `@Description` / `@Success`，可直接生成 OpenAPI 文档。
- **配置优先级**：`.env` -> 系统环境变量，所有配置均可通过容器注入。
- **自动任务**：`internal/task` 承载后台作业，可按需扩展。

 ## 📝 Swagger 说明