# DDD-app-example **Repository Path**: captials-team/ddd-app-example ## Basic Information - **Project Name**: DDD-app-example - **Description**: 基于DDD框架的应用示例 - **Primary Language**: Go - **License**: BSD-3-Clause - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-08 - **Last Updated**: 2026-04-30 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # ddd_app_example 基于 **领域驱动设计(DDD)** 的 Go 项目脚手架,使用 Go 1.24 标准库构建,零外部依赖。 --- ## 技术栈 | 类别 | 技术 | |------|------| | 语言 | Go 1.24 | | HTTP 框架 | [Gin](https://github.com/gin-gonic/gin) v1.12 | | API 文档 | [Swagger](https://github.com/swaggo/swag)(swaggo/swag v1.16) | | 持久化 | 内存仓储(可替换为 PostgreSQL / MySQL / MongoDB 等) | | 配置 | 环境变量 | | 依赖注入 | 手动装配(构造函数注入) | --- ## 设计模式 ### 架构模式:领域驱动设计(DDD) 项目严格遵循 DDD 四层架构,依赖方向为: ``` interfaces → application → domain ← infrastructure ``` #### 各层职责 | 层 | 路径 | 职责 | |----|------|------| | **Domain 领域层** | `internal/domain/` | 核心业务规则,不依赖任何框架或基础设施 | | **Application 应用层** | `internal/application/` | 编排领域对象,实现业务用例,定义事务边界 | | **Infrastructure 基础设施层** | `internal/infrastructure/` | 技术细节实现:持久化、配置、消息等 | | **Interfaces 接口层** | `internal/interfaces/` | 对外暴露入口:HTTP、gRPC、CLI 等 | #### 关键设计模式 - **聚合根(Aggregate Root)**:`User` 是用户领域的聚合根,所有状态变更通过其方法进行,保证不变量 - **仓储模式(Repository Pattern)**:`domain` 层定义接口,`infrastructure` 层提供实现,依赖倒置 - **命令查询分离(CQS)**:应用层区分 `Command`(写操作)和 `Query`(读操作),职责清晰 - **领域事件(Domain Events)**:`event.go` 定义领域内发生的业务事件,供后续扩展事件总线使用 - **领域服务(Domain Service)**:跨实体的业务逻辑(如邮箱唯一性校验)放入 `domain/service.go` - **值对象(Value Object)**:无副作用的概念可定义为值对象(扩展点) - **数据传输对象(DTO)**:应用层通过 `UserDTO`、`AddressDTO` 向上层暴露数据,隔离领域模型 --- ## 项目结构 ``` . ├── cmd/ │ └── main.go # 程序入口 ├── internal/ │ ├── domain/ │ │ ├── user/ │ │ │ ├── entity.go # User 聚合根 │ │ │ ├── repository.go # 仓储接口(契约) │ │ │ ├── service.go # 领域服务 │ │ │ ├── event.go # 领域事件定义 │ │ │ └── errors.go # 领域错误 │ │ └── address/ │ │ ├── entity.go # Address 实体 │ │ ├── repository.go # 仓储接口(契约) │ │ └── errors.go # 领域错误 │ ├── application/ │ │ ├── user/ │ │ │ ├── command.go # 写操作命令对象 │ │ │ ├── query.go # 读操作查询对象 & DTO │ │ │ └── service.go # 应用服务(用例编排) │ │ └── address/ │ │ ├── command.go # 写操作命令对象 │ │ ├── query.go # 读操作查询对象 & DTO │ │ └── service.go # 应用服务(用例编排) │ ├── infrastructure/ │ │ ├── config/ │ │ │ └── config.go # 环境变量配置 │ │ └── persistence/ │ │ ├── user_repository.go # 用户内存仓储实现 │ │ └── address_repository.go # 地址内存仓储实现 │ └── interfaces/ │ └── http/ │ ├── server.go # HTTP 服务器 & 依赖装配 │ └── handler/ │ ├── user_handler.go # 用户 HTTP 请求处理器 │ └── address_handler.go # 地址 HTTP 请求处理器 └── go.mod ``` --- ## 快速开始 ### 前置要求 - Go 1.22+���推荐 1.24) ### 运行服务 ```bash # 使用默认端口 :8080 go run ./cmd/main.go # 自定义端口 HTTP_ADDR=:9090 go run ./cmd/main.go ``` 服务启动后,访问 **http://localhost:8080/swagger/index.html** 即可在线查看 Swagger API 文档。 --- ### 更新 API 文档 修改接口注解后,执行以下命令重新生成文档: ```bash bash gen_docs.sh ``` --- ## API 使用示例 ### 用户管理 #### 创建用户 ```bash curl -X POST http://localhost:8080/users \ -H "Content-Type: application/json" \ -d '{"ID":"1","Name":"Alice","Email":"alice@example.com"}' ``` 响应:`201 Created` #### 查询用户 ```bash curl http://localhost:8080/users/1 ``` 响应: ```json { "id": "1", "name": "Alice", "email": "alice@example.com" } ``` #### 删除用户 ```bash curl -X DELETE http://localhost:8080/users/1 ``` 响应:`204 No Content` --- ### 收货地址管理 #### 新增地址 ```bash curl -X POST http://localhost:8080/users/1/addresses \ -H "Content-Type: application/json" \ -d '{ "ID": "addr-1", "ReceiverName": "Alice", "Phone": "13800138000", "Province": "广东省", "City": "深圳市", "District": "南山区", "Street": "科技园路1号", "Detail": "A栋101室" }' ``` 响应:`201 Created` #### 查询用户所有地址 ```bash curl http://localhost:8080/users/1/addresses ``` 响应: ```json [ { "id": "addr-1", "user_id": "1", "receiver_name": "Alice", "phone": "13800138000", "province": "广东省", "city": "深圳市", "district": "南山区", "street": "科技园路1号", "detail": "A栋101室", "is_default": false } ] ``` #### 查询单条地址 ```bash curl http://localhost:8080/users/1/addresses/addr-1 ``` #### 更新地址 ```bash curl -X PUT http://localhost:8080/users/1/addresses/addr-1 \ -H "Content-Type: application/json" \ -d '{ "ReceiverName": "Alice", "Phone": "13900139000", "Province": "广东省", "City": "广州市", "District": "天河区", "Street": "天河路100号", "Detail": "B栋202室" }' ``` 响应:`204 No Content` #### 设为默认地址 ```bash curl -X PATCH http://localhost:8080/users/1/addresses/addr-1/default ``` 响应:`204 No Content` #### 删除地址 ```bash curl -X DELETE http://localhost:8080/users/1/addresses/addr-1 ``` 响应:`204 No Content` --- ## 扩展指南 ### 替换持久化实现 在 `internal/infrastructure/persistence/` 下新增实现文件,实现对应的 `Repository` 接口,然后在 `internal/interfaces/http/server.go` 的 `NewServer` 中替换注入即可: ```go // 替换前 userRepo := persistence.NewInMemoryUserRepository() addressRepo := persistence.NewInMemoryAddressRepository() // 替换后(示例) userRepo := persistence.NewPostgresUserRepository(db) addressRepo := persistence.NewPostgresAddressRepository(db) ``` ### 新增业务领域 按照如下步骤添加新领域(以 `order` 为例): 1. 在 `internal/domain/order/` 下定义实体、仓储接口、领域服务 2. 在 `internal/application/order/` 下定义命令、查询和应用服务 3. 在 `internal/infrastructure/persistence/` 下实现仓储 4. 在 `internal/interfaces/http/handler/` 下添加 HTTP 处理器 5. 在 `server.go` 中注册路由 ### 配置项 | 环境变量 | 默认值 | 说明 | |----------|--------|------| | `HTTP_ADDR` | `:8080` | HTTP 监听地址 |