Pragmatic Hex Slice

Architecture Introduction

一套专为 Go 后端与 AI 协作设计的渐进式模块化单体架构。

核心原则：模块优先、轻量默认、按需升级、依赖单向、CI 守门。

简单业务采用轻量切片，复杂业务按需升级为六边形切片。以实际业务复杂度决定抽象程度，通过 Go 包边界、公共契约与 CI 约束依赖方向。

架构服务于业务，而不是让业务迁就架构。

1. Directory Tree

以下仅展示架构意图，并非固定模板。禁止机械照搬、提前创建空目录或无用抽象。所有结构按实际需求渐进创建。

myapp/
├── cmd/
│   └── api/
│       └── main.go
│
├── internal/
│   ├── app/
│   │   └── app.go                 # 全局装配、路由挂载
│   │
│   ├── platform/                  # 通用基础设施
│   │   ├── config/
│   │   ├── database/
│   │   ├── logger/
│   │   └── httpx/
│   │
│   ├── user/                      # 轻量切片
│   │   ├── entity.go
│   │   ├── service.go
│   │   ├── service_test.go
│   │   ├── repo_pgx.go
│   │   ├── handler.go
│   │   ├── api.go                 # 按需：公共业务 API
│   │   └── module.go              # 按需：模块装配
│   │
│   └── order/                     # 六边形切片
│       ├── domain/
│       │   ├── order.go
│       │   └── errors.go
│       │
│       ├── application/
│       │   ├── ports.go
│       │   └── create_order.go
│       │
│       ├── adapters/
│       │   ├── http/
│       │   │   ├── handler.go
│       │   │   └── dto.go
│       │   ├── postgres/
│       │   │   └── repo_pgx.go
│       │   └── payment/
│       │       └── stripe.go
│       │
│       ├── api.go
│       └── module.go
│
├── db/
│   └── queries/
├── migrations/
├── tests/
│   └── integration/
├── docs/
│   └── adr/
├── scripts/
│   └── check-architecture/
├── .github/workflows/ci.yml
├── .golangci.yml
├── AGENTS.md
├── Makefile
├── go.mod
└── go.sum

说明：

• app：依赖装配与路由挂载，不承担业务编排。
• platform：通用基础设施，不承载业务语义。
• 轻量切片：单包组织，依靠职责约定保持清晰。
• 六边形切片：通过包边界隔离 Domain、Application、Adapters。
• api.go、module.go：仅在存在实际需求时创建。
• 跨模块公共契约需要更强封装时，按需引入 Go internal 子包或专用公共契约包。

2. AGENTS.md

2.1 模块组织

1. 模块优先：按业务能力组织代码，禁止全局 Controller、Service、Repository 分层。
2. 轻量默认：简单 CRUD 保持单包，不提前创建接口、工厂或六边形目录。
3. 按需升级：复杂业务可局部升级为六边形，不强制整个项目统一分层。
4. 职责明确：
   • Handler：协议解析、参数转换、响应映射。
   • Service/Application：业务规则、用例编排。
   • Domain：核心业务模型与不变量。
   • Repo/Adapter：持久化及外部系统交互。
5. 按需拆包：辅助包必须有明确职责，不因文件数量或代码行数拆分。
6. 保持内聚：优先在业务模块内部完成业务能力，避免无必要的跨模块依赖。

2.2 渐进式架构升级

出现以下情况时，评估升级六边形：

• 存在复杂状态转换或重要业务不变量。
• 业务规则与基础设施明显耦合。
• 存在多个外部依赖或适配器。
• 用例编排、事务及业务职责难以保持清晰。
• 业务核心需要独立于基础设施测试。

升级原则：

1. 优先局部重构，不默认整体升级。
2. 不因文件数量、代码行数或目录规模自动升级。
3. 新增抽象必须有真实消费者和可验证收益。
4. 不强制使用 Repository、Factory、UnitOfWork 等设计模式。
5. 架构升级需说明原因、影响及迁移方案，经批准后实施。

2.3 封装与依赖方向

1. 单向依赖：Domain 不依赖 Application 或 Adapters；Application 不依赖具体基础设施实现。
2. 模块封装：跨模块只能通过批准的公共业务契约调用，禁止访问其他模块内部实现。
3. 物理边界：优先利用 Go 包及 internal 机制实施封装。
4. 最小暴露：仅暴露真实消费者需要的能力。
5. 接口所有权：消费者定义最小接口；没有实际解耦需求时允许直接依赖具体业务类型。
6. 基础设施隔离：Platform 不依赖业务模块。
7. 依赖无环：业务模块依赖图必须为有向无环图。

公共 API 规则

• 无跨模块消费者时，不必创建 api.go 或公共接口。
• api.go 只是代码组织约定，不提供 Go 文件级访问控制。
• 存在跨模块消费者时，必须明确允许访问的业务契约。
• 需要强隔离时，按需调整包结构，使用 Go 原生 internal 边界。
• 拆包必须先检查导入方向，避免产生循环依赖。
• 公共契约优先表达业务能力，不暴露 Repository、Adapter、数据库连接或内部实现类型。

2.4 数据与事务

数据归属

1. 各业务模块拥有自己的数据语义、SQL 和业务不变量。
2. 数据库迁移统一管理，并标记所属模块。
3. Platform 只提供通用数据库能力，不拥有业务数据语义。
4. 跨模块读取优先通过公共业务 API。
5. 只有明确的只读查询、报表场景，经批准后才允许跨模块 SQL JOIN。
6. 禁止未经授权直接修改其他模块拥有的数据。

事务所有权

1. 默认由具体业务操作管理自身事务。
2. 强一致操作由明确的应用用例决定事务边界。
3. 同库跨模块原子操作通过受控事务机制协调。
4. 事务参与者共享事务，但不得擅自提交或回滚上层拥有的事务。
5. Application 不依赖 pgx.Tx、sql.Tx 等具体数据库事务类型。
6. 仅在真实需求出现时引入最小事务协调契约，不提前建设通用 UnitOfWork 框架。
7. 跨模块事务必须通过集成测试验证原子性、回滚及失败行为。

外部系统一致性

• 禁止在数据库事务内执行外部网络调用。
• 跨外部系统操作应根据一致性需求评估 Outbox、幂等、重试与补偿。
• 不强制所有模块使用事件总线。
• 不为简单同步业务调用引入异步消息机制。

2.5 模块通信

约束：

1. 跨模块同步调用允许，但必须遵守公共契约。
2. 模块依赖不得形成循环。
3. 模块不能绕过公共 API 操作其他模块内部实现。
4. 跨模块业务流程由明确的应用用例协调。
5. app.go 仅负责装配，不承担业务流程编排。
6. 不提前创建通用 Workflow、EventBus 或消息抽象。

2.6 AI 协作

1. 最小修改：只修改完成任务必需的代码。
2. 拒绝过度设计：禁止空接口、无用工厂、提前泛化和无依据拆层。
3. 遵循现有结构：优先复用现有模块及约定。
4. 变更审批：模块拆分、目录重组、公共契约变更及架构升级必须先说明并获得批准。
5. 保持兼容：避免不必要的公共 API 及行为变更。
6. 禁止越权：不得为了实现功能绕过依赖边界。
7. 验证诚实：未执行的检查不得声称通过。
8. 禁止规避检查：不得擅自禁用规则、扩大白名单或忽略架构错误。

2.7 测试与 CI

• 单元测试：验证业务规则与不变量。
• 集成测试：验证数据库、Adapter、事务和外部交互。
• 架构测试：验证包边界、模块契约与依赖方向。
• 静态检查：执行项目配置的 golangci-lint。
• 构建检查：验证项目支持的构建条件。
• 架构检查：必须通过 scripts/check-architecture。

规则：

1. 架构检查失败时，CI 必须失败。
2. 依赖解析失败、未知结构及检查器异常必须 Fail Closed。
3. 新增业务模块必须自动纳入架构检查。
4. 新增或修改架构规则必须提供回归测试。
5. 规则变更必须经过审查。
6. 不允许通过忽略错误获得虚假的 CI 通过状态。

3. Dependency Rules

3.1 依赖矩阵

3.2 补充规则

1. 业务模块依赖图不得存在循环。
2. 跨模块访问必须符合显式批准的公共契约规则。
3. 不以导出标识符或 api.go 文件名自动认定公共 API。
4. 装配层允许引用具体实现，但不能将实现泄漏至业务应用层。
5. 架构检查以直接导入关系判断模块边界；传递依赖策略单独定义。
6. Go 包级检查不能识别同包不同文件的业务职责，须通过测试与代码审查补充。
7. 公共业务 API 的变更必须检查实际调用方；对外协议兼容性遵循独立的版本策略。

4. .golangci.yml

基础配置示例：

version: "2"

linters:
  enable:
    - depguard

  settings:
    depguard:
      rules:
        order-domain:
          list-mode: strict
          files:
            - "internal/order/domain/*.go"
            - "internal/order/domain/**/*.go"
          allow:
            - $gostd

配置原则：

1. depguard 主要负责指定包范围内的导入准入。
2. Domain 使用第三方纯逻辑库时，经批准后明确加入白名单。
3. allow 使用包路径前缀或精确匹配，不以 * 表示包路径通配符。
4. 不为不存在的模块创建规则。
5. CI 必须验证配置与固定的 golangci-lint 版本兼容。
6. CI 必须通过合法和非法导入样例验证规则实际生效。
7. 跨模块依赖、架构层级和模块循环由 scripts/check-architecture 检查，避免重复维护完整规则。

此配置仅为 Domain 导入约束示例，不代表完整架构检查。具体文件匹配行为必须在项目中验证。

5. Architecture Check Requirements

scripts/check-architecture 是核心架构防线。

5.1 模块识别

1. 从 go.mod 读取真实模块路径，不得硬编码项目名称。
2. 自动发现现有业务模块。
3. 默认按轻量切片处理。
4. 使用明确的保留层级结构识别六边形切片。
5. 允许轻量模块存在有明确业务职责的辅助包。
6. 混合、冲突或无法分类的结构必须报错。
7. 不要求不存在的模块满足预设目录结构。

5.2 依赖分析

1. 使用 go list -json -deps -test 加载真实包信息。
2. 基于直接导入关系执行架构边界检查。
3. 区分项目包、标准库及第三方依赖。
4. 覆盖生产代码与测试代码。
5. 覆盖项目明确支持的 Build Tags、GOOS、GOARCH 组合。
6. 检查构建与依赖加载错误，不得静默忽略。
7. 正确识别测试产生的包，避免误判。

5.3 边界校验

必须检查：

• Domain 不依赖 Application、Adapters 或未经批准的基础设施。
• Application 不依赖 Adapters 或具体数据库实现。
• Platform 不依赖业务模块。
• App 不绕过模块装配入口访问内部实现。
• 业务模块不越界访问其他模块内部实现。
• 跨模块依赖仅通过批准的公共契约。
• 业务模块依赖图无循环。
• 包级导入循环导致的构建错误不得忽略。

公共契约应通过显式规则识别，不通过文件名或导出标识符推测。

5.4 测试边界

• 生产代码严格遵循架构规则。
• 单元测试默认遵循模块边界。
• 测试专用依赖可以经过明确批准。
• 集成测试可按需访问基础设施和 Adapter。
• 集成测试的必要豁免不得自动扩展至生产代码。
• 未经授权的跨模块内部访问仍然禁止。

5.5 Fail Closed

以下情况必须失败：

1. go list 执行或依赖加载失败。
2. 业务模块结构无法识别。
3. 发现非法依赖或模块循环。
4. 应覆盖的源码或构建条件未被检查。
5. 规则配置无效或检查器执行异常。
6. 必需的规则回归测试失败。

未知结构应报错，但不应将所有合法辅助目录判定为违规。

5.6 诊断输出

每条违规应尽可能包含：

Source: internal/order/application/create_order.go
Target: internal/order/adapters/postgres
Rule:   application-cannot-import-adapters

Reason:
Application must not depend on concrete adapters.

Fix:
Define a minimal dependency contract owned by
the consumer and inject the implementation.

错误信息应明确：

• 违规来源
• 违规目标
• 规则名称
• 失败原因
• 修复建议

6. Architecture Check Tests

6.1 最小回归样例

6.2 检查器实现顺序

阶段一：核心边界

• 自动发现业务模块。
• 检查 Platform 依赖。
• 检查模块越界。
• 检查模块依赖循环。
• 验证 Fail Closed。

阶段二：六边形约束

• Domain 依赖限制。
• Application 依赖限制。
• Adapters 依赖方向。
• 混合结构识别。

阶段三：完整验证

• 显式公共契约校验。
• 测试包分类。
• Build Tags 与目标平台矩阵。
• 违规样例与规则覆盖验证。
• 清晰诊断输出。

每个阶段启用的规则都必须有对应回归测试。未实现的规则不得声称已被 CI 强制保证。

7. Final Principles

Pragmatic Hex Slice 遵循以下最终准则：

1. 业务优先：以业务能力组织模块，而非技术分层。
2. 轻量默认：简单业务不承担无意义的抽象成本。
3. 复杂隔离：复杂业务通过物理包边界保护核心规则。
4. 单向依赖：跨模块通过明确契约协作，依赖图保持无环。
5. 数据自治：模块拥有自身数据语义，事务具有明确所有者。
6. 按需抽象：接口、分层及设计模式必须由真实需求驱动。
7. AI 受控：AI 可以建议架构演进，但不得擅自扩大修改范围。
8. CI 守门：机器验证结构与依赖，测试和代码审查补足业务语义。
9. 渐进演进：允许局部升级，避免一次性引入完整架构体系。
10. 验证诚实：架构保证以实际执行和测试结果为准。

Core Philosophy

简单业务保持简单，复杂业务守住边界。

以业务模块组织代码，以复杂度决定分层，以 Go 包边界控制依赖，以 CI 保证约束，以 AI 审批机制控制演进。

让架构随业务演进，而不是让业务迁就架构。