architecture-patterns

架构模式

涵盖整洁架构、后端分层、项目结构约定和测试标准的综合架构验证与强制执行模式。每个类别都有单独的规则文件，按需从 rules/ 加载。来自已退役参考教程的经验教训和有日期记录的决策保存在 references/ork-delta.md 中；教程本身由上游负责（参见下方“上游覆盖范围”）。

快速参考

类别	规则	影响	适用场景
整洁架构	3	高	SOLID 原则、六边形架构、端口与适配器、DDD
项目结构	2	高	文件夹约定、嵌套深度、导入方向、汇总文件
后端分层	3	高	路由器/服务/仓储分离、DI、文件命名
测试标准	3	中	AAA 模式、命名约定、覆盖率阈值
适度设计	2	高	架构级别选择、防止过度设计、结合上下文实施

总计：5 个类别共 13 条规则

快速开始

# Clean Architecture: Dependency Inversion via Protocol
class IUserRepository(Protocol):
    async def get_by_id(self, id: str) -> User | None: ...

class UserService:
    def __init__(self, repo: IUserRepository):
        self._repo = repo  # Depends on abstraction, not concretion

# FastAPI DI chain: DB -> Repository -> Service
def get_user_service(db: AsyncSession = Depends(get_db)) -> UserService:
    return UserService(PostgresUserRepository(db))

# Project Structure: Unidirectional Import Architecture
shared/lib  ->  components  ->  features  ->  app
(lowest)                                    (highest)

# Backend Layers: Strict Separation
Routers (HTTP) -> Services (Business Logic) -> Repositories (Data Access)

整洁架构

面向可维护后端的 SOLID 原则、六边形架构、端口与适配器，以及 DDD 战术模式。

规则	文件	关键模式
六边形架构	rules/clean-hexagonal.md	驱动端/被驱动端端口、适配器实现、分层结构
SOLID 与依赖规则	rules/clean-dependency-rule.md	基于协议的接口、依赖反转、FastAPI DI
DDD 战术模式	rules/clean-ports-adapters.md	实体、值对象、聚合根、领域事件

设计审查清单：checklists/solid-checklist.md。领域实体模板：scripts/domain-entity-template.py。

关键决策

决策	建议
Protocol 与 ABC 的选择	Protocol（结构化类型）
Dataclass 与 Pydantic 的选择	领域层使用 Dataclass，API 使用 Pydantic
仓储粒度	每个聚合根一个
事务边界	服务层，而非仓储层
事件发布	在聚合中收集，在提交后发布

项目结构

基于功能的组织方式、最大嵌套深度、单向导入以及防止使用汇总文件。

规则	文件	关键模式
文件夹结构与嵌套	rules/structure-folders.md	React/Next.js 和 FastAPI 布局、最多嵌套 4 层、汇总文件规则
导入方向与位置	references/structure-import-direction.md	单向导入、防止跨功能导入、组件/钩子的位置

阻断规则

规则	检查项
最大嵌套深度	从 src/ 或 app/ 开始最多 4 层
禁止汇总文件	不允许使用 index.ts 重新导出（会导致 tree-shaking 问题）
组件位置	React 组件只能放在 components/ 或 features/ 中
钩子位置	自定义钩子只能放在 hooks/ 或 features/*/hooks/ 中
导入方向	单向：shared -> components -> features -> app

后端分层

采用路由器/服务/仓储分层和阻断式验证的 FastAPI 整洁架构。

规则	文件	关键模式
分层	rules/backend-layers.md	路由器/服务/仓储边界、禁止模式、异步规则
依赖注入	rules/backend-di.md	Depends() 链、阻断的 DI 模式、违规检测
文件命名与异常	rules/backend-repository.md	命名约定、异步规则、领域异常

此类别的经验教训（异常到 HTTP 状态码映射、导入级违规 grep 检查、DI 覆盖拆除）：references/ork-delta.md。

分层边界

层	职责	禁止事项
路由器	HTTP 相关处理、请求解析、身份验证检查	数据库操作、业务逻辑
服务	业务逻辑、验证、编排	HTTPException、Request 对象
仓库	数据访问、查询、持久化	HTTP 相关处理、业务逻辑

测试规范

遵循测试最佳实践，包括 AAA 模式、命名约定、隔离和覆盖率阈值。

规则	文件	关键模式
AAA 模式与隔离	rules/testing-aaa.md	Arrange-Act-Assert、测试隔离、参数化测试
命名约定	references/testing-naming-conventions.md	面向 Python 和 TypeScript 的描述性、聚焦行为的名称
覆盖率与位置	rules/testing-coverage.md	覆盖率阈值、fixture 作用域，以及（依据 references/ork-delta.md）禁止与源代码放在同一目录的规则

覆盖率要求

范围	最低要求	目标
整体	80%	90%
业务逻辑	90%	100%
关键路径	95%	100%
新代码	100%	100%

适度设计

根据上下文执行后端架构规范。规则会根据 scope-appropriate-architecture 检测到的项目层级调整严格程度。

执行流程：

1. 从 scope-appropriate-architecture 上下文中读取项目层级（在头脑风暴/实现步骤 0 中设置）
2. 如果未设置层级，则使用 Read("rules/right-sizing-tiers.md") 中的信号自动检测
3. 应用基于层级的执行矩阵——跳过针对检测到的层级标记为 OFF 的规则
4. 安全规则不受层级影响——始终强制执行 SQL 参数化、输入验证和身份验证检查

规则	文件	关键模式
架构规模层级	rules/right-sizing-tiers.md	Interview/MVP/production/enterprise 规模矩阵、LOC 估算、检测信号
适度设计决策指南	rules/right-sizing-decision.md	各层级的 ORM、身份验证、错误处理、测试建议及过度设计成本

基于层级的规则执行

规则	Interview	MVP	Production	Enterprise
分层	OFF	WARN	BLOCK	BLOCK
仓库模式	OFF	OFF	WARN	BLOCK
领域异常	OFF	OFF	BLOCK	BLOCK
依赖注入	OFF	WARN	BLOCK	BLOCK
OpenAPI 文档	OFF	OFF	WARN	BLOCK

**手动覆盖：**用户可以显式设置层级以绕过自动检测（例如：“我想在这个 take-home 项目中使用企业级模式来展示能力。”）。

决策流程图

Is this a take-home or hackathon?
  YES --> Flat architecture. Single file or 3-5 files. Done.
  NO  -->

Is this a prototype or MVP with < 3 months runway?
  YES --> Simple layered. Routes + services + models. No abstractions.
  NO  -->

Do you have > 5 engineers or complex domain rules?
  YES --> Clean architecture with ports/adapters.
  NO  --> Layered architecture. Add abstractions only when pain appears.

不适用场景

并非每个项目都需要架构模式。应根据项目层级匹配复杂度：

模式	Interview	Hackathon	MVP	Growth	Enterprise	更简单的替代方案
仓库模式	过度设计（约 200 LOC）	过度设计	临界	合适	必需	在服务中直接调用 ORM（约 20 LOC）
DI 容器	过度设计（约 150 LOC）	过度设计	仅轻量使用	合适	必需	构造函数参数或模块级单例（约 10 LOC）
事件驱动架构	过度设计（约 300 LOC）	过度设计	过度设计	选择性使用	合适	服务之间直接调用函数（约 30 LOC）
六边形架构	过度设计（约 400 LOC）	过度设计	过度设计	临界	合适	带导入语句的扁平模块（约 50 LOC）
严格分层	过度设计（约 250 LOC）	过度设计	警告	阻止	阻止	在同一文件中放置路由和模型（约 40 LOC）
领域异常	过度设计（约 100 LOC）	过度设计	过度设计	阻止	阻止	内置的 ValueError/HTTPException（约 5 LOC）

**经验法则：**如果某个模式对于检测到的层级显示为过度设计，就不要使用它。请采用更简单的替代方案。在 take-home 项目中使用六边形架构体现的是过度设计，而非能力。

反模式（禁止）

# CLEAN ARCHITECTURE
# NEVER import infrastructure in domain layer
from app.infrastructure.database import engine  # In domain layer!

# NEVER leak ORM models to API layer
@router.get("/users/{id}")
async def get_user(id: str, db: Session) -> UserModel:  # Returns ORM model!

# NEVER have domain depend on framework
from fastapi import HTTPException
class UserService:
    def get(self, id: str):
        raise HTTPException(404)  # Framework in domain!

# PROJECT STRUCTURE
# NEVER create files deeper than 4 levels from src/
# NEVER create barrel files (index.ts re-exports)
# NEVER import from higher layers (features importing from app)
# NEVER import across features (use shared/ for common code)

# BACKEND LAYERS
# NEVER use database operations in routers
# NEVER raise HTTPException in services
# NEVER instantiate services without Depends()

# TEST STANDARDS
# NEVER mix test files with source code
# NEVER use non-descriptive test names (test1, test, works)
# NEVER share mutable state between tests without reset

上游覆盖范围（不要重复说明）

本技能中的这些主题长篇教程已移除（2026-07-31 wrap-plus-delta 活动）。请前往一手来源阅读；此处仅保留底线、经验教训和内部决策（参见 references/ork-delta.md）。

主题	一手来源
六边形架构、端口与适配器详解	Alistair Cockburn，https://alistair.cockburn.us/hexagonal-architecture/ 和 Architecture Patterns with Python，https://www.cosmicpython.com/
SOLID 原则教程（基于 Protocol）	Architecture Patterns with Python，https://www.cosmicpython.com/ 和 Python Protocol 规范，https://typing.python.org/en/latest/spec/protocol.html
DDD 战术模式（实体、值对象、聚合、领域事件）	Architecture Patterns with Python，https://www.cosmicpython.com/
FastAPI 依赖注入、身份验证依赖、DI 测试覆盖	FastAPI 文档（context7：/tiangolo/fastapi），https://fastapi.tiangolo.com/tutorial/dependencies/ 和技能 ork:python-backend
路由器／服务／仓储层详解	FastAPI 大型应用，https://fastapi.tiangolo.com/tutorial/bigger-applications/ 和技能 ork:python-backend
完整的 FastAPI 整洁架构示例应用	FastAPI 全栈模板，https://github.com/fastapi/full-stack-fastapi-template
Next.js 文件夹布局和结构违规目录	Next.js 项目结构文档，https://nextjs.org/docs/app/getting-started/project-structure（技能 vercel:nextjs）
AAA 模式、隔离、参数化测试、fixture 作用域、覆盖率配置	技能 ork:testing-unit；pytest 文档，https://docs.pytest.org/en/stable/ 和 Vitest 覆盖率，https://vitest.dev/config/#coverage

相关技能

• ork:scope-appropriate-architecture - 项目层级检测，用于驱动适当的规模约束
• ork:quality-gates - YAGNI 门禁使用层级上下文来验证复杂度
• ork:distributed-systems - 分布式锁、弹性、幂等模式
• ork:api-design - REST API 设计、版本控制、错误处理
• ork:testing-unit - 单元测试：AAA 模式、fixture、模拟、工厂
• ork:testing-e2e - E2E 测试：Playwright、页面对象、视觉回归
• ork:testing-integration - 集成测试：API 端点、数据库、契约
• ork:python-backend - FastAPI、SQLAlchemy、asyncio 模式
• ork:database-patterns - 模式设计、查询优化、迁移