# gin-ddd-scaffold

**Repository Path**: yefengr/gin-ddd-scaffold

## Basic Information

- **Project Name**: gin-ddd-scaffold
- **Description**: 基于 Go + Gin + GORM 的 DDD（领域驱动设计）脚手架，包含前端 React + TypeScript + Ant Design。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-01-07
- **Last Updated**: 2026-01-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Gin DDD Scaffold

基于 Go + Gin + GORM 的 DDD（领域驱动设计）脚手架，包含前端 React + TypeScript + Ant Design。

## 特性

- **DDD 分层架构**：接口层、应用层、领域层、基础设施层
- **代码生成**：GORM Gen 自动生成模型，Wire 依赖注入，Swagger 文档
- **前后端分离**：后端 Go API，前端 React SPA
- **完整示例**：包含 Example 模块作为开发参考

## 技术栈

| 层级 | 技术 |
|------|------|
| 后端 | Go 1.25 + Gin + GORM + PostgreSQL |
| 前端 | React 19 + TypeScript + Vite + Ant Design + Zustand |
| 数据库 | PostgreSQL 18 (Docker) |
| 文档 | Swagger (自动生成) |

## 快速开始

### 环境要求

- Go 1.25+
- Node.js 18+
- pnpm
- Docker

### 一键启动

```bash
# 首次使用，完成所有初始化
make setup

# 启动开发环境（数据库 + 后端 + 前端）
make dev
```

### 访问地址

| 服务 | 地址 |
|------|------|
| 前端 | http://localhost:5173 |
| 后端 API | http://localhost:8080/api/v1 |
| Swagger 文档 | http://localhost:8080/swagger/index.html |

## 项目结构

```
gin-ddd-scaffold/
├── backend/                 # 后端服务 (Go)
│   ├── internal/
│   │   ├── interfaces/      # 接口层 (Handler、DTO、路由)
│   │   ├── application/     # 应用层 (用例编排)
│   │   ├── domain/          # 领域层 (实体、值对象、仓储接口)
│   │   ├── infrastructure/  # 基础设施层 (数据库、配置)
│   │   ├── config/          # 配置加载
│   │   ├── pkg/             # 工具包 (日志等)
│   │   └── wire/            # 依赖注入
│   ├── migrations/          # 数据库迁移
│   └── config/              # 配置文件
│
├── frontend/                # 前端应用 (React)
│   └── src/
│       ├── api/             # API 调用
│       ├── pages/           # 页面组件
│       ├── components/      # 公共组件
│       ├── stores/          # Zustand 状态管理
│       ├── hooks/           # 自定义 Hooks
│       └── router/          # 路由配置
│
├── docs/                    # 项目文档
├── docker-compose.yml       # Docker 配置
└── Makefile                 # 构建命令
```

## 常用命令

### 开发

```bash
make dev              # 启动完整开发环境
make backend-dev      # 仅启动后端
make frontend-dev     # 仅启动前端
```

### 测试

```bash
make test             # 运行全部测试
make backend-test     # 后端测试
make frontend-test    # 前端测试
```

### 代码生成

```bash
make backend-swag     # 生成 Swagger 文档
make backend-wire     # 生成 Wire 依赖注入
make backend-gen      # 生成 GORM Gen 模型
make frontend-api     # 根据 Swagger 生成前端 API
```

### 数据库

```bash
make db-up            # 启动 PostgreSQL
make db-down          # 停止数据库
make db-init          # 初始化表结构
make db-reset         # 重置数据库
```

## 新功能开发流程

以添加 `User` 模块为例：

### 1. 数据库表

```sql
-- backend/migrations/002_users.sql
CREATE TABLE users (
    id          SERIAL PRIMARY KEY,
    name        VARCHAR(255) NOT NULL,
    email       VARCHAR(255) UNIQUE NOT NULL,
    created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    deleted_at  TIMESTAMP
);
```

执行迁移并生成模型：

```bash
make db-init
make backend-gen
```

### 2. 领域层

```go
// internal/domain/user/entity.go
type User struct {
    ID        int64
    Name      string
    Email     string
    CreatedAt time.Time
    UpdatedAt time.Time
}

// internal/domain/user/repository.go
type Repository interface {
    Create(ctx context.Context, user *User) error
    FindByID(ctx context.Context, id int64) (*User, error)
    // ...
}
```

### 3. 基础设施层

```go
// internal/infrastructure/persistence/repository/user.go
// internal/infrastructure/persistence/converter/user.go
```

### 4. 应用层

```go
// internal/application/user/service.go
```

### 5. 接口层

```go
// internal/interfaces/api/handler/user.go
// internal/interfaces/api/dto/request/user.go
// internal/interfaces/api/dto/response/user.go
```

### 6. Wire 依赖注入

更新 `internal/wire/wire.go` 后执行：

```bash
make backend-wire
```

### 7. 生成 API 文档

```bash
make backend-swag
make frontend-api  # 生成前端 API 代码
```

## 配置说明

配置文件位于 `backend/config/config.yaml`：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| server.port | 服务端口 | :8080 |
| server.mode | 运行模式 (debug/release) | debug |
| db.* | 数据库连接配置 | localhost:5432 |
| log.* | 日志配置 | ./data/logs |

## API 接口示例

### 示例管理 (Example)

| 方法 | 路径 | 说明 |
|------|------|------|
| POST | /api/v1/examples | 创建示例 |
| GET | /api/v1/examples | 获取示例列表 |
| GET | /api/v1/examples/:id | 获取示例详情 |
| PUT | /api/v1/examples/:id | 更新示例 |
| DELETE | /api/v1/examples/:id | 删除示例 |

详细接口文档请访问 Swagger：http://localhost:8080/swagger/index.html

## 开发指南

详见 [CLAUDE.md](./CLAUDE.md) 和 [docs/](./docs/) 目录下的文档：

- [架构设计](./docs/架构设计.md)
- [数据库设计](./docs/数据库设计.md)
- [API 设计](./docs/API设计.md)
- [开发指南](./docs/开发指南.md)

## License

MIT