Phase 5：后端分层与代码实现

后端是业务的骨架。骨架清楚，肉和皮才有地方长。

分层清晰的好处不只是代码好看，更重要的是：你和 AI 都能独立理解每一块，改起来不怕牵一发而动全身。

---

一、这个阶段要做什么

基于架构设计和技术选型，把后端代码搭起来。产出可运行的 API 和数据库 Schema。

---

二、推荐的分层

text
路由层（Routes）      ← HTTP 入口，参数校验
服务层（Services）    ← 业务逻辑编排
工具层（Tools）       ← 外部系统调用
数据层（Repository）  ← 数据库操作
基础设施层           ← LLM 客户端、配置、日志

依赖方向永远向下：上层调用下层，下层不回调上层。

---

三、每层具体做什么

路由层

接收 HTTP 请求，校验参数，调用 Service，返回统一响应。路由层里不要写业务逻辑。

服务层

放业务逻辑。编排 Tools 和 Repository，处理事务和错误。这是最需要你仔细看的一层。

工具层

封装所有外部调用：邮件、日历、搜索、第三方 API。每个工具实现统一接口，方便 mock 和替换。

数据层

所有数据库操作集中在这里。上层不需要知道用的是 PostgreSQL 还是 SQLite。

基础设施层

LLM Provider 抽象、配置读取、日志、缓存、队列。这些东西不直接参与业务，但到处都需要。

---

四、给 AI 的输入

hljs markdown
## 架构文档
[粘贴 ARCHITECTURE.md]

## 技术栈
[粘贴 TECH-STACK.md]

## 请实现
1. 数据库 Schema
2. 核心 API 路由
3. Service 层骨架
4. 一个 Tool 的示例实现
5. Repository 接口及实现

## 要求
- 使用 [你的技术栈]
- 包含错误处理
- 包含基础测试

---

五、几个关键代码模式

统一响应格式

hljs typescript
interface ApiResponse<T> {
  success: boolean;
  data?: T;
  error?: string;
  meta?: { total: number; page: number };
}

LLM Provider 抽象

hljs typescript
interface LLMProvider {
  complete(options: CompletionOptions): Promise<LLMResponse>;
  stream(options: CompletionOptions): AsyncIterable<LLMChunk>;
}

Tool 接口

hljs typescript
interface Tool {
  name: string;
  description: string;
  parameters: object;
  execute(args: unknown, context: ToolContext): Promise<ToolResult>;
}

---

六、数据库设计的几个原则

先满足查询需求

根据 API 反推 Schema，不要先设计完美的范式。

适当冗余

该反范化就反范化，不要为了第三范式牺牲性能。

时间戳必备

created_at、updated_at 几乎总是需要。

软删除

重要数据不要物理删除，加 deleted_at 或 status 字段。

Schema 变更走迁移

手动改表结构是大忌，用迁移脚本管理。

---

七、和 AI 协作的方式

先给接口契约

"API 契约已经确定，请你先写 Service 层，不要碰路由和数据库。"

分模块实现

"今天只做 User 模块：注册、登录、获取资料。其他模块不要动。"

要求测试

"每个 Service 函数配一个单元测试，覆盖正常和异常路径。"

错误处理要明确

"错误要分类：用户错误 400、系统错误 500、外部错误 502。"

---

八、什么时候算做完了

• 核心 API 可运行
• 数据库 Schema 已创建
• Service 层覆盖主要业务逻辑
• 至少一个 Tool 实现完成
• 单元测试通过
• 错误处理完整

---

九、几个常见错误

业务逻辑散在路由里

• 后果：难以测试和复用
• 修正：集中到 Service

直接调用外部 API

• 后果：测试困难
• 修正：封装 Tool 层

忽略错误处理

• 后果：线上崩溃
• 修正：每层显式处理

不写测试

• 后果：改一处崩一处
• 修正：先写测试再改代码

---

十、输出文件

text
/src/
├── routes/
├── services/
├── tools/
├── repositories/
├── infrastructure/
└── tests/

/docs/
└── API.md

---

十一、下一步

后端骨架搭好后，进入 Prompt 工程阶段。

→ Phase 6 Prompt 工程与 AI 协作