核心特点

• 严格 DDD 四层架构：领域层、应用层、基础设施层、接口层
• Gin Web 框架：高性能 HTTP 服务
• 事件驱动：领域事件 + RocketMQ 生产者/消费者
• 双数据库支持：用户库 + 订单库可独立配置（默认 MySQL + PostgreSQL）
• 统一响应格式：Response 封装，错误码集中管理
• 全局中间件：日志、恢复、跨域
• 可选邮件通知：订单创建事件驱动 SMTP 邮件发送

技术栈

技术	版本	说明
Go	1.21+	语言版本
Gin	1.9+	HTTP 框架
RocketMQ	5.3+	事件消息队列
MySQL	8.0+	用户库默认
PostgreSQL	14+	订单库默认
YAML	-	配置文件格式

工程结构

工程结构图

基础设施层

领域层

应用层

接口层

实现

实现

发布事件

HTTP Handler / 路由

应用服务

领域服务

聚合根/实体

仓储接口

通知接口

仓储实现

邮件服务

消息队列

数据库

工程结构列表

	gin-ddd/
	├── cmd/server/main.go # 启动入口，装配各层并启动 HTTP + MQ
	├── config/config.yaml # 应用配置
	├── docs/init.sql # MySQL 初始化脚本（示例）
	├── internal/
	│ ├── domain/ # 领域层
	│ │ ├── model/
	│ │ │ ├── order/order.go # 订单聚合根
	│ │ │ └── user/user.go # 用户聚合根
	│ │ ├── repository/ # 仓储接口
	│ │ │ ├── order/order_repository.go
	│ │ │ └── user/user_repository.go
	│ │ ├── event/ # 领域事件
	│ │ │ ├── domain_event.go
	│ │ │ ├── order_event.go
	│ │ │ ├── user_event.go
	│ │ │ └── event_publisher.go
	│ │ ├── notification/mail_service.go # 通知领域接口（邮件）
	│ │ └── service/ # 领域服务（预留）
	│ ├── application/ # 应用层
	│ │ ├── dto/
	│ │ │ ├── order/order_dto.go
	│ │ │ └── user/user_dto.go
	│ │ └── service/
	│ │ ├── order/order_service.go # 订单应用服务（发布事件）
	│ │ └── user/user_service.go # 用户应用服务
	│ ├── infrastructure/ # 基础设施层
	│ │ ├── config/ # 配置与 DB 初始化
	│ │ ├── persistence/ # 仓储实现
	│ │ │ ├── order/order_repository_impl.go
	│ │ │ └── user/user_repository_impl.go
	│ │ ├── mq/ # RocketMQ 实现
	│ │ │ ├── rocketmq_producer.go
	│ │ │ └── rocketmq_consumer.go
	│ │ ├── mail/ # SMTP 邮件实现
	│ │ ├── middleware/ # Gin 中间件
	│ │ ├── common/response.go # 统一响应
	│ │ └── constants/error_code.go # 错误码
	│ └── interfaces/ # 接口层
	│ ├── handler/ # HTTP 处理器
	│ ├── router/ # 路由配置
	│ └── vo/ # 请求/响应对象
	└── pkg/utils/ # 日志等工具

各层职责说明

层级	位置	职责	关键原则
领域层	internal/domain/	领域模型、规则与事件	不依赖框架、业务逻辑内聚
应用层	internal/application/	编排领域对象、事务边界	薄而清晰，不实现业务规则
基础设施层	internal/infrastructure/	DB、MQ、邮件等技术细节	向上提供实现，细节下沉
接口层	internal/interfaces/	HTTP 请求/响应与路由	处理外部交互，不含业务规则

快速开始

1. 环境准备

• Go 1.21+
• MySQL 8.0+ 与 PostgreSQL 14+（或自行选择其一）
• RocketMQ 5.3+（可选）

2. 初始化数据库

默认配置使用双数据库：

• 用户库：MySQL
• 订单库：PostgreSQL

MySQL 用户库示例（可直接用 docs/init.sql 作为起点）：

	CREATE DATABASE IF NOT EXISTS gin_ddd CHARACTER SET utf8mb4;
	USE gin_ddd;
	CREATE TABLE IF NOT EXISTS users (
	id BIGINT AUTO_INCREMENT PRIMARY KEY,
	name VARCHAR(50) NOT NULL UNIQUE,
	email VARCHAR(100) NOT NULL UNIQUE,
	phone VARCHAR(20),
	created_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
	updated_time TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
	);

PostgreSQL 订单库示例（与当前订单仓储字段一致）：

	CREATE DATABASE seed;
	\c seed;
	CREATE TABLE IF NOT EXISTS orders (
	id BIGSERIAL PRIMARY KEY,
	order_no VARCHAR(50) NOT NULL UNIQUE,
	user_id BIGINT NOT NULL,
	total_amount DECIMAL(10, 2) NOT NULL DEFAULT 0.00,
	status VARCHAR(20) NOT NULL DEFAULT 'PENDING',
	created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
	updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
	);

数据库适配注意：

• 若订单库改为 MySQL，需要将 SQL 占位符从 $1 形式改为 ?
• 若用户库改为 PostgreSQL，需要将插入 ID 获取逻辑改为 RETURNING id

3. 配置应用

编辑 config/config.yaml，至少配置数据库与 RocketMQ：

	server:
	host: "0.0.0.0"
	port: 8080
	mode: "debug"
	database:
	user:
	driver: "mysql"
	host: "localhost"
	port: 3306
	username: "root"
	password: "your_password"
	database: "gin_ddd"
	order:
	driver: "postgres"
	host: "localhost"
	port: 5432
	username: "postgres"
	password: "your_password"
	database: "seed"
	rocketmq:
	enabled: true
	nameserver: "localhost:9876"
	group_name: "gin-ddd-group"
	instance_name: "gin-ddd-instance"
	topics:
	order_event: "order-event-topic"

说明：

• rocketmq.enabled: true 才会初始化生产者与消费者
• 当前订单事件 Topic 在代码中使用固定值 order-event-topic，需与配置保持一致

4. 启动 RocketMQ（可选）

	sh bin/mqnamesrv
	sh bin/mqbroker -n localhost:9876

5. 启动应用

	go mod tidy
	go run cmd/server/main.go

6. 验证接口

	curl http://localhost:8080/health
	curl http://localhost:8080/api/users
	curl http://localhost:8080/api/orders

如何基于脚手架开发新功能

示例：新增“商品管理”模块

步骤 1：新增领域模型 internal/domain/model/product/product.go

	package product
	import "time"
	type Product struct {
	ID int64
	Name string
	Price float64
	Stock int
	CreatedAt time.Time
	UpdatedAt time.Time
	}

步骤 2：新增仓储接口 internal/domain/repository/product/product_repository.go

	package product
	import (
	"context"
	"gin-ddd/internal/domain/model/product"
	)
	type ProductRepository interface {
	Create(ctx context.Context, p *product.Product) error
	Update(ctx context.Context, p *product.Product) error
	FindByID(ctx context.Context, id int64) (*product.Product, error)
	FindAll(ctx context.Context) ([]*product.Product, error)
	}

步骤 3：新增仓储实现 internal/infrastructure/persistence/product/product_repository_impl.go

	package product
	import (
	"context"
	"database/sql"
	"gin-ddd/internal/domain/model/product"
	)
	type ProductRepositoryImpl struct {
	db *sql.DB
	}
	func NewProductRepository(db *sql.DB) *ProductRepositoryImpl {
	return &ProductRepositoryImpl{db: db}
	}
	func (r *ProductRepositoryImpl) Create(ctx context.Context, p *product.Product) error {
	_, err := r.db.ExecContext(ctx,
	`INSERT INTO products (name, price, stock, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`,
	p.Name, p.Price, p.Stock, p.CreatedAt, p.UpdatedAt,
	)
	return err
	}

步骤 4：新增应用服务 internal/application/service/product/product_service.go

	package product
	import (
	"context"
	"time"
	"gin-ddd/internal/domain/model/product"
	productDomain "gin-ddd/internal/domain/repository/product"
	)
	type ProductService struct {
	repo productDomain.ProductRepository
	}
	func NewProductService(repo productDomain.ProductRepository) *ProductService {
	return &ProductService{repo: repo}
	}
	func (s *ProductService) Create(ctx context.Context, name string, price float64, stock int) error {
	p := &product.Product{
	Name: name,
	Price: price,
	Stock: stock,
	CreatedAt: time.Now(),
	UpdatedAt: time.Now(),
	}
	return s.repo.Create(ctx, p)
	}

步骤 5：新增 HTTP Handler 和路由

将请求/响应对象放到 internal/interfaces/vo/product/，Handler 放到 internal/interfaces/handler/product/，并在 internal/interfaces/router/router.go 中注册路由。

步骤 6：新增数据库表

	CREATE TABLE IF NOT EXISTS products (
	id BIGINT AUTO_INCREMENT PRIMARY KEY,
	name VARCHAR(100) NOT NULL,
	price DECIMAL(10, 2) NOT NULL,
	stock INT NOT NULL DEFAULT 0,
	created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP,
	updated_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
	);

事件驱动与 RocketMQ

事件类型

订单事件：

• order.created
• order.paid
• order.shipped
• order.delivered
• order.cancelled
• order.refunded

用户事件：

• user.created
• user.activated
• user.deactivated
• user.blocked
• user.deleted

消息流转

	HTTP 请求 -> Application Service -> Domain Model
	-> 发布 DomainEvent -> RocketMQ Producer
	-> RocketMQ Broker -> Consumer
	-> 事件处理 -> 发送邮件/触发后续流程

事件发布与消费关键点

• 订单创建后会发布 order.created 事件（发布失败不会影响主流程）
• 消费端按 Tag 解析为 OrderEvent 或 UserEvent
• 订单邮件通知仅在 order.created 且启用邮件时触发

邮件发送配置（QQ 邮箱）

在 config/config.yaml 中开启邮件配置：

	mail:
	enabled: true
	host: "smtp.qq.com"
	port: 465
	username: "your@qq.com"
	password: "你的SMTP授权码"
	from_email: "your@qq.com"
	from_name: "订单系统"

注意事项：

• 必须使用 SMTP 授权码，不是 QQ 登录密码
• 端口 465 使用 TLS，端口 587 使用 STARTTLS
• 收件人取自用户表中的 email 字段

常见问题排查

• 日志提示“事件发布器未初始化”：RocketMQ 未启用或初始化失败
• 订单事件已发送但邮件未到：确认用户邮箱字段正确，且 SMTP 授权码可用
• 消费者没有收到消息：确认 Topic 与 Tag 正确、Broker 启动正常

开发规范

命名建议：

• 领域模型：名词，如 Order、User
• 应用服务：XxxService
• 仓储接口：XxxRepository
• 仓储实现：XxxRepositoryImpl
• Handler：XxxHandler

分层原则：

• 领域层不依赖基础设施
• 应用层只做编排与事务协调
• 基础设施提供技术实现
• 接口层只负责 HTTP 交互

常用命令

	go mod tidy
	go test ./...