4.8 KiB

Raw Blame History

`` 到 `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：静态模块 catalog，汇总各模块迁移、菜单、API 和默认任务。
modules/system：system 模块的 Definition，声明系统表迁移。
modules/integration：integration 配置迁移和管理面贡献。
modules/task：定时任务迁移和默认任务贡献。
modules/payment：payment 模块的 Definition，声明支付迁移和支付管理面。
biz/system：用户、权限、菜单、审计、媒体和系统配置等系统领域模型与用例。
biz/payment：支付订单、支付流程、支付接口和支付日志。
biz/integration：支付/消息队列/WebSocket 集成配置定义与校验。
biz/task：定时任务模型、任务用例和任务注册协议。
conf：system 配置 proto、运行时快照和生成代码。
data：共享数据库生命周期与配置 watcher；PO/仓储按 system、integration、task、payment 子包隔离。
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。

目录分类约定

internal/
  app/          # 应用组合根
  modules/      # 静态 catalog、业务模块定义及其模块级贡献
  biz/
    system/     # 系统领域
    payment/    # 支付领域
    integration/# 集成配置领域
    task/       # 定时任务领域
  config/       # Viper 配置、快照和热更新
  global/       # 进程级共享资源入口
  data/
    system/     # 系统表与系统仓储
    integration/# 集成配置表与仓储
    task/       # 定时任务表与仓储
    payment/    # 支付表与仓储
  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。只有少量代码且没有独立边界时不建立新包；同一角色文件较多时也不应全部堆在父目录。

暂不抽取的候选

token cookie 名称、SameSite 和反向代理策略：目前是 system 认证策略。
operation-audit 脱敏和请求采集：包含 system context key 与审计字段。
biz 查询选项和错误：当前绑定 system 的领域接口及 API reason。

只有当其他模块出现相同、稳定且不带 system 语义的契约时，才新增公共包；不要直接把单个 system 类型搬到 pkg。

验证

go test ./...

当前全仓测试通过，且未发现对已删除旧路径的 Go import。

4.8 KiB Raw Blame History Unescape Escape

`` 到 pkg 复用性审查

已抽取到 pkg