一款Python语言Django框架DDD脚手架，适合快速搭建项目
这是什么
Django-DDD 是一个精心打造的 Python 语言 DDD 工程脚手架，帮你快速搭建符合 DDD 精髓的 Web 服务。项目内置用户与订单示例、领域事件与内存总线、多数据库路由、统一响应与全局异常处理，适合作为团队工程模板，给AI提供代码规范参考。
为什么要用DDD？
很多人认为 Python 没必要用 DDD，毕竟它和 Ruby、JS 一样轻巧灵活，Django 自带的 MTV（Model-Template-View）拿来就能写。确实，大多数场景下"数据驱动"的 Django 模式完全够用。
工程化无非是把接口处理、业务逻辑、数据处理区分开，让各部分各司其职，方便维护和扩展。DDD 相对更适合中大型项目：如果项目有几十个模块、上百个接口，用 DDD 设计会更合适；模块少、接口不多的话，简单分层就够了。
项目做大以后，会遇到三个常见问题：
- 业务规则散落在各处：View 里判断状态，Model 里写校验，Service（如果有）里再来一次
- Model 太胖：既承担持久化，又承担业务逻辑，测试必须起 Django 才能跑
- 强耦合 Django：业务代码离不开
django.db.models，替换存储引擎几乎是重构
本脚手架遵循务实 DDD：抓住精髓（分层 + 领域模型 + 仓储抽象 + 领域事件），不死守概念（不做 CQRS、不强制事件溯源、不要求每个业务都建聚合）。总之，是否采用 DDD 和语言无关，只跟业务规模有关。
源码地址：design-patterns/practice-projects/django-ddd at main · microwind/design-patterns · GitHub
核心特点
- 严格 DDD 四层架构：领域层、应用层、基础设施层、接口层
- Django 5 + DRF：成熟生态 + 灵活 APIView
- 事件驱动：领域事件 + 进程内 Publisher（可替换为 Kafka/RocketMQ）
- 双数据库支持：用户库 + 订单库独立配置（默认 MySQL + PostgreSQL）
- 统一响应格式：
{ code, message, data }+ 全局异常处理器 - 领域层零 Django 依赖：纯 Python dataclass，方便单元测试
- 自动 OpenAPI：drf-spectacular 生成 Swagger UI，零警告零错误
- Docker 一键起停：MySQL + PostgreSQL + 应用整套编排
技术栈
| 技术 | 版本 | 说明 |
|---|---|---|
| Python | 3.10+ | 语言版本（使用str | None等新语法） |
| Django | 5.1 | Web 框架 |
| DRF | 3.15 | REST 接口层 |
| drf-spectacular | 0.27 | OpenAPI/Swagger 生成 |
| MySQL | 8.0+ | 用户库默认 |
| PostgreSQL | 13+ | 订单库默认 |
| YAML | - | 配置文件格式 |
工程结构
DDD 四层架构
DDD 四层架构
依赖接口
实现接口
接口层 Interfaces
DRF APIView · URLConf · Serializer
应用层 Application
用例编排 · 事务边界 · Command/DTO
领域层 Domain
聚合根 · 业务规则 · 领域事件
基础设施层 Infrastructure
Django ORM · 事件发布器 · 数据库
重点：外层只依赖内层；基础设施通过实现领域层定义的接口（Repository、EventPublisher）完成对内供给，保证领域层零框架依赖。
工程结构图
基础设施层 Infrastructure
领域层 Domain
应用层 Application
接口层 Interfaces
发布事件
实现
产生
DRF APIView
Serializer 请求校验
URLConf 路由
应用服务
Command / DTO
聚合根 User · Order
Repository 接口
领域事件
Django ORM Model
Repository 实现
EventPublisher 实现
MySQL
frog
PostgreSQL
seed
工程结构列表
django-ddd/ |
├── config/ |
│ ├── config.yaml # 本地配置（与 gin-ddd 字段一致） |
│ └── config.docker.yaml # docker compose 专用 |
├── docs/ |
│ ├── init.mysql.sql # 用户库 DDL + 样例数据 |
│ └── init.postgres.sql # 订单库 DDL + 样例数据 |
├── src/ |
│ ├── project/ # Django project |
│ │ ├── settings.py # 读 YAML → DATABASES 等 |
│ │ ├── urls.py # 根路由：健康检查 + /api + 文档 |
│ │ ├── routers.py # app_label → database 路由器 |
│ │ ├── wsgi.py / asgi.py |
│ │ └── __init__.py |
│ ├── shared/ # 共享层 |
│ │ ├── apps.py # 启动时构建事件发布器 |
│ │ ├── domain/ |
│ │ │ ├── events.py # DomainEvent 基类 |
│ │ │ └── publisher.py # EventPublisher 抽象 |
│ │ └── infrastructure/ |
│ │ ├── config.py # YAML → dataclass |
│ │ ├── response.py # 统一响应 + ApiResponseSerializer |
│ │ ├── exceptions.py # 领域异常 + 全局 handler |
│ │ └── events.py # InMemoryEventPublisher |
│ ├── user/ # 用户 bounded context |
│ │ ├── domain/{user,repository,events}.py # 聚合根/接口/事件 |
│ │ ├── application/{dto,service}.py # Command + 应用服务 |
│ │ ├── infrastructure/{models,repository,listeners}.py # ORM + 仓储实现 + 订阅者 |
│ │ ├── interfaces/{serializers,views,urls}.py # DRF 视图 + 路由 |
│ │ ├── models.py # re-export 供 Django 发现 |
│ │ └── apps.py # AppConfig.ready() 注册监听器 |
│ └── order/ # 订单 bounded context（含状态机） |
│ └── ... 同 user 结构 |
├── Dockerfile |
├── compose.yaml |
├── manage.py |
├── pyproject.toml |
└── requirements.txt |
各层职责说明
| 层级 | 位置 | 职责 | 关键原则 |
|---|---|---|---|
| 领域层 | */domain/ | 聚合根、值对象、领域事件、仓储接口 | 绝不 import django，业务规则内聚 |
| 应用层 | */application/ | 用例编排，Command/DTO，事务边界 | 薄而清晰，不实现业务规则 |
| 基础设施层 | */infrastructure/ | ORM 模型、仓储实现、事件发布器 | 实现领域接口，技术细节下沉 |
| 接口层 | */interfaces/ | DRF Serializer、APIView、URL | 只处理 HTTP 交互，不含业务规则 |
请求生命周期
以"创建订单"为例，展示一条 HTTP 请求在四层之间的流转：
POST /api/orders 完整链路
客户端
发送 JSON
接口层
CreateOrderRequest 校验
OrderListView.post
转换为 Command
应用层
OrderApplicationService.create
应用层
检查用户是否存在
领域层
Order.create() 校验 + 业务规则
基础设施层
DjangoOrderRepository.save
PostgreSQL
INSERT orders
基础设施层
InMemoryEventPublisher.publish
OrderCreatedEvent
触发监听器
接口层
api_response 包装
{code, message, data}
关键点：
- 跨越层次由内层接口控制：应用层调用
OrderRepository、EventPublisher接口，具体实现由基础设施在运行时注入。 - 业务规则集中在聚合根：
Order.create()内部完成金额合法性、订单号生成等校验，应用层不再写 if/else。 - 事件与主流程解耦：
publish失败只写日志，不阻塞请求响应。
快速开始
1. 环境准备
- Python 3.10+（项目使用了
str | None等 PEP 604 语法） - MySQL 8.0+ 与 PostgreSQL 13+（或自行选择其一）
- Docker（可选，用于一键起停）
2. 初始化数据库
默认配置使用双数据库：
- 用户库：MySQL（
frog） - 订单库：PostgreSQL（
seed）
Django 的 ORM Meta 配置为
managed = False，不会自动改表结构，
表结构完全由docs/init.*.sql负责，行为和 gin-ddd / nestjs-ddd 对齐。
MySQL 用户库（直接使用docs/init.mysql.sql）：
CREATE DATABASE IF NOT EXISTS frog CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; |
USE frog; |
CREATE TABLE users ( |
id BIGINT AUTO_INCREMENT PRIMARY KEY, |
name VARCHAR(50) NOT NULL UNIQUE, |
email VARCHAR(100) NOT NULL UNIQUE, |
phone VARCHAR(20), |
address VARCHAR(255), |
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 orders ( |
id BIGSERIAL PRIMARY KEY, |
order_no VARCHAR(50) NOT NULL UNIQUE, |
user_id BIGINT NOT NULL, |
total_amount DECIMAL(12, 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 |
); |
数据库适配注意：
- 若只用一个数据库，在
src/project/routers.py中把APP_DB_MAPPING全部指向default即可 - 若订单库改为 MySQL，字段
BIGSERIAL / TIMESTAMP需替换为BIGINT AUTO_INCREMENT / TIMESTAMP