---
tags: []
aliases:
  - 🏗️ Project Architecture & Design Guidelines (v1.0)
date created: 星期日, 十二月 7日 2025, 11:57:43 中午
date modified: 星期二, 十二月 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)”** 的扁平化结构，而非传统的按层分包。

```Plaintext
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` 将其转换为统一响应格式。
- **格式:**

    ```Go
    // 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”。