Complug 采用 Monorepo (单仓多模块) 架构,核心目标是实现极致的依赖隔离与能力标准化。

• 绝对解耦:components/(标准层)严禁依赖 contrib/(实现层)。
• 零污染:components/ 模块禁止引入任何非 Go 标准库的第三方依赖。
• 物理隔离:每个子目录必须拥有独立的 go.mod 文件,确保用户可以"按需引入",避免引入无关的三方驱动。

该目录定义各领域的抽象标准(插座标准)。

• 职责:定义 interface、基础数据模型 struct、枚举常量和 Sentinel Errors。
• 约束:
  • 必须包含独立的 go.mod。
  • 文件名规范:api.go (存放接口定义), types.go (存放通用模型)。
  • 禁止包含具体实现逻辑(如连接池管理、协议解析等)。

该目录提供针对第三方库的具体适配实现(插头)。

• 职责:将第三方 SDK(如 Kafka, Redis, GORM)的功能适配到 components 定义的接口上。
• 约束:
  • 目录结构必须与领域对应:/contrib/{domain}/{driver}。
  • 必须包含独立的 go.mod。
  • 开发阶段必须通过 replace 指令引用本地的 components 模块。

• 上下文支持:所有涉及 I/O、网络或耗时操作的方法,第一个参数必须是 context.Context。
• 错误处理:驱动层需负责将三方 SDK 的原始错误包装或转换为 components 定义的标准错误。
• 类型安全:在处理 Payload 数据或数据库 Record 时,优先使用 Go 泛型(Generics)。

• 每个 contrib 模块必须暴露一个 New{Driver}Provider 或 New{Driver}Client 函数。
• 返回类型强制:函数必须返回 components 中定义的 Interface,而非驱动层的具体结构体指针。
  • OK: func NewKafka(...) (queue.Provider, error)
  • Err: func NewKafka(...) *KafkaAdapter

• Go 版本:全项目 Go 版本必须对齐(建议 1.21 及以上)。
• 依赖声明原则:
  • components 模块的依赖树深度应尽可能为 0(仅限标准库)。
  • contrib 模块仅能引用其对应的 components 模块及该驱动必要的三方 SDK。
• 模块路径命名:
  • 核心层:github.com/{org}/complug/components/{domain}
  • 实现层:github.com/{org}/complug/contrib/{domain}/{driver}

# Kafka 适配
go get github.com/alonexy/complug/contrib/queue/kafka@v1.0.7
# RabbitMQ 适配
go get github.com/alonexy/complug/contrib/queue/rabbitmq@v1.0.7
# NATS 适配
go get github.com/alonexy/complug/contrib/queue/nats@v1.0.8
# Protobuf Codec
go get github.com/alonexy/complug/contrib/queue/protobuf@v1.0.7

• 提交粒度:
  • 每次提交必须只覆盖一个明确主题,优先按模块收敛变更。
  • 若仅修改单个模块(例如 contrib/queue/kafka),提交中不得混入其他模块的无关改动。
• 提交信息:
  • 使用 Conventional Commits 风格,例如:feat: add kafka writer defaults、fix: preserve explicit kafka commit semantics。
• 项目级 Tag:
  • 仓库根级别维护整体发布版本,格式为 vX.Y.Z,例如 v1.0.5。
  • 当本次变更需要对外形成统一版本时,必须补齐对应的项目级 Tag。
• 模块级 Tag:
  • 每个可独立引用的 Go 模块都维护自己的发布 Tag,格式为 {module-path}/vX.Y.Z。
  • 例如:
    • components/queue/v1.0.5
    • contrib/queue/kafka/v1.0.5
    • contrib/queue/rabbitmq/v1.0.5
• 统一发版原则:
  • 若本次发布声明为全项目统一版本,则项目级 Tag 与所有已纳入发布体系的模块级 Tag 必须保持一致版本号。
  • 若仅发布单个模块,可只创建对应模块 Tag,但仍需确认是否需要同步补齐项目级 Tag。
• Tag 指向:
  • 项目级 Tag 与本次涉及的模块级 Tag 必须指向同一个已推送的提交。
  • 禁止在未提交或未推送的工作区状态上创建发布 Tag。

当使用 AI 辅助开发时,请严格遵守以下逻辑:

1. 新建组件顺序:先在 components/ 下定义纯接口,并初始化 go.mod;确认无误后,再在 contrib/ 下开发实现。
2. 依赖冲突检查:若 AI 试图在 components/ 中使用 go get 引入第三方包,必须立即中止并报错。
3. Monorepo 自动适配:生成代码时,AI 应自动识别目录深度并正确编写 go.mod 中的 replace 路径(如 ../../components/xxx)。

• 1. 在 components/{domain} 下定义标准接口。
• 2. 在该目录下运行 go mod init。
• 3. 在 contrib/{domain}/{driver} 下创建对应的实现目录。
• 4. 在实现目录下运行 go mod init 并 replace 接口模块。
• 5. 编写适配器逻辑并实现所有接口契约。
• 6. 编写单元测试,确保驱动完全符合接口预期。