csxj2026/junhong_cmp_fiber
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
Files
main
junhong_cmp_fiber/.planning/codebase/STACK.md

7.5 KiB
Raw Permalink Blame History

Technology Stack

Analysis Date: 2026-03-27

Languages

Primary:

  • Go 1.25.x - 应用代码、API、Worker、OpenAPI 生成和基础设施脚本，依据 go.mod、cmd/api/main.go、cmd/worker/main.go、cmd/gendocs/main.go

Secondary:

  • YAML - 配置与部署编排，见 pkg/config/defaults/config.yaml、docker-compose.prod.yml、.gitea/workflows/deploy.yaml
  • Dockerfile - API/Worker 容器构建，见 Dockerfile.api、Dockerfile.worker
  • Makefile - 本地构建、文档生成、迁移命令，见 Makefile

Runtime

Environment:

  • Go runtime；API 服务基于 Fiber HTTP 服务器，见 cmd/api/main.go
  • 独立 Worker 进程处理异步任务与调度，见 cmd/worker/main.go
  • 生产容器基础镜像为 Alpine，构建镜像使用 Go 1.25.6 Alpine，见 Dockerfile.api、Dockerfile.worker

Package Manager:

  • Go Modules，见 go.mod
  • Lockfile: go.sum present

Frameworks

Core:

  • Fiber v2.52.9 - HTTP 框架与路由宿主，见 go.mod、cmd/api/main.go
  • GORM v1.31.1 + gorm.io/driver/postgres v1.6.0 - PostgreSQL ORM 与连接层，见 go.mod、pkg/database/postgres.go
  • Viper v1.21.0 - 嵌入式默认配置 + 环境变量覆盖，见 go.mod、pkg/config/loader.go

Queue / Scheduling:

  • Asynq v0.25.1 - 任务提交、Worker 消费、定时任务，见 go.mod、pkg/queue/client.go、pkg/queue/server.go、cmd/worker/main.go

Serialization / Validation:

  • sonic v1.14.2 - Fiber JSON 编解码与任务载荷序列化，见 go.mod、cmd/api/main.go、pkg/queue/client.go
  • validator/v10 v10.28.0 - DTO 校验依赖，见 go.mod

Logging:

  • zap v1.27.1 - 应用日志与 SQL 日志，见 go.mod、pkg/logger/logger.go、pkg/database/postgres.go
  • lumberjack.v2 v2.2.1 - 日志轮转，见 go.mod、pkg/logger/logger.go

Docs tooling:

  • swaggest/openapi-go v0.2.60 - OpenAPI 3.0.3 文档生成，见 go.mod、pkg/openapi/generator.go

Build / Dev / Deploy

Build:

  • Makefile 定义 build、run、run-worker、docs、migrate-* 目标，见 Makefile
  • API 与 Worker 使用多阶段 Docker 构建，编译产物分别来自 ./cmd/api 与 ./cmd/worker，见 Dockerfile.api、Dockerfile.worker

Deploy:

  • 生产编排使用 Docker Compose，运行 api 与 worker 两个服务，见 docker-compose.prod.yml
  • Gitea Actions 工作流构建镜像、推送私有镜像仓库并在主分支执行 docker compose up -d，见 .gitea/workflows/deploy.yaml

Docs generation:

  • API 启动时会生成 logs/openapi.yaml，见 cmd/api/main.go、cmd/api/docs.go
  • 手动文档命令 make docs 运行 cmd/gendocs/main.go，输出 docs/admin-openapi.yaml，见 Makefile、cmd/gendocs/main.go

Storage, Data, Messaging

Database:

  • PostgreSQL 是唯一检测到的主数据库；连接、连接池、GORM logger、Ping 校验位于 pkg/database/postgres.go

Cache / KV:

  • Redis 用于认证、缓存、队列后端、限流存储和配置缓存，见 pkg/database/redis.go、cmd/api/main.go、internal/service/wechat_config/service.go

Messaging / Queue:

  • Asynq 直接复用 Redis 连接配置作为消息后端，见 pkg/queue/client.go、pkg/queue/server.go
  • Worker 内注册订单超时、告警检查、数据清理等调度任务，见 cmd/worker/main.go

Object storage:

  • S3 兼容对象存储通过 AWS SDK v1 实现，支持上传、下载、预签名 URL、临时文件下载，见 pkg/storage/s3.go、pkg/storage/service.go

Configuration

Loading model:

  • 默认配置从嵌入文件 pkg/config/defaults/config.yaml 读取，见 pkg/config/embedded.go
  • 运行时使用 JUNHONG_ 前缀环境变量覆盖，见 pkg/config/loader.go
  • 必填配置校验包括数据库、Redis、JWT，见 pkg/config/config.go

Key config areas:

  • 服务与超时：server.*，见 pkg/config/config.go
  • PostgreSQL：database.*，见 pkg/config/config.go
  • Redis：redis.*，见 pkg/config/config.go
  • Asynq：queue.*，见 pkg/config/config.go
  • 日志：logging.*，见 pkg/config/config.go
  • 短信：sms.*，见 pkg/config/config.go
  • 对象存储：storage.*，见 pkg/config/config.go
  • 外部 Gateway：gateway.*，见 pkg/config/config.go

WeChat config exception:

  • 微信公众号/小程序/支付配置不走 Viper 主配置，业务侧从数据库表 tb_wechat_config 读取并缓存到 Redis，见 internal/model/wechat_config.go、internal/service/wechat_config/service.go、pkg/wechat/config.go

Logging & Observability

Application logs:

  • pkg/logger/logger.go 初始化 app/access 双 logger；生产模式写 JSON，开发模式 app logger 同时输出控制台

Access logs:

  • pkg/logger/middleware.go 记录 method、path、query、status、duration、request_id、ip、user_agent、user_id、请求/响应 body

SQL logs:

  • pkg/database/postgres.go 自定义 GORM logger，记录错误、慢查询和普通 SQL trace

Health checks:

  • Dockerfile.api 与 docker-compose.prod.yml 均通过 GET /health 做容器健康检查

Notable Dependencies

HTTP / App:

  • github.com/gofiber/fiber/v2 - API 服务核心框架，见 go.mod、cmd/api/main.go
  • github.com/google/uuid - 请求 ID 生成，见 cmd/api/main.go

Persistence / Cache:

  • gorm.io/gorm、gorm.io/driver/postgres - ORM 与 PostgreSQL 驱动，见 go.mod、pkg/database/postgres.go
  • github.com/redis/go-redis/v9 - Redis 客户端，见 go.mod、pkg/database/redis.go

Queue / Async:

  • github.com/hibiken/asynq - 队列与调度器，见 go.mod、pkg/queue/*.go、cmd/worker/main.go

Serialization / File processing:

  • github.com/bytedance/sonic - JSON 编解码，见 cmd/api/main.go、pkg/queue/client.go
  • github.com/xuri/excelize/v2 - Excel 导入处理依赖，见 go.mod; 任务消费方在 internal/task/iot_card_import.go、internal/task/device_import.go 调用 Excel 解析

External SDKs:

  • github.com/ArtisanCloud/PowerWeChat/v3 - 微信公众号与微信支付 SDK，见 go.mod、pkg/wechat/official_account.go、pkg/wechat/payment.go
  • github.com/aws/aws-sdk-go - S3 兼容对象存储客户端，见 go.mod、pkg/storage/s3.go

Platform Requirements

Development:

  • 需要 PostgreSQL、Redis、JWT 密钥与 JUNHONG_ 环境变量；config.Load() 在启动时强校验，见 pkg/config/config.go
  • make docs 需要 Go 环境；migrate-* 目标需要系统安装 migrate 命令，见 Makefile

Production:

  • 目标运行形态是 Docker 化 API + Worker 双进程部署，见 Dockerfile.api、Dockerfile.worker、docker-compose.prod.yml
  • 镜像发布到私有仓库 registry.boss160.cn，见 .gitea/workflows/deploy.yaml

Evidence

  • go.mod
  • README.md
  • cmd/api/main.go
  • cmd/api/docs.go
  • cmd/worker/main.go
  • cmd/gendocs/main.go
  • pkg/config/config.go
  • pkg/config/loader.go
  • pkg/config/embedded.go
  • pkg/config/defaults/config.yaml
  • pkg/database/postgres.go
  • pkg/database/redis.go
  • pkg/queue/client.go
  • pkg/queue/server.go
  • pkg/queue/handler.go
  • pkg/logger/logger.go
  • pkg/logger/middleware.go
  • pkg/openapi/generator.go
  • pkg/openapi/handlers.go
  • pkg/storage/s3.go
  • pkg/storage/service.go
  • pkg/wechat/config.go
  • pkg/wechat/official_account.go
  • pkg/wechat/payment.go
  • pkg/sms/client.go
  • internal/gateway/client.go
  • Makefile
  • Dockerfile.api
  • Dockerfile.worker
  • docker-compose.prod.yml
  • .gitea/workflows/deploy.yaml

Stack analysis: 2026-03-27

Reference in New Issue View Git Blame Copy Permalink