486 lines
25 KiB
Markdown
Executable File
486 lines
25 KiB
Markdown
Executable File
# 12 · Python 开发规范
|
||
|
||
> 适用：本学习项目（FastAPI Agent 服务骨架 + 各阶段离线 Demo）
|
||
> 目的：统一目录、文件、接口、工具函数与各层抽象的命名与组织方式，让代码层次清晰、可读、可持续演进。
|
||
> 约定本规范**面向本项目当前真实结构编写**，不做超出实际需要的理论堆砌。
|
||
|
||
## 1. 项目根布局
|
||
|
||
```
|
||
/workspace
|
||
├─ app/ # FastAPI 服务骨架（阶段七部署到 API 的核心）
|
||
│ ├─ main.py # 应用实例 + 生命周期 + 全局异常处理器
|
||
│ ├─ config.py # pydantic-settings 配置（读取 .env）
|
||
│ ├─ schemas/ # 请求/响应 Pydantic 模型（common.py 统一响应 + 按域拆分）
|
||
│ ├─ dependencies.py # 可复用依赖（Depends：会话 / 鉴权 / 配置）
|
||
│ ├─ api/ # 路由（routers），按资源拆分
|
||
│ ├─ agents/ # Agent 编排层（阶段七扩展）
|
||
│ ├─ tools/ # 工具服务层（LLM / 检索 / 计算）
|
||
│ └─ storage/ # 存储层（Redis / PG / Qdrant）
|
||
├─ code/ # 各阶段离线可运行 Demo（纯标准库优先）
|
||
├─ docs/ # 学习文档（阶段一 ~ 八 + 配套）
|
||
├─ requirements.txt # 服务侧依赖清单
|
||
├─ .env.example # 环境变量模板（.env 不入库）
|
||
└─ .gitignore # 忽略 .env / __pycache__ 等
|
||
```
|
||
|
||
- 三类代码按「**能否被 API 调用**」区分：`app/` 是服务，`code/` 是脚本型 Demo，`docs/` 非代码。
|
||
|
||
- 新增可复用的非服务工具放 `app/tools/`（详见第 5 节），新增教学示例放对应 `code/阶段N/`。
|
||
|
||
- **FastAPI 目录对齐官方 Bigger Applications 惯例**：路由按资源拆到 `api/` 各文件、`dependencies.py` 集中放 `Depends` 依赖、`schemas/` 目录放模型 [$TRAE\_REF](https://fastapi.tiangolo.com/tutorial/bigger-applications/#apirouter)。
|
||
|
||
## 2. app/ 分层架构与各层抽象
|
||
|
||
`app/` 采用**四层**抽象，每个模块只允许依赖其下层，禁止跨层引用：
|
||
|
||
```
|
||
API 接入层 app/api/ 路由 + 请求响应对象（HTTP / SSE）
|
||
↓
|
||
Agent 编排层 app/agents/ 规划 / 记忆 / 工具调用编排（LangGraph 等）
|
||
↓
|
||
工具服务层 app/tools/ 可复用工具函数（llm / 检索 / 计算 ...）
|
||
↓
|
||
存储层 app/storage/ Redis / PG / Qdrant 访问封装
|
||
```
|
||
|
||
```mermaid
|
||
graph TD
|
||
A[API接入层 app/api] --> B[Agent编排层 app/agents]
|
||
B --> C[工具服务层 app/tools]
|
||
C --> D[存储层 app/storage]
|
||
```
|
||
|
||
当前骨架已具备 `app/main.py`、`app/api/routes.py`、`app/schemas/`；`app/agents` / `app/tools` / `app/storage` 按需新增（阶段七扩展时落地）。
|
||
|
||
### 2.1 分层职责与引用规则
|
||
|
||
| 层 | 目录 | 职责 | 允许引用 |
|
||
| ----- | -------------- | ------------------------ | ----------- |
|
||
| 接入层 | `app/api/` | 路由、入参校验、响应序列化、流式返回 | 编排层、schemas |
|
||
| 编排层 | `app/agents/` | 状态机、规划、记忆、工具调用循环 | 工具服务层、存储层 |
|
||
| 工具服务层 | `app/tools/` | 一次性的可复用能力（LLM 封装、检索、计算） | 存储层 |
|
||
| 存储层 | `app/storage/` | Redis / PG / Qdrant 读写封装 | 仅驱动与配置 |
|
||
|
||
- 接入层**不得直接触碰存储层**；编排层**不得写 HTTP 路由**。
|
||
|
||
- 依赖方向永远是单向的，出现「下层 import 上层」即视为架构违规。
|
||
|
||
## 3. 文件命名规范
|
||
|
||
| 类别 | 规则 | 示例 |
|
||
| -------------- | ----------------------------------------- | ----------------------------- |
|
||
| 模块文件 | 小写下划线 `snake_case.py` | `routes.py` / `llm_client.py` |
|
||
| 包目录 | 小写下划线，含 `__init__.py` | `app/api/` / `app/tools/` |
|
||
| 教学 Demo | 语义化小写，一个文件一个主题 | `react_agent.py` |
|
||
| 数据模型 | `schemas/` 目录按域拆分，`__init__.py` 统一导出 | `app/schemas/chat.py` |
|
||
| 可复用依赖 | `dependencies.py`（放 `Depends` 函数） | `dependencies.py` |
|
||
| 常量/配置 | `config.py`（pydantic-settings `Settings`） | `config.py` |
|
||
| 命名 `.markdown` | 中文语义化 + 阶段编号 | `docs/07-…/01-Agent工程化…md` |
|
||
|
||
- 文件名只做一件事：一眼看出「这是什么」「属于哪层/哪阶段」。
|
||
|
||
- `code/` 下避免用 `test` / `utils` / `common` 这类无意义泛名。
|
||
|
||
## 4. 接口（API）规范
|
||
|
||
### 4.1 通用约定
|
||
|
||
- 路由集中注册：`app/api/` 下 `APIRouter(prefix=..., tags=[...])`，统一在 `main.py` `include_router`。
|
||
|
||
- 请求/响应结构一律用 Pydantic 模型声明（`schemas/` 目录），由 FastAPI 自动校验与生成文档。
|
||
|
||
- 健康检查统一 `GET /health`（`main.py` 内），供 K8s probe 使用，不入业务路由。
|
||
|
||
- **`tags`** **必填**：路由按 `tags` 分组，Swagger 文档据此归类，禁止无 `tags` 裸挂。
|
||
|
||
- **显式** **`status_code`**：每个端点声明响应码，避免默认 200 掩盖语义（创建用 201、删除用 204 等）。
|
||
|
||
```python
|
||
# app/main.py
|
||
from contextlib import asynccontextmanager
|
||
|
||
@asynccontextmanager
|
||
async def lifespan(app: FastAPI): # 生命周期：启动/关闭时的资源管理
|
||
# 启动：连库 / 加载模型 / 初始化配置
|
||
yield
|
||
# 关闭：释放连接 / 落盘状态
|
||
|
||
app = FastAPI(title="Python AI Agent 学习项目", version="0.1.0", lifespan=lifespan)
|
||
app.include_router(router) # 挂载 /agent 路由
|
||
app.add_exception_handler(CustomError, custom_handler) # 全局异常处理器
|
||
|
||
@app.get("/health", tags=["system"])
|
||
async def health() -> dict:
|
||
return {"status": "ok"}
|
||
```
|
||
|
||
### 4.2 REST 语义
|
||
|
||
| 场景 | 方法 / 路径 | `status_code` | 说明 |
|
||
| -- | ------------------------------- | ------------- | ---------------------------------- |
|
||
| 对话 | `POST /agent/chat` | 200 | 请求 `ChatRequest`，返回 `ChatResponse` |
|
||
| 创建 | `POST /agent/tasks` | 201 | 创建长任务，返回任务 ID |
|
||
| 查询 | `GET /agent/tasks/{id}` | 200 | 幂等查询，无副作用 |
|
||
| 状态 | `GET /agent/tasks/{id}/status` | 200 | 查询长任务进度 |
|
||
| 取消 | `POST /agent/tasks/{id}/cancel` | 202 | 接受取消请求，异步生效 |
|
||
| 删除 | `DELETE /agent/tasks/{id}` | 204 | 无返回体 |
|
||
|
||
- 动词进 URL 视为反模式：用 `POST /xx/{id}/cancel`，而非 `POST /xx/cancel_task`。
|
||
|
||
- 必须显式声明 `response_model`，FastAPI 据此生成 OpenAPI 与做响应序列化。
|
||
|
||
### 4.3 请求/响应模型（Pydantic v2）
|
||
|
||
```python
|
||
from pydantic import BaseModel, Field
|
||
|
||
class ChatRequest(BaseModel):
|
||
question: str = Field(..., min_length=1, max_length=2000, description="用户问题")
|
||
session_id: str | None = Field(default=None, description="多轮会话 ID")
|
||
|
||
class ChatResponse(BaseModel):
|
||
answer: str = Field(..., description="回答内容")
|
||
source: str = Field(..., description="来源标识: skeleton / rag / tool ...")
|
||
```
|
||
|
||
- 每条 Field 都要有 `description`；校验约束（`min/max_length`）贴近业务真实边界。
|
||
|
||
- 响应模型独立于请求模型，禁止直接复用请求模型回传多余字段。
|
||
|
||
### 4.4 统一响应封装与业务状态码
|
||
|
||
**所有接口成功响应统一用 `ApiResponse` 包装**，结构固定为：
|
||
|
||
```json
|
||
{"code": 0, "message": "成功", "data": { ... }, "trace_id": "abc123"}
|
||
```
|
||
|
||
- 定义位置：`app/schemas/common.py`（`ApiResponse` 泛型 + `BizCode` 枚举）。
|
||
- `code` 为**业务状态码**（与 HTTP 状态码解耦）：`0` 成功，`4xxxx` 客户端侧错误，`5xxxx` 服务端侧错误。
|
||
- `message` 为对调用方可读的状态描述；`data` 成功时携带业务数据、失败时为 `null`；`trace_id` 贯穿日志与存储。
|
||
- 成功用 `ApiResponse.ok(data, trace_id=...)`，失败用 `ApiResponse.fail(BizCode.XXX, ...)`。
|
||
- 业务状态码集中在 `BizCode` 枚举管理，**禁止在代码里散落魔法数字**；新增错误在枚举追加一项。
|
||
|
||
| 业务状态码 | 含义 | 关联异常 |
|
||
|-|-|-|
|
||
| `0` | 成功 | - |
|
||
| `40001` | 参数校验失败 | -（Pydantic 自动 422） |
|
||
| `40101` | 未授权访问 | `UnauthorizedError` |
|
||
| `40301` | 无权限操作 | `ForbiddenError` |
|
||
| `40401` | 资源不存在 | `KnowledgeNotFound` |
|
||
| `42901` | 请求过于频繁 | `RateLimited` |
|
||
| `50201` | 外部依赖失败 | `ToolCallFailed` |
|
||
| `50000` | 服务内部错误 | `AppError` / 兜底 |
|
||
|
||
- 全局异常处理器（`app/errors.py`）已统一输出 `ApiResponse` 结构（`data=null`），HTTP 状态码仍按语义返回（401/403/404/429/502/500）。
|
||
- Pydantic 校验错误（422）保持 FastAPI 默认 `{"detail": ...}` 结构，**不**套业务包装，避免与标准校验语义混淆。
|
||
|
||
### 4.5 流式输出（SSE）——统一协议标准
|
||
|
||
**流式接口与普通接口走两套响应约定**：普通接口统一 `ApiResponse` 包装（见 4.4）；流式接口用 SSE 帧，`event` 字段表达消息语义，负载直接放业务数据，不再重复套 `{code, message, data}`。
|
||
|
||
- 定义位置：`app/schemas/sse.py`（事件类型 `SSEEventType` + 负载模型 + 帧构造 `format_sse`）；帧构造**一律走 `format_sse()`**，禁止在路由里手拼字符串。
|
||
- 响应头固定 `Content-Type: text/event-stream`，接口示例：`POST /agent/chat/stream`（`app/api/routes.py`）。
|
||
- 每帧格式（两行，空行结尾）：
|
||
|
||
```
|
||
event: <事件类型>
|
||
data: <JSON 负载>
|
||
|
||
```
|
||
|
||
- 事件类型与负载模型：
|
||
|
||
| 事件 | 负载字段 | 语义 |
|
||
|-|-|-|
|
||
| `meta` | `session_id` / `model` / `trace_id` | 流开始元信息，固定第一帧 |
|
||
| `message_start` | `{}` | 开始生成回答 |
|
||
| `delta` | `content` | token 增量（按序拼接即完整回答） |
|
||
| `tool_call` | `tool` / `args` | 调用工具 |
|
||
| `tool_result` | `tool` / `result` | 工具返回结果 |
|
||
| `done` | `finish_reason` / `usage` | 正常结束，固定最后一帧 |
|
||
| `error` | `code` / `message` | 中途失败，data 内复用 `BizCode` 的 code/message 语义 |
|
||
| `ping` | `{}` | 心跳保活（应对代理/客户端断流） |
|
||
|
||
- 事件流转约定：`meta → message_start → (delta \| tool_call \| tool_result)* → done`；任一步出错 → 发送 `error` → 再补 `done(finish_reason=error)` 兜底，保证流一定以 `done` 收尾。
|
||
- 长任务（RAG 检索、多步 agent）拆「提交 → 查询进度 → 获取结果」，不用单请求阻塞拖死连接。
|
||
|
||
### 4.6 依赖注入（Depends）——FastAPI 核心机制
|
||
|
||
**凡跨端点复用的横切能力（鉴权、会话、配置、限流），一律用** **`Depends`** **注入，禁止在路由里手动 new 对象**。这是 FastAPI 与普通 Flask/命令式项目的分水岭，也是专业项目结构的基础 [$TRAE\_REF](https://tomodahinata.com/en/blog/fastapi-project-structure-apirouter-dependencies-large-app-guide)。
|
||
|
||
```python
|
||
# app/dependencies.py —— 集中声明可复用依赖
|
||
def get_settings() -> Settings:
|
||
return get_settings.cache # 单例配置注入
|
||
|
||
async def get_tenant(req: Request) -> str:
|
||
"""从 Header/Token 解析租户 ID, 供多租户隔离使用（阶段八 Level5）"""
|
||
token = req.headers.get("X-Tenant-Id")
|
||
if not token:
|
||
raise HTTPException(status_code=401, detail="缺少租户标识")
|
||
return token
|
||
|
||
# app/api/routes.py —— 端点通过 Depends 取依赖
|
||
@router.post("/chat", response_model=ChatResponse, status_code=200)
|
||
async def chat(req: ChatRequest,
|
||
settings: Settings = Depends(get_settings),
|
||
tenant: str = Depends(get_tenant)) -> ChatResponse:
|
||
...
|
||
```
|
||
|
||
- **分层注入**：路由只依赖「抽象依赖函数」；编排层、工具层对象由依赖函数装配，接入层不感知具体实现。
|
||
|
||
- 鉴权、会话、配置、`trace_id` 生成等横切关注点，统一放 `app/dependencies.py`。
|
||
|
||
- 有状态依赖（数据库连接等）用 FastAPI 的依赖缓存（默认每次请求复用同依赖实例）。
|
||
|
||
- **禁止**：在路由函数体内 `Client(...)` 手动构造、绕过 `Depends` 直读全局单例。
|
||
|
||
## 5. 工具函数规范（app/tools）
|
||
|
||
### 5.1 组织原则
|
||
|
||
- 工具按域拆分文件，一个文件一个能力主题：`llm_client.py` / `search.py` / `retriever.py` / `calc.py`。
|
||
|
||
- 工具函数应是**纯函数优先**：输入确定、输出确定、尽可能无隐藏副作用；有外呼（LLM / 外部 API）的单独标注。
|
||
|
||
- 每个工具给**明确的入参、返回类型注解与 docstring**，让 Agent 能可靠调用。
|
||
|
||
```python
|
||
# app/tools/llm_client.py
|
||
import httpx
|
||
|
||
def call_llm(prompt: str, *, base_url: str, api_key: str, timeout: float = 30.0) -> str:
|
||
"""调用 LLM 完成生成。有外呼副作用, 失败抛异常由上层重试。"""
|
||
...
|
||
```
|
||
|
||
### 5.2 工具函数清单（阶段四「工具调用生态」落地）
|
||
|
||
| 工具 | 文件建议 | 输入 → 输出 | 副作用 |
|
||
| ------ | --------------------- | -------------------- | --- |
|
||
| LLM 对话 | `tools/llm_client.py` | `prompt/model → str` | 外呼 |
|
||
| 搜索 | `tools/search.py` | `query → list[dict]` | 外呼 |
|
||
| 检索 | `tools/retriever.py` | `query/向量 → hits` | 读存储 |
|
||
| 计算 | `tools/calc.py` | `expr → number` | 无 |
|
||
| 外部工具 | `tools/*.py` | 各自定义 | 视情况 |
|
||
|
||
- 所有工具函数**统一用关键字参数传可选配置**（`*` 分隔必选与可选），避免位置参数歧义。
|
||
|
||
- docstring 首行一句话说明「它做什么」，第二段提副作用与异常。
|
||
|
||
## 6. 依赖、环境与第三方工具使用
|
||
|
||
### 6.1 依赖与配置
|
||
|
||
- 服务依赖集中在 `requirements.txt`，锁定主版本（如 `fastapi>=0.110`），生产建议 `pip freeze` 出 lock。
|
||
|
||
- `requirements.txt` 是**前瞻声明**：记录服务侧设计需要的依赖，可超前于 `app/` 当前代码的 import；新增依赖先加这里，使用处按阶段落地（`loguru`/`tenacity`/`httpx`/`pydantic-settings` 在阶段四/六/七扩展时启用）。
|
||
|
||
- 密钥与可变配置一律走 `.env`（模板在 `.env.example`）；`.env` **强制不入库**。
|
||
|
||
- 配置统一用 **`pydantic-settings`** 的 `BaseSettings` 管理（FastAPI 官方推荐）[$TRAE\_REF](https://fastapi.tiangolo.com/advanced/settings/#use-the-settings)，禁止在业务模块散落 `os.getenv`。
|
||
|
||
```python
|
||
# app/config.py —— 唯一配置入口, 启动时读取 .env
|
||
from pydantic_settings import BaseSettings, SettingsConfigDict
|
||
|
||
class Settings(BaseSettings):
|
||
app_name: str = "Python AI Agent 学习项目"
|
||
openai_api_key: str = "" # 密钥, 只从 .env 读
|
||
deepseek_api_key: str = ""
|
||
redis_url: str = "redis://localhost:6379/0"
|
||
qdrant_url: str = "http://localhost:6333"
|
||
|
||
model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
|
||
|
||
settings = Settings() # 全应用共享单例
|
||
```
|
||
|
||
- 使用方通过 `Depends(get_settings)` 注入 `Settings`，而不是 `from app.config import settings` 到处 import。
|
||
|
||
- 新增配置项 = 在 `Settings` 加一个带默认值的字段 + 在 `.env.example` 补一行，二处同步。
|
||
|
||
### 6.2 标准工具库约定（对应阶段一「核心工具库」）
|
||
|
||
| 库 | 用途 | 本规范约定 |
|
||
| ------------------- | ------- | ------------------------------------- |
|
||
| `pydantic` | 数据模型与校验 | 所有请求/响应收敛到 Pydantic |
|
||
| `pydantic-settings` | 配置管理 | `config.py` 用 `BaseSettings` 读 `.env` |
|
||
| `loguru` | 日志 | 统一 `logger`，按层打 tag，见第 7 节 |
|
||
| `tenacity` | 重试 | 外呼统一用 `@retry` 做指数退避，见第 8 节 |
|
||
| `httpx` | 异步 HTTP | 取代 `requests`；超时必设，见第 8 节 |
|
||
|
||
## 7. 日志规范
|
||
|
||
- 统一 `from loguru import logger`，不散用 `print`（Demo 教学文件除外）。
|
||
|
||
- 关键路径要能还原现场，至少覆盖：请求进入、工具调用（入参/返回）、失败、耗时。
|
||
|
||
- 日志分级对齐：`debug` 明细、`info` 正常生命周期、`warning` 可恢复、`error` 需关注。
|
||
|
||
```python
|
||
from loguru import logger
|
||
|
||
@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=0.5))
|
||
def call_llm(...):
|
||
logger.info("llm call start, prompt={}", prompt[:50])
|
||
try:
|
||
r = ...
|
||
logger.info("llm call ok, used_tokens={}", r.usage)
|
||
return r
|
||
except httpx.TimeoutException as e:
|
||
logger.warning("llm timeout: {}", e)
|
||
raise
|
||
```
|
||
|
||
- 生产排障依赖日志可检索：每条日志带稳定标识（`trace_id` / `session_id`），见第 9 节。
|
||
|
||
## 8. 错误处理与可靠性
|
||
|
||
### 8.1 异常策略
|
||
|
||
- 业务方法向上抛「语义化异常」而非裸调库异常；接入层统一捕获转 HTTP 状态码。
|
||
|
||
- **外呼必须设超时**：`httpx` 传 `timeout`，LLM / 外部 API 一律默认 `timeout=30.0`。
|
||
|
||
- **外呼统一重试**：用 `tenacity` 指数退避，默认 `stop_after_attempt(3)`、`wait_exponential(multiplier=0.5)`；幂等操作才重试，写操作重试前判幂等。
|
||
|
||
```python
|
||
from tenacity import retry, stop_after_attempt, wait_exponential
|
||
|
||
@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=0.5))
|
||
def fetch(day: str) -> dict: # GET 幂等 → 可安全重试
|
||
...
|
||
```
|
||
|
||
- 时长敏感 / 高风险的调用在编排层用**熔断**（连续失败即快速失败），示例见 `code/阶段七`。
|
||
|
||
- 工具返回空结果必须「如实报空、勿编造」，禁止模型自行补齐不存在的数据。
|
||
|
||
### 8.2 HTTP 错误码映射（接入层）
|
||
|
||
| 异常 | 返回码 |
|
||
| ---------------- | --------- |
|
||
| 参数校验失败（Pydantic） | 422 |
|
||
| 未授权 / 权限不足 | 401 / 403 |
|
||
| 资源不存在（含检索空结果） | 404 |
|
||
| 外部依赖失败（LLM / 存储） | 502 |
|
||
| 请求过于频繁 / 熔断打开 | 429 |
|
||
| 服务内部错误（未分类） | 500 |
|
||
|
||
### 8.3 全局异常处理器（FastAPI 惯用法）
|
||
|
||
- 业务侧抛**自定义异常**（如 `ToolCallFailed`、`KnowledgeNotFound`），接入层用 `@app.exception_handler` 统一转 HTTP 响应，路由内不散落 try/except 转码。
|
||
|
||
- 通用异常处理收敛到 `main.py` 或独立 `app/errors.py`，避免每个路由重复写错误映射。
|
||
|
||
```python
|
||
# app/errors.py —— 集中定义自定义异常与全局处理器
|
||
class AppError(Exception):
|
||
biz_code: BizCode = BizCode.INTERNAL_ERROR # 关联业务状态码
|
||
http_status: int = 500
|
||
|
||
class ToolCallFailed(AppError):
|
||
biz_code = BizCode.TOOL_FAILED # 50201 → HTTP 502
|
||
http_status = 502
|
||
|
||
# main.py 注册（register_exception_handlers 统一注册）
|
||
# 处理器输出统一 ApiResponse 结构，HTTP 状态码按语义返回：
|
||
# {"code": 50201, "message": "外部依赖失败", "data": null, "trace_id": ...}
|
||
```
|
||
|
||
- Pydantic 校验错误由 FastAPI 自动转 422，无需自定义；只对**业务异常**注册处理器。
|
||
|
||
## 9. 可追踪性与并发
|
||
|
||
- 每个请求注入 `trace_id`（如 `uuid4().hex[:8]`），贯穿日志与存储，跨链路可对。
|
||
|
||
- 多租户 / 会话用稳定键区分：`app/agents` 里 `thread_key(<tenant> , <session>)` 组合，见阶段八 Level5。
|
||
|
||
- 异步敏感路径用原生 `async/await`（FastAPI / httpx 天然支持）；CPU 密集用 `asyncio.to_thread` 不阻塞事件循环。
|
||
|
||
## 10. 代码质量与提交
|
||
|
||
| 项 | 约定 |
|
||
| --------- | -------------------------------------- |
|
||
| Python 版本 | 3.10+，语法用现代类型注解（`str \| None`） |
|
||
| 格式 | `ruff format` 统一风格 |
|
||
| Lint | `ruff check`，消灭未用变量 / import 与未处理异常 |
|
||
| 类型 | 函数/参数/返回值全部注解 |
|
||
| 文档串 | 每个公开函数有 docstring，首行一句话说明意图 |
|
||
| 测试 | 关键接口配 `pytest` 单测；数据类用 Pydantic 校验即测边界 |
|
||
| 提交信息 | 一句话 present 动作，如 `fix: 修复流式接口内存泄漏` |
|
||
|
||
## 11. 各类代码的定位（避免误用）
|
||
|
||
| 位置 | 定位 | 应避免 |
|
||
| ----------- | ------------- | --------------------- |
|
||
| `app/` | 生产风格服务，遵循以上规范 | 用 `print`、裸读 env、跨层引用 |
|
||
| `code/阶段N/` | 教学 Demo，重可读性 | 上生产的依赖（环境变量强绑定） |
|
||
| `docs/` | 文档，不动代码 | 混入可执行逻辑 |
|
||
|
||
- Demo 的注释可以比生产多（教学），但**命名与分层原则一致**，便于从 Demo 平滑迁移到 `app/`。
|
||
|
||
## 12. 防过度设计（底线准则）
|
||
|
||
**前提**：本仓库是「学习项目 + 生产骨架」的混合体，最大的基建风险是「为将来做准备」而把抽象、分层、依赖做过头。以下为不可逾越的底线，新增任何结构先对照自检。
|
||
|
||
### 12.1 一句话原则
|
||
|
||
> 抽象必须服务当下的真实代码；基础设施按真实的触发时机建，不为「看起来更规范」提前预埋。
|
||
|
||
### 12.2 八条红线
|
||
|
||
1. **抽象必须有当下的受益者。** 每新增一层（service / repository / 中间件 / 基类 / 装饰器）先回答：现在有没有调用方？没有受益者的空壳就是为抽象付费（如尚无业务时的空 `app/services/`）。
|
||
2. **推迟到触发时机，而非提前预埋。** 详见「12.3 推迟清单」：基础设施按真实需求点再建。
|
||
3. **单一职责，但不为细分而细分。** 一个文件承载一个完整职责是允许的；按「读的人会不会迷路」判断是否拆分，而非按行数或「内聚感」。
|
||
4. **分层方向是硬约束，层数是软约束。** 依赖单向（`api → agents → tools → storage`）必须遵守；各层内部是否再分子层，交由实际复杂度决定。
|
||
5. **全局机制给一次、做对。** 统一响应、SSE 协议、异常转码、trace_id 等横切机制每个只实现一次，后续一律复用、禁止绕行。临时造轮子（手拼 SSE 帧、散落 `os.getenv`）是漏不是省。
|
||
6. **依赖与配置从简起步。** 新增依赖必须有当下真实用途；新增配置项 = `Settings` 加字段 + `.env.example` 补一行。
|
||
7. **扩展点「留位置」，不要「做实现」。** 预留好位置（如 SSE 已定义 `tool_call / tool_result / ping` 事件）但不预写将返工的实现。
|
||
8. **怀疑自己的编辑器视野。** 「加一层更规范」的冲动，未必是让此时读者更清楚，可能只是满足外部「最佳实践」印象。
|
||
|
||
### 12.3 本仓库推迟清单（照此执行，暂不实现）
|
||
|
||
| 结构 | 触发时机（再开始建） |
|
||
| ---- | ------------------------------------------------------------ |
|
||
| Alembic 迁移 | 第一张真实业务表出现时 |
|
||
| `/readyz` 就绪探针 | 存储/外部依赖接入后 |
|
||
| API Key 鉴权 Depends | 服务对外开放时 |
|
||
| 会话态持久化（Redis） | 多 worker 真正需要共享状态时 |
|
||
| RAG 相关超出 import 的深层封装 | 阶段四 RAG 落地时 |
|
||
| service / repository 层 | 出现明确的跨用例业务复用点时 |
|
||
| K8s manifests / CI 流水线 | 部署到集群前 |
|
||
|
||
### 12.4 自查三问（新增抽象前）
|
||
|
||
1. 这个抽象现在有没有至少一个真实调用方？
|
||
2. 把它推迟一个月，会有多少返工成本？（< 半天 → 推迟）
|
||
3. 去掉它，谁会读不清代码？
|
||
|
||
三问全过再动手；有一问存疑，先写下意图、引入真实触发时机后再实现。
|
||
|
||
## 13. 小结自检
|
||
|
||
- [ ] 新代码归属明确（`app/` 服务 / `code/` 教学），模块命名一眼可辨
|
||
|
||
- [ ] 接入层不碰存储、编排层不写路由，依赖单向
|
||
|
||
- [ ] 所有接口用 Pydantic 声明请求/响应，字段带 `description`
|
||
|
||
- [ ] 路由带 `tags` 分组 + 显式 `status_code`，`main.py` 只做组装
|
||
|
||
- [ ] 横切能力（鉴权/会话/配置）用 `Depends` 注入，不手动 new 对象
|
||
|
||
- [ ] 配置用 `pydantic-settings`，密钥走 `.env` 不入库
|
||
|
||
- [ ] 业务异常用全局 `exception_handler` 统一转码
|
||
|
||
- [ ] 外呼统一设超时 + `tenacity` 重试，空结果如实报空
|
||
|
||
- [ ] 统一 `loguru` 日志 + `trace_id`
|
||
|