第一章：后端开发概述——三层价值模型与项目结构

“AI在后台开发中的价值不是单层的，而是分层的：从驱动规范，到辅助开发，到集成AI能力。”

1.1 什么是"后端Agent开发"

在本书里，"后端Agent开发"指的是两件事的结合：

层次一：用AI Agent工具构建后端代码

用Claude Code、Cursor等工具，以自然语言描述需求，让AI生成、审查、重构后端代码。大多数人用得很浅——只用AI做代码补全或者回答语法问题，而没有把AI当作真正的"协作开发者"。

层次二：在后端服务中集成AI能力

让你的后端能调用LLM API（OpenAI、Anthropic）、处理流式响应、实现Tool Use（让LLM调用你的业务函数），把AI能力变成你的产品功能。

本书两个层次都覆盖，因为在2026年，作为后端开发者，两者都需要。

1.2 三层价值模型

第三层：AI能力集成（你的产品提供AI功能）
         ↑
第二层：AI辅助开发（AI帮你写代码，你审查决策）
         ↑
第一层：AI驱动规范（用AI维护代码约束、文档、架构一致性）

第一层：AI驱动规范

这一层通常被忽视，却是基础。通过CLAUDE.md（项目级AI指令文件）、代码注释规范、迁移脚本、架构决策记录，让AI在整个项目中始终在同一个框架下工作。

没有这一层，AI每次都在"猜"你的代码风格和约束，产出质量不稳定。有了这一层，AI知道你用SQLAlchemy 2 async，知道业务逻辑在services/里，知道不能用asyncio.gather()在同一个session上并发查询。

第二层：AI辅助开发

把AI当成一个"知道你整个codebase"的协作者，而不是只负责生成代码片段的工具。Claude Code能读取整个项目目录，理解现有代码的模式，生成符合你现有风格的新代码。

第三层：AI能力集成

你的产品里有AI功能——文本生成、图片分析、智能分类、自动化操作。后端需要负责：调用AI API、处理长时间运行的AI任务、管理API成本和配额、给用户提供流式响应体验。

1.3 为什么选FastAPI + SQLAlchemy 2 Async

FastAPI

Python生态中最接近"真实生产可用"的高性能框架
原生支持async/await
自动生成OpenAPI文档（Swagger）
Pydantic v2深度集成，数据校验零样板代码
AI工具对它的理解质量是Python框架中最好的

SQLAlchemy 2 async

ORM的async支持在2.0版本才真正稳定可用
Async Session + Async Engine让数据库操作不阻塞事件循环
丰富的关系映射能力，AI对它的支持质量极高

PostgreSQL

功能最完整的开源关系数据库
JSONB支持让schema-less字段的需求不需要引入MongoDB
全文搜索、地理位置、数组类型等高级功能
生产可靠性经过几十年验证

这个组合最重要的特性：它们都是"AI支持质量最好"的选项。

1.4 项目结构：标准目录布局

graph TD
    A[app/] --> B[api/v1/endpoints/]
    A --> C[models/]
    A --> D[schemas/]
    A --> E[services/]
    A --> F[core/]
    A --> G[db/]

    B --> B1[auth.py]
    B --> B2[users.py]

    C --> C1[base.py]
    C --> C2[user.py]

    D --> D1[user.py]

    E --> E1[user_service.py]

    F --> F1[security.py]
    F --> F2[exceptions.py]

    G --> G1[session.py]

最重要的架构规则：

路由层（api/）只做三件事：参数校验、Depends注入、调用Service。业务逻辑和数据库操作全部在services/里。 models/只定义ORM映射，不包含任何业务逻辑。

1.5 配置AI工具

在项目根目录创建CLAUDE.md：

# 项目架构规则

## 技术栈
Python 3.12, FastAPI 0.115, SQLAlchemy 2.0 async, Pydantic v2, Alembic, PostgreSQL 16

## 关键约束
- 所有业务逻辑和数据库操作放在 app/services/
- 路由层只做参数校验和 Depends 注入，不直接操作 DB
- 禁止在单个 AsyncSession 上使用 asyncio.gather()
- 新功能开发顺序：Model → Schema → Service → Route → Test
- 单文件超过 300 行时必须拆分

## 代码风格
- 类型注解完整（所有函数参数和返回值）
- 异步函数使用 async/await，不使用 threading
- 错误处理：业务异常用 HTTPException，系统异常记录到 Sentry

这个文件让Claude Code在整个项目中都遵守你的约束，不需要每次都手动说明。

本章小结

后端Agent开发 = AI辅助开发 + AI能力集成
三层价值模型：规范 → 开发 → 集成
FastAPI + SQLAlchemy 2 async + PostgreSQL：AI支持最好的组合
路由-Service分离：业务逻辑在services/，路由只做校验
CLAUDE.md是基础：让AI在整个项目中遵守同一套约束

本章提示词模板

生成CLAUDE.md

请帮我为以下技术栈的项目生成CLAUDE.md文件：

技术栈：
- 后端框架：FastAPI 0.115
- ORM：SQLAlchemy 2.0 async
- 数据库：PostgreSQL 16
- 数据校验：Pydantic v2
- 迁移工具：Alembic

请包含：
1. 技术栈版本说明
2. 关键架构约束（特别是禁止的模式）
3. 开发顺序规范
4. 代码风格要求
5. 错误处理规范

设计项目结构

请为以下场景设计FastAPI项目结构：

场景：SaaS平台，包含用户认证、项目管理、订阅计费、AI功能集成

技术栈：FastAPI + SQLAlchemy 2 async + PostgreSQL

请输出：
1. 完整的目录结构
2. 每个文件的功能说明
3. 关键的架构规则
4. 推荐的AI配置文件内容

→ 继续阅读：第二章：数据模型设计