FranklinWH-Toolbox/service

FranklinWH Toolbox Service

Go 后端服务，整合了：

• Fiber（Web 框架）
• GORM（ORM）
• Swagger（接口文档）
• 缓存（Redis）
• 任务 + 定时器（Cron）
• 日志（Zap 或 Logrus）
• 配置管理（Viper）

📁 项目结构

├── cmd/
│    └── main.go
├── config/             # 配置
│    └── config.go
├── cache/              # 缓存封装（Redis）
├── database/
│    └── database.go    # GORM 初始化
├── logger/
│    └── logger.go
├── scheduler/          # 任务调度
│    └── scheduler.go
├── routes/
│    └── routes.go      # Fiber 路由 & swagger
├── controllers/        # 控制器
├── models/             # GORM 模型，数据结构定义（实体、DTO）
├── services/           # 业务逻辑（核心）
├── middleware/         # 中间件 (鉴权 / 日志 / 限流 / 恢复 panic)
├── repositories/       # 数据访问层（DB/Cache/外部 API）
├── dto/                # 请求/响应 DTO (Data Transfer Object)
├── domain/             # 领域对象 Domain Model
├── utils/              # 工具函数
├── pkg/                # 自定义通用包
├── docs/               # Swagger 文档
├── .env                # 环境变量
├── go.mod
└── go.sum

♻️ 项目标准访问流

Notes:

• 带*为可选历程，可跳过
• 一般情况下不允许跳层级访问

Client (HTTP / gRPC / MQ)

│
▼

Route (Fiber 路由)

│
▼

Middleware* (鉴权 / 日志 / 限流 / 恢复 panic)

│
▼

Controller / Handler (解析请求，调用 service)

│
▼

Service (业务逻辑) ────────────────────────────────────────────┐

│                                                         ▼
│                                          Task (实时任务) / Scheduler (定时任务)
│                                                          │
│                                                          ▼
│                                                        Jobs* (繁琐事务)
▼                                                         

Repository / DAO (数据库 / 缓存 / API) ◀───────────────────────┘

│
▼

Database / Cache (Redis) / 外部服务 (FWH-API)

✅ 项目特点 & 核心依赖

• 配置: Viper（加载 .env、支持环境变量）
• ORM: GORM — 数据库操作 + AutoMigrate 自动建表
• 缓存: Redis（Go‑redis 客户端）
• 定时任务: robfig/cron
• 日志: Zap（结构化日志）
• 文档: swaggo + swagger UI 自动生成 Swagger 文档
• 任务调度: Cron 支持定时和任务计划

📌 源模板参考

• alpody/golang-fiber-realworld-example-app 项目提供了 Fiber + GORM + Swagger 等完整的实战案例
• Fiber 官方 recipes/gorm-example 示例展示了 GORM 和 Fiber 的集成方式

⚙️ 配置说明

项目可通过环境变量配置文件对软件的功能进行配置，配置文件支持的路径如下（读取优先级与路径列出顺序一致）：

• "./.env"
• "./config.env"

| 变量名 | 说明 | | - | --- | | APP_ENV | 运行环境，可选项："pro" - 生产环境、"dev" - 开发环境，默认"DEV" | | APP_PORT | 服务监听端口号，默认"8301" | | MYSQL_DSN | MYSQL数据库连接配置，DSN格式，连接FWH服务器的home_energy_storage_server数据库，用于查询站点信息。 | | POSTGRES_DSN | PGSQL数据库连接配置，DSN格式，本地保存数据信息。 | | MONGO_DSN | MONGO数据库连接配置，DSN格式，本地保存数据信息。 | | REDIS_ADDR | REDIS本地缓存服务器的域名或IP地址，默认"localhost" |