Inbox/Go项目实战/00_顶层设计/关于项目的顶层设计模式和风格.md

tags, aliases, date created, date modified

tags	aliases	date created	date modified
	🏗️ Project Architecture & Design Guidelines (v1.0)	星期日, 十二月 7日 2025, 11:57:43 中午	星期二, 十二月 9日 2025, 11:00:14 晚上

🏗️ Project Architecture & Design Guidelines (v1.0)

项目代号: Enterprise-CMS-Core

架构风格: 模块化整洁架构 (Modular Clean Architecture)

核心原则: 实用主义 (Pragmatic)、Go 原生思维 (Idiomatic)、领域驱动 (DDD-Lite)

1. 技术栈约束 (Tech Stack Constraints)

• Language: Go 1.21+
• Web Framework: Gin
• Database: PostgreSQL (Primary), Redis (Cache)
• ORM: GORM (With Migration Tools)
• Dependency Injection: Google Wire
• Configuration: Viper (YAML)
• Observability: Zap (Log), Prometheus (Metrics), Jaeger (Trace)
• Documentation: Swagger / OpenAPI 3.0

---

2. 目录结构规范 (Directory Structure)

采用 “按领域分包 (Package by Domain)” 的扁平化结构，而非传统的按层分包。

root/
├── cmd/server/
│   ├── main.go             # 仅包含 wire 初始化与 app.Run()
│   └── wire.go             # 顶层依赖注入定义
├── config/                 # 配置文件模板 (config.yaml)
├── internal/
│   ├── api/                # [API层] 全局通用的 HTTP DTO (Request/Response)
│   ├── middleware/         # [中间件] Gin 中间件 (Auth, CORS, Logger)
│   ├── pkg/                # [基础设施] 内部通用组件 (AppResult, ErrorCode)
│   │
│   │   # --- 核心业务领域 (Domain Modules) ---
│   │   # 每个领域包内部扁平化，自包含所有逻辑
│   ├── user/               # [示例] 用户领域
│   │   ├── entity.go       # 核心实体 (GORM Model)
│   │   ├── repository.go   # 仓储接口定义 + GORM 实现
│   │   ├── service.go      # 业务逻辑 (Service Struct)
│   │   ├── handler.go      # HTTP 控制器 (Controller)
│   │   └── provider.go     # Wire ProviderSet
│   │
│   └── article/            # [示例] 文章领域 (结构同上)
│
├── pkg/                    # [外部库] 可抽离的通用工具 (Hash, JWT, Logger封装)
├── migrations/             # 数据库迁移 SQL 文件 (up/down)
├── go.mod
└── Makefile

---

3. 核心架构设计规则 (Architectural Rules)

3.1. 依赖倒置与注入 (IoC & DI)

• 规则: 严禁在业务代码中手动 New() 依赖对象。
• 实现: 所有依赖关系必须通过 NewStruct(dep Interface) 构造函数声明，并由 Google Wire 在编译期自动组装。
• 模块化注入: 每个领域包（如 internal/user）必须包含一个 provider.go，导出 var ProviderSet = wire.NewSet(…)，供顶层 cmd/server/wire.go 聚合。

3.2. 接口策略 (Interface Strategy)

• Repository (必须): 仓储层必须定义接口（例如 UserRepository），以支持 Mock 测试和数据库切换。

• Service (按需): 默认不需要定义 Service 接口，直接使用 Struct。仅在以下情况提取接口：

  1. 出现循环依赖。
  2. 需要对 Service 进行 Mock 测试。
  3. 该 Service 存在多种策略实现（如 PaymentService 有支付宝/微信两种实现）。

3.3. 领域包扁平化 (Flat Domain Package)

• 规则: 在 internal/user/ 等领域包内，不再建立 service/, repo/ 子目录。
• 原因: 利用 Go 的 package 级私有可见性，隐藏领域内部细节（如辅助函数、内部 DTO），仅暴露必要的 Handler 和 Service 方法。

3.4. 数据模型 (Model Vs Entity)

• 策略: 采用 "Pragmatic Entity" 模式。
• 定义: entity.go 中的结构体既是业务实体，也是 GORM 模型（带 gorm:"…" 标签）。
• 例外: 只有当数据库存储结构与业务逻辑结构差异巨大时，才在 Repository 内部引入独立的 PO (Persistent Object) 并进行转换。

---

4. 编码实施标准 (Implementation Standards)

4.1. 错误处理 (Error Handling)

• 禁止: 严禁直接返回 error 字符串给前端。

• 必须: Service 层返回标准 error，Controller 层通过 pkg/app 将其转换为统一响应格式。

• 格式:

  // Response JSON
  {
      "code": 20001,
      "msg": "User already exists",
      "data": null
  }
  

4.2. 数据库交互 (Database Interaction)

• 禁止: Controller 层严禁导入 gorm 包，严禁执行 SQL。
• 迁移: 生产环境严禁使用 AutoMigrate。必须使用 migrations/ 目录下的版本化 SQL 脚本进行变更。

4.3. 路由注册 (Router Registration)

• 规则: 路由不再集中管理。
• 实现: 每个领域包暴露一个 RegisterRoutes(r *gin.RouterGroup) 方法。在 main.go 启动时，统一调用各模块的注册方法。

---

5. AI 编程指令 (Instruction for AI Agent)

当作为 AI 助手编写代码时，请严格遵守以下指令：

1. Context Check: 在生成代码前，检查当前目录结构是否符合 Section 2。如果不符，请优先建议重构或遵循现有结构。
2. No Logic Leak: 确保 HTTP 处理逻辑（解析参数、校验参数）留在 handler.go，业务规则（判断权限、计算）留在 service.go，SQL 操作留在 repository.go。
3. Wire Awareness: 每当新增 Service 或 Repository，必须自动更新同目录下的 provider.go，并在 cmd/server/wire.go 中检查是否需要重新生成。
4. Testability: 编写 Repository 代码时，优先考虑“如何 Mock”。