后端智能体开发规范：基于FastAPI+Dify实战，从零构建可审计、零容错AI工作流

前言：在企业级AI智能体开发中，“AI辅助编码”往往伴随着风格混乱、静默失败、难以溯源等痛点。本文基于「FastAPI + Dify + MySQL」真实教育服务AI项目，总结一套可落地、可审计、强制执行的后端智能体行为规范，覆盖代码风格、错误处理、操作溯源等10大核心模块，已在项目中验证，可直接复制落地，帮团队提升开发效率、降低线上故障。

> 本文核心：拒绝“AI写啥用啥”，用规范约束AI行为，让AI辅助开发贴合企业级工程标准，实现“高效编码+可维护性”双提升。

一、背景：为什么必须给后端智能体定“强制规范”？

我们在开发「教育服务AI智能体系统」时，核心技术栈如下：

  • 业务后端：FastAPI（负责客户研判、日报周报生成、身份认证等核心接口）

  • AI编排平台：Dify（负责员工/老板智能体配置、知识库RAG检索、工作流编排）

  • 辅助工具：Cursor（AI编码辅助，提升接口开发、bug修复效率）

初期未制定规范时，AI辅助开发暴露出诸多问题：代码风格不统一、接口报错无日志、参数类型模糊、线上故障难以定位……为此，我们梳理了一套「零妥协」的行为规范，要求所有AI操作（Cursor辅助编码、Dify节点配置）必须严格执行。

落地效果（真实数据）：

  • PR代码风格问题减少50%+，代码评审效率提升40%

  • 线上错误定位时间缩短60%，无需再逐行排查无日志代码

  • 新成员上手速度提升35%，规范即文档，降低交接成本

二、核心规范总览（10大章节，一目了然）

无需死记硬背，先看总览，后续可直接复用文末模板，按需调整：

章节 核心要求（强制执行）
一、操作溯源记录 每步操作必记，固定日志文件，标准化格式，可追溯、可审计
二、代码风格 纯函数、强类型注解、无默认参数、英文注释，拒绝“松散编码”
三、错误处理 零容错、无静默失败、显式抛出异常、暂停并提供解决方案
四、编码前置检查 默认代码有bug，先分析风险（边界、依赖），再动手编码
五、依赖与类型 Pydantic/接口优先，虚拟环境隔离，禁止全局安装依赖
六、测试策略 集成测试优先，不盲目追求覆盖率，真实验证业务逻辑
七、Git操作 非交互式命令，每完成1个功能点，提示提交并写语义化备注
八、文档 代码即文档，以docstring为主，禁止重复冗余注释
九、沟通 信息不足立即提问，不猜测需求、不画蛇添足
十、红线禁令 10条绝对禁止行为（如修改入参、吞异常、中文注释等）

提示：全文较长，可直接跳过中间细节，拉到文末复制「完整规范模板」，直接用于项目或AI系统提示词。

三、落地实践：FastAPI后端中如何执行规范？（附代码示例）

规范的核心是“可落地”，以下是FastAPI项目中最常用的5个规范实操示例，直接复制即可复用。

3.1 操作溯源记录（强制留痕，关键！）

所有AI操作（分析、设计、编码、测试）必须记录日志，便于后续审计和故障排查。在项目根目录创建「AI_OPERATION_LOG.md」，固定格式如下：

## [001] [分析] 2025-04-27 10:32:15
- 操作内容：阅读客户研判接口 `/customer/judge` 现有代码
- 执行结果：成功，发现逻辑中未处理年龄缺失情况，存在空值崩溃风险

## [002] [设计] 2025-04-27 10:35:22
- 操作内容：设计缺失字段处理方案，兼容age为None的场景
- 执行结果：输出设计文档，增加缺失字段标记（is_missing: bool），不影响原有接口返回格式

## [003] [编码] 2025-04-27 10:40:05
- 操作内容：修改/customer/judge接口，添加age空值处理逻辑
- 执行结果：代码编写完成，通过本地调试，无语法错误

✅ 要求：AI在修改任何代码前，必须先记录「分析步骤」；修改完成后，补充「执行结果」，不允许跳过记录直接编码。

3.2 代码风格规范（避坑示例）

FastAPI项目核心要求：纯函数、强类型、无副作用，以下是正反示例，避免踩坑：

❌ 禁止写法（违反3条规范）：

def process_data(data, flag=True):   # 1.有默认参数；2.无类型注解
    result = []
    for item in data:
        result.append(item)           # 3.未说明是否修改入参，逻辑模糊
    return result

✅ 正确写法（完全符合规范）：

from typing import List

def process_data(data: List[int], flag: bool) -> List[int]:
    """
    Process list of integers based on flag.
    Args:
        data: List of integers to be processed
        flag: If True, multiply each element by 2; else return copy
    Returns:
        New list after processing, does NOT modify input data
    """
    if flag:
        return [x * 2 for x in data]
    return data[:]   # 返回副本，明确不修改入参，无副作用

核心要点：强类型注解（输入+输出）、纯函数（不修改入参）、英文docstring（清晰说明功能）、无默认参数。其中使用英文提示词（含英文注释、英文docstring）有显著优势：一是适配AI工具（如Cursor、Dify LLM）的训练语料特性，减少AI理解偏差，提升辅助编码、字段提取的准确性，结合Cursor支持的Claude 4.6 Sonnet、GPT-5.3 Codex等主流模型，均以英文训练语料为核心，英文提示词能最大化发挥模型性能；二是实现团队协作国际化，避免中文编码乱码问题，同时符合行业通用开发规范，便于后续项目迭代和跨团队交接；三是降低歧义，英文语法严谨，能更精准地描述函数逻辑、参数含义，减少因中文语义模糊导致的开发失误；四是适配FastAPI等主流框架的原生生态，FastAPI官方文档虽有中文版本，但核心API注解、示例代码均以英文为标准，英文提示词能与框架规范保持一致，减少适配成本；五是便于工具解析，各类代码检查工具（如flake8、pylint）对英文注释的解析更精准，可避免中文注释导致的解析异常，提升代码检查效率。为更直观体现优势，以下补充英文与中文提示词的对比示例：

对比示例：函数docstring（同一功能）

❌ 中文提示词（存在问题）：

def process_data(data: List[int], flag: bool) -> List[int]:
    """
    处理整数列表，根据flag参数决定处理方式
    参数：
        data：要处理的整数列表
        flag：如果为真，将每个元素乘以2，否则返回副本
    返回：
        处理后的新列表，不修改原输入
    """
    # 中文注释易出现语义模糊，如“处理方式”未明确，且AI工具解析准确率低
    if flag:
        return [x * 2 for x in data]
    return data[:]

✅ 英文提示词（推荐）：

def process_data(data: List[int], flag: bool) -> List[int]:
    """
    Process list of integers based on flag.
    Args:
        data: List of integers to be processed (non-empty)
        flag: Boolean indicator, multiply elements by 2 if True, return copy if False
    Returns:
        New list after processing, does NOT modify input data (no side effects)
    """
    # 英文语法严谨，参数约束、返回规则清晰，AI工具（Cursor）能精准识别，减少理解偏差
    if flag:
        return [x * 2 for x in data]
    return data[:]

通过对比可见，英文提示词能精准界定参数约束、功能逻辑和返回规则，不仅提升AI工具的辅助效率，也让团队成员（尤其是跨语言团队）能快速理解代码意图，减少沟通成本。这一优势同样适用于后续Dify节点提示词、Cursor规则文件的配置，保持英文提示词的统一性，能进一步降低团队协作成本和AI工具适配成本。

3.3 错误处理模板（零静默失败）

所有外部调用（Dify API、MySQL查询、第三方接口）必须带重试、显式抛出异常，禁止“吞异常”。以下是FastAPI中调用Dify接口的标准模板：

import httpx
from tenacity import retry, stop_after_attempt, wait_exponential
from fastapi import HTTPException

# 全局配置Dify接口地址（从环境变量读取，符合依赖规范）
DIFY_URL = "http://your-dify-instance/api/v1/workflows/run"

@retry(stop=stop_after_attempt(3), wait=wait_exponential(multiplier=1, min=1, max=4))
async def call_dify_workflow(query: str) -> dict:
    """Call Dify workflow to process query, with retry and error handling"""
    try:
        async with httpx.AsyncClient(timeout=30.0) as client:
            resp = await client.post(DIFY_URL, json={"query": query})
            resp.raise_for_status()  # 触发HTTP状态码异常（非200）
            return resp.json()
    except httpx.HTTPStatusError as e:
        # 显式抛出异常，携带上下文，便于调试
        raise HTTPException(
            status_code=e.response.status_code,
            detail=f"Dify API error: {e.response.status_code}, body: {e.response.text}"
        ) from e
    except Exception as e:
        # 捕获其他异常（连接超时等），提供解决方案
        raise HTTPException(
            status_code=500,
            detail=f"Failed to reach Dify after 3 retries: {str(e)}. "
                   "Solution: 1. Check Dify service status; 2. Verify DIFY_URL configuration"
        ) from e

✅ 异常处理要求：

  • 外部调用必须带重试（3次指数退避，避免瞬时故障）

  • 禁止万能try-except（如try: ... except: pass）

  • 异常必须携带上下文（错误信息、状态码），并提供至少2种解决方案

  • 抛出异常后，暂停后续操作，等待用户确认

3.4 编码前置检查清单（避免踩坑）

AI在修改现有代码、新增代码前，必须先输出「风险分析」或「设计方案」，不允许直接动手编码。

示例1：修改现有代码前，输出风险分析：

## 风险分析（修改/customer/judge接口前）
1. 边界条件：当age为None时，现有函数会报TypeError，导致接口500
2. 类型问题：education参数可能是None，但函数未做空值判断，会影响后续逻辑
3. 依赖影响：该接口被/customer/list接口调用，修改返回格式会导致下游异常
4. 兼容性：老版本客户端未处理is_missing字段，需保证返回格式向后兼容

示例2：新增代码前，输出设计方案：

## 设计方案（新增日报提取接口 /report/extract）
1. 功能：接收日报文本，提取结构化数据（工作总结、成果、下一步计划、问题）
2. 输入：report_text: str（必填，非空）
3. 输出：结构化JSON，使用Pydantic模型ReportExtractResponse
4. 异常场景：
   - 文本为空 → 返回400错误，提示“日报文本不能为空”
   - 提取失败 → 返回500错误，提示“提取失败，请检查文本格式”
5. 依赖：调用Dify提取工作流，需配置超时时间（30s）和重试机制
6. 测试要点：需测试空文本、乱码文本、正常文本3种场景

3.5 测试规范（集成测试优先）

拒绝“为了覆盖率写测试”，优先编写集成测试，真实模拟业务场景，以下是FastAPI接口测试示例：

❌ 不推荐（无意义测试，仅凑覆盖率）：

def test_judge_result():
    assert judge_customer({"age": 25}) is not None   # 未验证业务逻辑，无实际意义

✅ 推荐（集成测试，真实验证）：

from fastapi.testclient import TestClient
from sqlalchemy.orm import Session
from app.main import app
from app.models import Customer

client = TestClient(app)

def test_create_customer_integration(client: TestClient, db_session: Session):
    # 模拟真实请求，调用接口
    response = client.post("/api/v1/customer/save", json={
        "name": "李四", "age": 28, "judge_result": 1
    })
    # 验证接口返回
    assert response.status_code == 200
    assert response.json()["code"] == 0
    # 验证数据库写入（真实数据校验）
    db_customer = db_session.query(Customer).filter_by(name="李四").first()
    assert db_customer is not None
    assert db_customer.judge_result == 1

核心要点：集成测试需覆盖“接口调用+数据落地”，不盲目Mock，真实验证业务逻辑。

四、将规范融入Dify工作流（AI编排也需守规矩）

Dify作为AI编排平台，虽不直接执行Python代码，但它的LLM节点、代码节点、HTTP请求节点，同样需要遵守上述规范，避免工作流“失控”。

4.1 LLM节点：系统提示词加入规范摘要

在每个Dify LLM节点（如意图分类、字段提取）的「系统提示词」开头，加入规范约束，强制LLM输出符合要求：

You are a strict assistant for backend AI workflow. Follow these rules strictly:
1. Functional style: No side effects, output only required results.
2. Data format: Output only JSON when requested, no extra text or explanation.
3. Information missing: Do NOT guess; ask for missing information immediately.
4. Error handling: All error messages must include context (input, expected format).
5. Missing fields: Do NOT use default values; output null and mark as missing.

此处使用英文提示词，核心好处在于Dify的LLM节点基于英文训练语料优化，英文指令能减少语义损耗，让AI更精准理解规范要求，避免中文翻译偏差导致的规则执行不到位；同时英文提示词更简洁严谨，能快速界定AI的输出边界，提升工作流执行效率，且便于后续对接国际版AI模型或跨语言团队协作。此外，结合Dify的工作流特性，英文提示词能更好适配其节点交互逻辑，减少因语言适配问题导致的工作流卡顿或执行异常，这与前文代码中英文docstring的优势形成呼应，保持规范执行的一致性。

4.2 代码节点：模拟操作日志留痕

Dify代码节点可将执行步骤写入后端日志接口，实现工作流操作溯源，示例代码：

import requests
import json
from datetime import datetime

def main(query: str):
    # 记录工作流步骤日志
    step_log = {
        "step": "日报字段提取",
        "input": query,
        "timestamp": datetime.utcnow().isoformat() + "Z",
        "status": "processing"
    }
    # 发送日志到FastAPI后端日志接口（可选，实现全局溯源）
    try:
        requests.post("http://your-backend/api/v1/log/ai-operation", json=step_log)
    except Exception as e:
        # 日志发送失败，显式抛出异常，不静默
        raise Exception(f"Log send failed: {str(e)}")
    
    # 实际业务逻辑：调用LLM提取字段
    result = {"work_summary": "完成客户研判", "achievements": ["完成3个客户对接"]}
    
    # 更新日志状态
    step_log["status"] = "success"
    step_log["output"] = result
    requests.post("http://your-backend/api/v1/log/ai-operation", json=step_log)
    
    return result

4.3 错误处理分支：避免工作流静默失败

在每个Dify HTTP请求节点（如调用FastAPI接口）后，必须增加「条件分支」，判断请求状态码，避免工作流“卡壳”或“静默失败”：

HTTP节点（调用FastAPI接口） → 条件分支（判断status_code == 200？）
  ├─ 是 → 正常流程（继续执行后续节点，如LLM字段提取）
  └─ 否 → 错误回复节点（输出：状态码 + 错误信息 + 建议操作）
          → 暂停工作流，等待用户确认后再继续

错误回复节点示例输出：「调用后端接口失败，状态码400，错误信息：日报文本不能为空。建议操作：1. 检查输入文本是否为空；2. 重新提交请求。」

五、Cursor辅助开发：用规则文件强制约束

如果使用Cursor IDE辅助编码，可将规范拆分为3层规则文件，让Cursor自动遵守规范，无需手动提醒。Cursor支持自定义AI规则（Settings > Rules for AI），具体配置如下：

5.1 全局规则（所有项目生效）

- Functional programming: Pure functions, no side effects (do not modify input parameters or global state)
- Strong typing: Forbid Any type, all parameters and return values must have type annotations
- No default parameters: All function parameters are required, no default values allowed
- Comments: Use English only, docstring for all functions/methods

5.2 项目规则（当前FastAPI项目生效，.cursor/index.mdc）

# 教育服务AI后端项目规范（Always生效）
- Tech stack: FastAPI + SQLAlchemy + MySQL + Pydantic
- Layered architecture: Router → Service → Repository → Model
- All database models are defined in models.py
- Configuration: Read from environment variables (do not hardcode)
- API return format: {"code": 0, "message": "success", "data": ...}

5.3 上下文规则（特定场景生效，.cursor/rules/db-operations.mdc）

# 数据库操作规范（仅编写SQLAlchemy代码时生效）
1. Use parameterized queries to prevent SQL injection
2. Pagination: Default limit is 20, support page parameter
3. Avoid N+1 query: Use joinedload for associated queries
4. Transaction: Use db_session.commit() after write operations, rollback on error

配置完成后，Cursor在辅助编码时，会自动遵循上述规则，减少风格问题和错误代码。此处采用英文规则文件，除了契合Cursor的AI交互逻辑（适配英文训练模型，提升规则识别准确率），还能避免中文注释、中文规则在IDE中出现的编码兼容问题，同时与代码中的英文docstring、Dify节点的英文提示词保持一致，形成统一的开发规范，降低团队认知成本，进一步强化英文提示词在全流程中的适配优势。

六、完整规范模板（可直接复制，立即落地）

以下是精简后的完整规范，可直接复制到项目根目录「AI_RULES.md」，或作为AI系统提示词，无需修改即可使用：

# AI 智能体行为规范（强制执行，违者终止操作）

## 一、操作溯源（核心）
1. 每一步操作（分析/设计/编码/测试/命令）必须记录在 `AI_OPERATION_LOG.md`
2. 日志格式：`[序号] [操作类型] 操作内容 → 执行结果`
3. 不允许跳过记录直接执行操作，日志需可追溯、可审计

## 二、代码风格
1. 纯函数：不修改入参、不修改全局状态，无副作用
2. 强类型：禁止Any类型，所有参数、返回值必须有类型注解
3. 无默认参数：所有函数参数均为必填，禁止设置默认值
4. 注释：仅用英文，函数/类必须有docstring，禁止冗余重复注释

## 三、错误处理
1. 零容错：禁止静默失败、禁止万能try-except（try: ... except: pass）
2. 显式抛出：异常必须携带上下文（错误信息、输入参数），便于调试
3. 外部调用：必须带重试（3次指数退避），重试失败后显式抛出异常
4. 错误回复：需提供至少2种解决方案，暂停操作等待用户确认

## 四、编码前置检查
1. 修改代码前：列出所有风险点（边界条件、空值、依赖影响、兼容性）
2. 新增代码前：输出设计方案（功能、输入输出、异常场景、依赖）
3. 未完成前置检查，禁止动手编码

## 五、依赖与类型
1. 数据类型：优先使用Pydantic模型/接口，禁止使用松散字典
2. 依赖管理：依赖必须写入requirements.txt，使用虚拟环境，禁止全局安装
3. 配置：所有配置从环境变量读取，禁止硬编码（如数据库地址、密钥）

## 六、测试
1. 优先编写集成测试/E2E测试，不盲目追求测试覆盖率
2. 测试需模拟真实业务场景，能真实调用接口/数据库则不Mock
3. 新增/修改接口后，必须补充对应测试用例

## 七、Git操作
1. 使用非交互式命令（如git --no-pager diff），避免交互阻塞
2. 每完成1个功能点，提示提交代码，提交信息需语义化（如feat: 新增日报提取接口）
3. 提交前需检查代码是否符合规范，禁止提交违规代码

## 八、沟通
1. 信息不足时，立即提问，不猜测需求、不主观补充功能
2. 不做无意义优化，不画蛇添足（如修改无关代码、新增未要求功能）
3. 反馈问题时，携带上下文（代码片段、错误日志），不模糊描述

## 九、红线禁令（违反立即终止操作）
1. 修改函数入参、全局状态，产生副作用
2. 使用Any类型、设置函数默认参数
3. 静默失败、吞异常（万能try-except）
4. 使用中文注释、冗余重复注释
5. 全局安装依赖、硬编码配置
6. 跳过操作溯源记录，直接编码/执行命令
7. 未做前置检查，盲目修改/新增代码
8. 为凑覆盖率，编写无意义测试用例
9. 猜测需求，主观新增未要求的功能
10. 提交违规代码，不配合规范整改

七、结语

这套规范的核心不是“约束”，而是“提效”——通过标准化AI行为，减少代码评审成本、降低线上故障、提升团队协作效率。我们团队已落地使用2个月，最大的感受是：AI辅助开发从“杂乱无章”变得“可控可审计”，不再需要花费大量时间修改AI写出的违规代码。

建议你根据自己的项目（如电商、医疗、教育等），调整部分规则的严格程度，但操作溯源、错误显式抛出、纯函数这三个核心原则，建议始终保留——它们是保证AI辅助开发“可维护性”的关键。

最后，附上本文相关资源链接，方便大家深入学习：

附加福利：本文完整示例代码（FastAPI接口、Dify节点配置、Cursor规则文件）已上传至Gitee，欢迎star交流，评论区回复“规范”即可获取链接～

如果觉得本文对你有帮助，欢迎点赞、收藏、转发，关注我，后续分享更多FastAPI+AI智能体实战技巧！

# 人工智能 # fastapi
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

Copaw Fork 同步策略：如何避免 Cherry-pick 地狱与协议不兼容

avatar 龙虾开发者社区
cover

WorkBuddy 身份主键设计：如何避免机器人礼貌地做错事

avatar 龙虾开发者社区
cover

Browser Use/Chromium MCP 会话隔离：如何避免跨会话临时文件泄漏？

avatar 龙虾开发者社区