> For the complete documentation index, see [llms.txt](https://zhouhao4221.gitbook.io/haiqing-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zhouhao4221.gitbook.io/haiqing-docs/02-design/architecture-patterns.md).

# 架构模式

AI 驱动工程中常用的架构设计模式。核心问题是：如何让系统结构本身降低 AI 出错的概率。

***

## 核心原则

### 模块化优先

将系统拆分为小型、职责单一的单元。AI 能可靠推理的范围有限，组件边界越清晰，AI 修改它的风险越低。

**判断标准**：向 AI 描述一个模块需要超过三句话，说明边界可能不清。

### 契约优先

先定义接口（API 契约、数据结构、函数签名），再实现。给 AI 明确的目标，而非让它自行推断意图。

**判断标准**：AI 生成的代码偏离了预期接口，说明契约定义不够明确。

### 文档驱动设计

以 AI 可消费的格式记录架构决策。未记录的设计意图对 AI 不可见——它会基于代码推断，而非你的意图。

**判断标准**：AI 审查给出了与已知设计决策冲突的建议，说明这些决策没有文档化。

### 边界显式化

清晰标明系统中 AI 涉及和不涉及的范围。将 AI 生成的代码与人工维护的关键逻辑物理分离。

***

## 分层边界模式

将系统按 AI 参与程度分层，明确每一层的变更规则：

```
┌─────────────────────────────────┐
│  交互层（AI 可自由生成）           │  UI 组件、API 适配器、格式化逻辑
├─────────────────────────────────┤
│  应用层（AI 生成，人工审查）        │  用例、编排、校验
├─────────────────────────────────┤
│  领域层（人工编写，AI 辅助审查）    │  业务规则、核心实体、不变量
├─────────────────────────────────┤
│  基础设施层（人工维护）            │  数据库、外部服务、配置
└─────────────────────────────────┘
```

越往下，AI 修改时需要越强的人工确认。

***

## 接口契约模式

AI 辅助编码时，先定义接口再实现。接口文件位于独立路径，不与实现混在一起：

```
src/
├── contracts/       # 类型定义、接口、枚举 — 人工维护
├── implementations/ # 实现代码 — AI 可生成
└── tests/           # 测试 — AI 生成初稿，人工补全边界情况
```

**规则**：`contracts/` 目录的改动必须经过人工审查，不能由 AI 直接推送。

***

## AI 可读性设计原则

为让 AI 能安全理解并修改代码：

* **函数保持单一职责**：超过 40 行的函数对 AI 推理成本显著上升
* **避免隐式状态**：全局可变状态对 AI 不透明，优先使用显式参数传递
* **错误路径清晰**：异常类型语义明确，AI 才能生成正确的错误处理代码
* **命名反映意图**：`processUserPayment()` 比 `handle()` 给 AI 更多上下文

***

## 边界标注约定

在代码中显式标注 AI 的操作边界：

```typescript
// ---- AI-SAFE: 以下函数可由 AI 生成或修改 ----
export function formatCurrency(amount: number, currency: string): string { ... }

// ---- HUMAN-ONLY: 以下逻辑须人工审查后方可修改 ----
function applyBusinessDiscountRules(order: Order): Order { ... }
```

***

## 架构决策记录（ADR）模板

每次做出重要架构决策时，用以下格式记录并存入 `design-decisions.md`：

```
## 决策：[标题]
背景：需要做什么决策，为什么
选项：考虑了哪些方案
决策：选了什么
后果：这个决策的影响和权衡
AI 参与：AI 在决策过程中承担了哪部分工作
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://zhouhao4221.gitbook.io/haiqing-docs/02-design/architecture-patterns.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.