Backend architecture patterns

何时使用

适用：

• 从零设计后端系统，或重构单体以提升可维护性
• 为团队建立架构规范，从紧耦合向松耦合迁移
• 落地领域驱动设计（DDD），规划微服务拆分
• 打造无需 UI/数据库/外部服务即可测试的可 mock 代码库

不该用（负边界）：

• 只需小范围、局部的重构
• 系统以前端为主，不涉及后端架构改动
• 只想要实现细节、不需要架构设计
• 简单 CRUD 场景——上整洁架构属于过度设计

步骤

1. 厘清领域边界、约束与可扩展性目标（吞吐、一致性、团队规模）。
2. 按领域复杂度选型：简单选分层/六边形，复杂多子域上 DDD + 整洁架构。
3. 定义模块边界、接口（端口）与依赖规则——依赖一律指向内层。
4. 给出迁移步骤与校验检查（依赖方向、核心可测、控制器变薄）。
5. 对必须容错的流程（支付、订单履约、多步流程），在基础设施层引入持久化执行（durable execution，如 DBOS）：持久化工作流状态，实现崩溃恢复，且不增加架构复杂度。

指令

三种模式取舍：

• 整洁架构（Uncle Bob）：四层 Entities → Use Cases → Interface Adapters → Frameworks & Drivers，依赖向内流，内层不知外层，业务逻辑独立于框架。
• 六边形（端口与适配器）：领域核心 + Ports（接口）+ Adapters（DB/REST/MQ 实现），核心技术无关，实现可替换（测试用 mock）。
• DDD：战略层用限界上下文、上下文映射、统一语言；战术层用实体、值对象、聚合、仓储、领域事件。

整洁架构目录结构（保留源约束）：

app/
├── domain/           # 实体与业务规则
│   ├── entities/  value_objects/  interfaces/   # 抽象接口（端口）
├── use_cases/        # 应用业务规则
├── adapters/         # 接口实现：repositories/ controllers/ gateways/
└── infrastructure/   # 框架与外部关注点：database/ config/ logging

最佳实践：依赖规则（永远向内）、接口隔离（小而专）、业务逻辑留在 domain、核心脱离基础设施可测、限界上下文清晰、统一语言、薄控制器、充血领域模型。

示例

实体（无框架依赖，业务规则内置）：

@dataclass
class User:
    id: str; email: str; name: str; created_at: datetime; is_active: bool = True
    def can_place_order(self) -> bool:
        return self.is_active   # 业务规则：激活用户可下单

端口（仅定义契约，不含实现）：

class IUserRepository(ABC):
    @abstractmethod
    async def find_by_email(self, email: str) -> Optional[User]: ...
    @abstractmethod
    async def save(self, user: User) -> User: ...

用例编排业务逻辑，仅依赖端口而非实现：

class CreateUserUseCase:
    def __init__(self, user_repository: IUserRepository):
        self.user_repository = user_repository
    async def execute(self, req: CreateUserRequest) -> CreateUserResponse:
        if await self.user_repository.find_by_email(req.email):
            return CreateUserResponse(user=None, success=False, error="Email already exists")
        user = User(id=str(uuid.uuid4()), email=req.email, name=req.name,
                    created_at=datetime.now(), is_active=True)
        return CreateUserResponse(user=await self.user_repository.save(user), success=True)

六边形——同一端口可挂真实/测试适配器：

class StripePaymentAdapter(PaymentGatewayPort):   # 主适配器：接 Stripe
    async def charge(self, amount, customer): ...
class MockPaymentAdapter(PaymentGatewayPort):     # 测试适配器：无外部依赖
    async def charge(self, amount, customer):
        return PaymentResult(success=True, transaction_id="mock-123")

DDD——值对象不可变、聚合根守护不变量、仓储持久化后发布事件：

@dataclass(frozen=True)
class Money:
    amount: int; currency: str          # cents
    def add(self, other):
        if self.currency != other.currency: raise ValueError("Currency mismatch")
        return Money(self.amount + other.amount, self.currency)

class Customer:                          # 聚合根：控制对子实体的访问
    def add_address(self, address):
        if len(self._addresses) >= 5: raise ValueError("Maximum 5 addresses allowed")
        self._addresses.append(address)

控制器只处理 HTTP，委派给用例（薄控制器）：

@router.post("/users")
async def create_user(dto: CreateUserDTO, use_case: CreateUserUseCase = Depends(...)):
    resp = await use_case.execute(CreateUserRequest(email=dto.email, name=dto.name))
    if not resp.success: raise HTTPException(status_code=400, detail=resp.error)
    return {"user": resp.user}

注意事项

规避常见反模式：

• 贫血领域：实体只有数据没有行为。
• 框架耦合：业务逻辑依赖框架。
• 胖控制器：业务逻辑写在控制器里。
• 仓储泄漏：把 ORM 对象直接暴露到外层。
• 缺失抽象：核心层直接依赖具体实现。
• 过度设计：对简单 CRUD 硬套整洁架构。

通用约束：本技能输出不能替代针对具体环境的验证、测试与专家评审；若领域边界、权限、安全边界或成功标准等关键输入缺失，应先停下来澄清。

互见

可配合使用：event-sourcing-architect、saga-orchestration、workflow-automation、dbos-*（持久化执行）。

---

采编自 sickn33/antigravity-awesome-skills（MIT）。