183 lines
5.1 KiB
Markdown
183 lines
5.1 KiB
Markdown
# chatapp3-golang
|
||
|
||
## 现在的结构
|
||
|
||
项目已经从平铺结构调整为按模块组织，并把运行职责拆成了 `api` 与 `consumer` 两个入口：
|
||
|
||
```text
|
||
cmd/api
|
||
cmd/consumer
|
||
internal/bootstrap
|
||
internal/common
|
||
internal/config
|
||
internal/integration
|
||
internal/model
|
||
internal/repo
|
||
internal/router
|
||
internal/service/baishun
|
||
internal/service/invite
|
||
internal/service/luckygift
|
||
internal/service/registerreward
|
||
internal/service/weekstar
|
||
internal/utils
|
||
```
|
||
|
||
每个业务模块都已经拆成独立目录，router 也改成模块化注册，不再把所有处理器和平铺 service 混在一起。`weekstar` 的自动结算、自动发奖和失败补发执行已经迁到 `chatapp-cron`，当前仓库只保留 API、实时积分消费、查询和失败补发任务投递能力。
|
||
|
||
## 分层说明
|
||
|
||
### 1. `cmd/api`
|
||
- 只做启动和依赖装配。
|
||
- 不承担业务逻辑。
|
||
- 当前线上只部署 `golang` API 进程，所以这里会同时启动 `registerreward` 的 Redis Stream consumer 和 `weekstar` 的 RocketMQ consumer，确保注册成功与周星送礼事件能被消费。
|
||
- 不启动任何 `weekstar` 结算 goroutine。
|
||
|
||
### 2. `cmd/consumer`
|
||
- 只做事件消费任务启动和优雅退出。
|
||
- 当前承接：
|
||
- `registerreward` 的 Redis Stream 消费
|
||
- `weekstar` 的 RocketMQ 消费
|
||
- 如果后续单独部署 consumer，`registerreward` 使用同一个 Redis consumer group，重复启动不会重复发奖。
|
||
|
||
### 3. `internal/bootstrap`
|
||
- 统一完成配置加载、存储初始化、依赖探活、Java 网关装配。
|
||
- `cmd/api` 与 `cmd/consumer` 共用这层，避免两份入口各自维护初始化逻辑。
|
||
|
||
### 4. `internal/router`
|
||
- 路由按模块拆分。
|
||
- `router.go` 只负责创建 Gin Engine 和统一挂载模块路由。
|
||
- `invite_routes.go`、`week_star_routes.go`、`baishun_routes.go`、`lucky_gift_routes.go` 分别负责各自模块。
|
||
- `middleware.go`、`response.go` 放公共中间件和统一响应。
|
||
|
||
### 5. `internal/service/<module>`
|
||
- 每个业务模块一个目录，避免所有逻辑堆在同一个 `service` 包里。
|
||
- `types.go` 只放服务结构、常量、DTO、内部类型。
|
||
- 业务层只依赖模块自己的 DB/Redis/gateway ports，不再直接依赖大一统 `repo.Repository` 或 `integration.Client`。
|
||
- 业务流程按职责继续拆文件，例如：
|
||
- `weekstar/config.go`
|
||
- `weekstar/page.go`
|
||
- `weekstar/reward_retry.go`
|
||
- `registerreward/consumer.go`
|
||
- `baishun/callback.go`
|
||
- `invite/recharge.go`
|
||
- 当前模块：
|
||
- `invite`
|
||
- `baishun`
|
||
- `luckygift`
|
||
- `registerreward`
|
||
- `weekstar`
|
||
|
||
### 6. `internal/common`
|
||
- 放跨模块共享结构。
|
||
- 当前包含：
|
||
- `AppError`
|
||
- `AuthUser`
|
||
|
||
### 7. `internal/utils`
|
||
- 放跨模块通用工具。
|
||
- 当前保留雪花 ID 生成器。
|
||
|
||
### 8. `internal/model`
|
||
- 只放表结构映射，不再维护跨模块大文件。
|
||
- 当前已经按模块拆分：
|
||
- `common_models.go`
|
||
- `invite_models.go`
|
||
- `registerreward_models.go`
|
||
- `weekstar_models.go`
|
||
- `luckygift_models.go`
|
||
- `baishun_models.go`
|
||
|
||
### 9. `internal/integration`
|
||
- Java 调用已经从单一 `Client` 继续下沉为多个职责网关：
|
||
- `Auth`
|
||
- `Device`
|
||
- `InviteCode`
|
||
- `RewardDispatch`
|
||
- `RewardQuery`
|
||
- `Profile`
|
||
- `Wallet`
|
||
|
||
## 路由装配方式
|
||
|
||
在 `cmd/api/main.go` 里先通过 `bootstrap` 组装基础依赖，再创建 service，通过 `router.Services` 统一注入：
|
||
|
||
```go
|
||
engine := router.NewRouter(app.Config, app.Repository, &app.Gateways, router.Services{
|
||
Invite: inviteService,
|
||
Baishun: baishunService,
|
||
LuckyGift: luckyGiftService,
|
||
WeekStar: weekStarService,
|
||
})
|
||
```
|
||
|
||
这样做的好处是：
|
||
- 入口依赖一眼可见
|
||
- router 不再直接依赖平铺 service 包
|
||
- 后续拆模块时不会改爆主入口
|
||
|
||
## 现在的拆分原则
|
||
|
||
- `router`
|
||
- 一个模块一个路由文件
|
||
- 公共响应、鉴权、中间件单独放公共文件
|
||
- `service`
|
||
- 一个模块一个目录
|
||
- 一个文件只负责一类逻辑
|
||
- 模块内辅助函数使用有语义的文件名，不再新增 `utils.go`
|
||
- `common`
|
||
- 放跨模块共享对象，例如 `AppError`、`AuthUser`
|
||
- `utils`
|
||
- 只放跨模块通用工具，不放业务逻辑
|
||
|
||
## 当前模块文件示例
|
||
|
||
```text
|
||
internal/service/weekstar/
|
||
aliases.go
|
||
config.go
|
||
cycle.go
|
||
event.go
|
||
lifecycle.go
|
||
mapper.go
|
||
page.go
|
||
reward_retry.go
|
||
types.go
|
||
|
||
internal/service/invite/
|
||
bind.go
|
||
home.go
|
||
landing.go
|
||
normalize.go
|
||
recharge.go
|
||
reward.go
|
||
store.go
|
||
task.go
|
||
types.go
|
||
```
|
||
|
||
## 运行职责
|
||
|
||
- `chatapp3-golang`
|
||
- 负责 HTTP API
|
||
- 负责事件消费
|
||
- 负责 `weekstar` 配置、实时榜单、快照/发奖记录查询、失败补发任务投递
|
||
- `chatapp-cron`
|
||
- 是 `weekstar` 周期结算扫描、快照冻结、自动发奖、失败补发执行的唯一执行方
|
||
|
||
因此当前仓库里不要再新增任何 `scheduler`、`settlement loop`、`start settlement worker` 之类的运行职责。
|
||
|
||
## 本地检查
|
||
|
||
```bash
|
||
$(go env GOPATH)/bin/goimports -w cmd internal
|
||
go test ./...
|
||
```
|
||
|
||
如果有结构调整，提交前建议再跑一遍：
|
||
|
||
```bash
|
||
$(go env GOPATH)/bin/goimports -w cmd internal
|
||
gofmt -w cmd internal
|
||
go test ./...
|
||
```
|