82 lines
4.4 KiB
Markdown
82 lines
4.4 KiB
Markdown
# `` 到 `pkg` 复用性审查
|
||
|
||
审查原则：公共包只提供跨模块稳定的机制、协议或无状态纯函数；不能依赖
|
||
`app/*/internal`，也不承载 system 的业务表、用例、provider 客户端或运行时
|
||
配置。
|
||
|
||
## 已抽取到 `pkg`
|
||
|
||
| 能力 | 公共位置 | 说明 |
|
||
| --- | --- | --- |
|
||
| HTTP JSON 响应契约 | `pkg/httpx` | `Response`、`PageResult`、状态码和 Gin 响应助手；`server/httpx/response.go` 仅保留 system 适配。 |
|
||
| protobuf JSON 局部合并 | `pkg/protoutil` | 与业务无关的字段归一化和局部反序列化；初始化直接使用公共包。 |
|
||
| 支付 provider/mode 标识 | `pkg/paymentkit` | provider 常量、支持列表、金额/签名/JSON 等跨模块协议；`biz/payment` 与 `biz/integration` 直接复用。 |
|
||
| 支付回调 ACK | `pkg/paymentkit` | 回调应答、失败包装和默认 provider 应答；具体渠道 SDK 留在 `internal/integration/payment`。 |
|
||
| WebSocket 通用收发 | `pkg/websocket` | Melody 的连接、事件、点对点发送、广播和会话查询封装；`internal/integration` 管理配置与生命周期。 |
|
||
| 消息队列 | `pkg/mq` | Broker 无关的发布、订阅、JSON 和 QoS 接口；EMQX/Paho 与 RabbitMQ/AMQP 客户端由 `internal/integration` 管理。 |
|
||
| 模块、任务和迁移协议 | `pkg/module`、`pkg/task`、`pkg/database/migration` | 供不同业务模块注册贡献，不带 system 业务语义。 |
|
||
|
||
## system 内部保留边界
|
||
|
||
- `app`：组合根，汇总各模块的迁移、菜单、路由和任务贡献。
|
||
- `modules/system`：system 模块的 Definition，声明迁移、管理面和默认任务。
|
||
- `modules/payment`：payment 模块的 Definition，声明支付迁移和支付管理面。
|
||
- `biz/system`：用户、权限、菜单、审计、媒体和系统配置等系统领域模型与用例。
|
||
- `biz/payment`：支付订单、支付流程、支付接口和支付日志。
|
||
- `biz/integration`：支付/消息队列/WebSocket 集成配置定义与校验。
|
||
- `biz/task`：定时任务模型、任务用例和任务注册协议。
|
||
- `conf`：system 配置 proto、运行时快照和生成代码。
|
||
- `data`：数据库连接、PO、仓储、system 表、支付持久化和配置 watcher。
|
||
- `initialize`：首次安装、配置迁移、种子编排和运行时重载。
|
||
- `integration`：Redis、邮件、存储、支付、WebSocket、EMQX 和 RabbitMQ 的 provider 生命周期。
|
||
- `security`：JWT claims、签发/解析和后台安全实现。
|
||
- `routecatalog`：HTTP 公开性、操作审计、请求体策略和 API 分组/说明的统一目录。
|
||
- `service`：HTTP DTO（`service/dto`）、DTO 与 DO 转换和应用服务。
|
||
- `server`：Gin 生命周期；handler、middleware、router、HTTP 适配按子包维护。
|
||
- `worker`：任务调度、执行器、SSE 订阅及其并发状态。
|
||
|
||
这些代码都带有 system 的 API、配置、数据表或生命周期语义，不应为了减少
|
||
文件数量搬到 `pkg`。
|
||
|
||
## 目录分类约定
|
||
|
||
```text
|
||
internal/
|
||
app/ # 组合根和 catalog
|
||
modules/ # 业务模块定义及其模块级贡献
|
||
biz/
|
||
system/ # 系统领域
|
||
payment/ # 支付领域
|
||
integration/# 集成配置领域
|
||
task/ # 定时任务领域
|
||
conf/ # 配置 proto/runtime
|
||
data/ # PO、repo、数据库和迁移
|
||
initialize/ # 首次安装和配置编排
|
||
integration/ # 外部 I/O provider
|
||
security/ # JWT 和安全实现
|
||
server/ # Gin 生命周期，内部按 handler/middleware/router/httpx 分类
|
||
service/ # 应用服务；DTO 集中在 dto 子包
|
||
worker/ # 任务运行时
|
||
```
|
||
|
||
技术角色使用子目录表达，子目录内部使用资源名，例如 `handler/payment.go`、
|
||
`router/payment.go`、`dto/payment.go`。只有少量代码且没有独立边界时不建立
|
||
新包；同一角色文件较多时也不应全部堆在父目录。
|
||
|
||
## 暂不抽取的候选
|
||
|
||
1. token cookie 名称、SameSite 和反向代理策略：目前是 system 认证策略。
|
||
2. operation-audit 脱敏和请求采集：包含 system context key 与审计字段。
|
||
3. biz 查询选项和错误：当前绑定 system 的领域接口及 API reason。
|
||
|
||
只有当其他模块出现相同、稳定且不带 system 语义的契约时，才新增公共包；不要
|
||
直接把单个 system 类型搬到 `pkg`。
|
||
|
||
## 验证
|
||
|
||
```text
|
||
go test ./...
|
||
```
|
||
|
||
当前全仓测试通过，且未发现对已删除旧路径的 Go import。
|