178 lines
7.5 KiB
Markdown
178 lines
7.5 KiB
Markdown
# 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*
|