# ddd-quickly-start

**Repository Path**: dothGitee/ddd-quickly-start

## Basic Information

- **Project Name**: ddd-quickly-start
- **Description**: 快速帮助DDD领域驱动设计理解初步, 正确阅读顺序阅读范围 : 
1. 从四层架构 ->
2. 四层协作顺序 从 domain 到  interfaces | DTO作为层级适配转接 | 持久化模型和领域模型的适配转接 ->
- domain 层：定义业务状态, 领域行为
- infrastructure 层：实现领域行为, 变更业务状态
- application 层：定义业务行为，编排领域行为
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README



# DDD 快速启动示例项目

本项目是一个基于 **领域驱动设计 (DDD)** 架构模式构建的 Spring Boot 示例应用，演示了如何在实际项目中应用 DDD 核心概念进行软件开发。

## 项目特性

- **分层架构**：展示清晰的领域层、应用层、基础设施层和接口层
- **领域建模**：包含聚合根、值对象、领域服务等 DDD 核心概念
- **基础设施**：集成 MyBatis 进行数据持久化
- **RESTful API**：提供城市信息的增删改查接口
- **统一响应**：标准化的接口响应格式
- **操作追踪**：完整的请求日志记录功能
- **异常处理**：全局异常处理器，友好的错误提示

## 技术栈

- **Spring Boot 3.x** - 应用框架
- **MyBatis** - 数据持久化
- **Lombok** - 简化代码
- **Springdoc OpenAPI** - API 文档生成
- **Maven** - 项目构建

## 项目结构

```
src/main/java/com/doth/demo01/
├── demo01/Demo01Application.java          # 应用启动类
├── application/                            # 应用层
│   └── city/CityAppService.java           # 城市应用服务
├── domain/                                 # 领域层
│   └── city/
│       ├── City.java                      # 城市聚合根
│       ├── CityId.java                    # 城市ID值对象
│       ├── CityRepository.java            # 城市仓储接口
│       └── CityErrorCode.java             # 领域错误码
├── infrastructure/                         # 基础设施层
│   ├── CityRepositoryMybatis.java         # 仓储MyBatis实现
│   └── persistence/                       # 持久化相关
│       ├── entity/CityEntity.java         # 持久化实体
│       ├── mapper/CityMapper.java         # MyBatis Mapper
│       └── CityPersistenceMapper.java     # 领域-实体映射
└── interfaces/                             # 接口层
    ├── city/
    │   ├── CityController.java            # 城市控制器
    │   ├── CityDTO.java                   # 城市数据传输对象
    │   └── CitySaveReq.java               # 城市保存请求
    ├── shared/                            # 共享组件
    │   ├── base/                          # 基础类
    │   │   ├── BaseController.java        # 控制器基类
    │   │   ├── Op.java                    # 操作追踪
    │   │   ├── LoggingObserver.java       # 日志观察者
    │   │   └── ResultVO.java              # 统一响应
    │   ├── vo/PageResponse.java           # 分页响应
    │   └── excp/                          # 异常处理
```

## 快速开始

### 环境要求

- JDK 17+
- Maven 3.6+

### 构建与运行

```bash
# 克隆项目
git clone https://gitee.com/dothGitee/ddd-quickly-start.git

# 进入项目目录
cd ddd-quickly-start

# 构建项目
mvn clean install

# 运行应用
mvn spring-boot:run
```

应用启动后，访问 `http://localhost:8080` 即可看到页面。

## API 接口

### 分页查询城市

```
GET /api/cities?keyword=&pageNum=1&pageSize=10
```

**参数：**
- `keyword` - 搜索关键词（可选）
- `pageNum` - 页码，默认 1
- `pageSize` - 每页大小，默认 10

**响应示例：**
```json
{
  "code": 0,
  "message": "success",
  "data": {
    "total": 2,
    "list": [
      {
        "cityId": 1,
        "country": "中国",
        "province": "广东",
        "cityName": "深圳"
      }
    ]
  }
}
```

### 新增城市

```
POST /api/cities
```

**请求体：**
```json
{
  "cityId": 1,
  "country": "中国",
  "province": "广东",
  "cityName": "深圳"
}
```

**响应示例：**
```json
{
  "code": 0,
  "message": "success"
}
```

## 核心领域概念

### 聚合根 (City)

`City` 作为城市聚合的聚合根，封装了城市的核心业务逻辑：

- **不变性维护**：确保国家、省份、城市名称不为空
- **领域行为**：`rename()` 改名、`moveProvince()` 迁移省份

### 值对象 (CityId)

`CityId` 使用 Java Record 实现，作为城市的唯一标识值对象。

### 仓储模式

`CityRepository` 定义了领域层的仓储接口，实现了领域层与基础设施层的解耦。

## 扩展指南

### 添加新的聚合

1. 在 `domain/` 下创建聚合包
2. 定义聚合根实体和值对象
3. 在 `infrastructure/` 实现对应的仓储
4. 在 `application/` 创建应用服务
5. 在 `interfaces/` 添加控制器

### 替换持久化技术

当前使用 MyBatis，如需更换为 JPA 或其他框架：

1. 修改 `infrastructure/` 下的仓储实现类
2. 更新 `persistence/` 包的映射逻辑

## 许可证

本项目采用 [MIT License](LICENSE) 开源协议。