如何避免"AI写代码3分钟，调试3天"？AI编程助手的"大脑说明书"：主流工具规则配置全景指南

(适合所有级别程序员必备的AI协作规范)

核心洞察：规则配置文件 = AI编程助手的"项目宪法"。配置得当，代码生成准确率提升60%+，团队协作效率翻倍

大家好！在AI编程助手席卷开发界的今天，你是否遇到过这些痛点：

• AI生成的代码风格与团队规范不符
• 它不知道你用的内部框架和自定义API
• 每次都要重复解释项目结构和技术栈
• 生成的代码包含安全漏洞或过时写法

根本原因：你没给AI写"说明书"！就像新同事入职需要培训手册，AI编程助手也需要项目规则文件来理解上下文。今天，我将带你全面了解主流AI编程工具的规则配置机制，让你从“调教AI”、“AI写代码3分钟，调试3天”的泥潭中解脱出来。

---

🌟 一、为什么需要项目规则文件？

传统开发中，团队通过代码审查、文档和口头交流来统一规范。但AI助手没有这些渠道——它只能通过显式规则理解你的项目。

数据说话：

• 配置完善的规则文件可减少40%的代码审查修改
• 企业级团队反馈：规则文件让AI生成代码的首次通过率提升65%
• 未配置规则的AI工具，30%的生成代码需要重大重构

💡 初中级程序员特别提示：别以为这是高级话题！从第一个项目开始写规则文件，能避免养成坏习惯，让你更容易融入团队协作。

---

🛠️ 二、主流AI编程工具规则配置对比

1. Cursor：最精细的规则控制系统

Cursor以其强大的上下文管理著称，规则配置最为完善。

配置方式：

• 项目规则：.cursor/rules/目录下的多个.md文件（可版本控制）
• 用户规则：全局生效的个人偏好设置
• 文件引用：使用@file语法将特定文件纳入上下文

核心特性：

# .cursor/rules/core.md
## 项目架构
- 前端：React 18 + TypeScript
- 后端：Node.js 20 + Express
- 数据库：MongoDB Atlas

## 代码规范
- 组件命名：PascalCase（如UserProfileCard）
- API调用：必须使用utils/api.js中的封装函数
- 禁止：直接操作DOM，必须用React Hooks

独特优势：

• 支持路径模式限定：src/components/*.tsx只应用前端规则
• 规则文件可分类管理：database.md、api.md、security.md分离关注点
• 支持手动调用特定规则，避免上下文过载

✅ 实战建议：从core.md开始，逐步添加模块化规则。新手可参考awesome-cursorrules社区模板

---

2. GitHub Copilot：企业级集成方案

作为GitHub官方工具，Copilot的规则配置注重企业级集成。

配置方式：

• 仓库级指令：.github/copilot-instructions.md
• VS Code设置：通过Copilot Chat的Custom Instructions面板
• 工作区上下文：使用@workspace命令动态提供上下文

配置示例：

# .github/copilot-instructions.md
## 项目上下文
- 这是一个电子商务平台，使用Next.js 14
- 核心功能：商品展示、购物车、支付集成
- 部署环境：Vercel + AWS Lambda

## 安全要求
- 所有API端点必须验证JWT
- 禁止在客户端存储敏感数据
- 数据库查询必须使用参数化查询

独特优势：

• 与GitHub生态深度集成，自动识别仓库结构
• 支持多级配置：组织级→仓库级→用户级指令
• 通过Model Context Protocol (MCP)智能收集上下文

✅ 实战建议：大团队优先使用仓库级指令，个人项目用VS Code自定义指令。注意指令长度限制，保持在200行以内

---

3. AWS CodeWhisperer：企业安全定制

CodeWhisperer主打企业安全，规则配置强调组织级管控。

配置方式：

• 组织定制化：管理员连接GitHub/GitLab/Bitbucket仓库
• AWS Toolkit配置：在IDE中控制定制化程度
• 内部API训练：包含企业专有库和框架

核心流程：

1. 管理员通过AWS CodeStar Connections连接代码仓库
2. 选择要包含的内部库和API文档
3. 生成定制化模型，团队成员自动继承

独特优势：

• 安全合规：支持自管理加密密钥保护定制文件
• 企业级集成：与AWS IAM、S3等服务深度整合
• 适合遗留系统现代化：能理解企业内部框架

⚠️ 注意：CodeWhisperer定制需要企业账户，个人开发者建议用其他工具。定制过程需要管理员权限

---

4. Tabnine：隐私优先的灵活方案

Tabnine以代码隐私著称，规则配置支持私有部署。

配置方式：

• MCP服务器：通过.tabnine/目录下的JSON配置文件
• 上下文感知：自动分析项目中的测试框架和代码模式
• 企业部署：支持云、本地或隔离环境部署

配置示例：

// .tabnine/mcp-config.json
{
  "context_providers": [
    {
      "name": "project_structure",
      "path_patterns": ["src/**/*.ts", "tests/**/*.ts"]
    },
    {
      "name": "coding_standards",
      "file_path": "CODING_STANDARDS.md"
    }
  ]
}

独特优势：

• 隐私保障：代码永不离开本地环境
• 灵活部署：适合金融、医疗等高合规要求行业
• 上下文理解能力强，能自动识别项目测试框架

✅ 实战建议：重视隐私的团队首选Tabnine。个人开发者可从简单规则开始，逐步添加上下文提供器

---

5. Qoder：12-Factor方法论实践者

配置方式：

• 双模式支持：.qoder/rules/*.md（多文件）或AGENTS.md（单文件）
• 12-Factor启发：系统化覆盖项目各个维度
• 跨平台一致：IDE、CLI、JetBrains插件统一支持

核心框架：

## I. Codebase
- 语言：Java 25
- 框架：Spring Boot 4.0
- 构建工具：Maven 3.9.11

## II. Dependencies
- com.fasterxml.jackson.core:jackson-databind:2.20.1: JSON序列化
- com.github.ben-manes.caffeine:caffeine:3.2.3: 内存缓存

## III. Config
- 配置文件：application.yml
- 环境变量：DB_URL, API_KEY（禁止硬编码）

独特优势：

• 方法论驱动：借鉴12-Factor App，结构清晰
• 新手友好：500行以内最佳实践 [[用户输入]]
• 渐进完善：从核心要素开始，逐步补充细节

---

让AI编程助手读懂你的代码：用12-Factor思想写好Qoder规则指南

一句话核心：项目规则文件 = 给AI的「代码说明书」。写得好，AI生成的代码准确率提升50%+

本文重点聊聊一个被90%开发者忽略的神器——Qoder的项目规则文件。当你用AI编程助手（比如Qoder）时，它其实是个“空杯新人”。没有说明书，它连你的项目用Java还是Python都分不清，更别说生成符合规范的代码了。

最近Qoder团队做了件超实用的事：把12-Factor App方法论改造成了AI专用指南。作为每天和Qoder打交道的工程师，我亲测这套方法让AI犯的低级错误减少了大半。下面用初中级程序员也能秒懂的方式拆解：

---

🔑 两种规则文件？选一个坚持用！

Qoder支持两种写法（效果完全相同）：

方式	存放位置	适合场景
Qoder Rules	.qoder/rules/*.md	大型项目，需要分模块描述
AGENTS.md	项目根目录下的单个文件	快速上手，简单项目首选

✅ 新手建议：直接用AGENTS.md（单文件更省心），最新版Qoder全平台支持

---

🧩 用12-Factor思维写规则（AI特供版）

传统12-Factor是给运维看的，我们提炼出7个AI最需要的要素。下面用「电商项目」举例：

I. Codebase：项目身份证

## 代码基础
- 语言：Java 17（非Java 8！）
- 框架：Spring Boot 3.2 + Spring MVC
- 构建工具：Maven 3.8
- 项目结构：
  src/main/java/com/shop
  ├── controller  # REST接口
  ├── service     # 业务逻辑
  └── repository  # 数据库操作

💡 关键点：明确技术栈版本！AI会混淆Spring Boot 2.x和3.x的写法

II. Dependencies：依赖说明书

## 关键依赖
- com.stripe:stripe-java:24.0.0 → 支付模块（生成支付链接用）
- org.redisson:redisson-spring-boot-starter:3.24 → 分布式锁（所有库存操作必须用！）

⚠️ 血泪教训：给每个依赖加用途注释。曾因没写Redis用途，AI把缓存逻辑塞进了Controller…

III. Config：配置地图

## 配置文件
- 核心配置：`application-prod.yml`（生产环境）
- 敏感变量：  
  STRIPE_SECRET_KEY（支付密钥，**禁止硬编码**！）  
  REDIS_HOST（Redis地址）

🔒 安全提示：.env文件通常被.gitignore忽略，必须手动列出关键变量名

IV. Backing Services：外部服务清单

## 数据库与中间件
- 主库：PostgreSQL 15（连接池用HikariCP）
- 缓存：Redis 7（集群模式，密码在K8s Secret）
- 消息队列：RabbitMQ（订单超时用delayed-exchange）

🌐 AI痛点：不声明服务版本，AI可能用过时的Redis命令（比如用SETNX代替Redisson锁）

V. Build & Run：启动说明书

## 构建与运行
- 本地启动：`mvn spring-boot:run -Dspring-boot.run.profiles=dev`
- 跳过测试打包：`mvn package -DskipTests`
- **禁止**直接运行Main类！

🚫 曾因没写这条，AI生成了public static void main覆盖了Spring Boot启动类…

VI. Port Binding：端口说明书

## 端口分配
- 8080：用户API（/api/v1/*）
- 9000：Admin后台（需鉴权）
- **禁止**修改Actuator端口（安全审计要求）

VII. Logs：日志规范

## 日志要求
- 框架：SLF4J + Logback
- 约定：  
  ✅ 用`log.error("支付失败, orderId={}", id, e)`  
  ❌ 禁止用System.out.println()
- 关键操作必须INFO级别记录（如下单、退款）

📌 真实案例：AI在生产环境打印密码，就因规则没强调日志规范

---

✨ 两条黄金法则（新手必看）

1. 500行生死线：
   Agent上下文窗口有限！Qoder团队实测超过500行的规则文件效果断崖下跌。只写关键项，别当小说写。

   ✅ 正确示范：用「-」列表代替大段描述
   ❌ 错误示范：粘贴整个技术设计文档

2. 渐进式完善：
   不必一次性写完美。当AI连续犯同类错误时（比如总用错缓存API），立刻补充对应规则。我的AGENTS.md是这样成长的：

   - v1：只写了Java版本
   + v2：增加了Redis依赖说明
   + v3：补充了支付模块安全规范
   

---

🚀 你的行动清单

1. 在项目根目录创建AGENTS.md（5分钟就能写完基础版）
2. 重点填写：语言版本+关键依赖+项目结构+端口（这4项解决80%问题）
3. 下载最新Qoder（支持IDE/CLI/插件全平台）

最后一句真心话：写规则文件不是给AI打工，而是把重复沟通的成本一次性买断。上周我花20分钟写规则，省下了3小时修AI生成的bug——这笔账，初中级程序员更该算清楚。

Happy qoding！
—— Qoder工程师老张（5年Java，现专注AI提效）

附：最小可用AGENTS.md模板

## Codebase  
- 语言：Python 3.10  
- 框架：Django 4.2  
- 项目结构：  
  myproject/  
  ├── apps/user  # 用户模块  
  └── core/utils.py  # 通用工具  
  
## Dependencies  
- django-rest-framework:4.0 → 所有API必须用DRF Serializer  
  
## Ports  
- 8000: Web服务  

🎯 三、跨工具通用规则配置最佳实践

1. 核心要素清单（所有工具必备）

无论使用哪种工具，规则文件必须包含：

## 📋 项目基础
- 语言 & 版本（精确到小版本！）
- 核心框架 & 版本
- 项目架构（目录结构图）

## 🔌 依赖说明
- 关键依赖包 + 版本 + 用途说明
- 内部框架/库的特殊用法
- 禁止使用的过时API

## 🔐 安全规范
- 敏感数据处理规则
- 认证授权标准
- 输入验证要求

## 🧪 质量要求
- 测试框架 & 覆盖率要求
- 代码审查要点
- 性能约束（如响应时间<100ms）

2. 避免的常见陷阱

• ❌ 过于冗长：AI上下文窗口有限，超过500行效果断崖下跌
• ❌ 模糊表述：避免"代码要优雅"，改为"函数不超过50行，圈复杂度<10"
• ❌ 忽略版本：不指定版本号，AI可能使用过时API
• ❌ 静态文档：规则文件需要随项目演进持续更新

3. 渐进式完善策略

新手（1-3天）：

# 最小可用规则
## 项目基础
- 语言：Python 3.10
- 框架：Django 4.2
- 项目结构：
  myproject/
  ├── apps/user
  └── core/utils.py

中级（1周）：

• 添加关键依赖说明
• 补充安全规范
• 定义端口和服务暴露规则

高级（持续迭代）：

• 按模块拆分规则文件
• 添加性能优化指南
• 集成CI/CD流水线要求

---

🚀 四、行动指南：30分钟提升你的AI开发体验

Step 1：选择适合的工具

场景	推荐工具	原因
个人学习/小项目	Cursor	规则系统完善，学习曲线平缓
企业GitHub生态	GitHub Copilot	与GitHub深度集成
高安全要求	Tabnine	代码隐私保障
AWS云原生	CodeWhisperer	AWS服务无缝集成
Java/Spring生态	Qoder	框架理解深度优化

Step 2：创建基础规则文件

# Cursor
mkdir -p .cursor/rules
touch .cursor/rules/core.md

# GitHub Copilot  
mkdir -p .github
touch .github/copilot-instructions.md

# Tabnine
mkdir .tabnine
touch .tabnine/mcp-config.json

Step 3：填充核心内容（5分钟）

复制以下模板，替换为你的项目信息：

## 项目基础
- 语言：[你的语言] + [精确版本]
- 框架：[核心框架] + [版本]
- 项目结构：
  [关键目录结构]

## 关键依赖
- [包名]: [版本] → [用途说明]
- [内部库]: [特殊用法说明]

## 禁止事项
- ❌ [常见错误1，如硬编码密码]
- ❌ [常见错误2，如未验证输入]

Step 4：验证和迭代

1. 让AI生成一个简单功能（如用户登录）
2. 检查是否符合规则要求
3. 针对不符合的点，补充规则说明
4. 每周回顾规则文件，保持更新

---

💡 五、未来展望：规则配置的演进趋势

1. 自动规则生成：工具将分析代码库自动生成初始规则
2. 规则共享市场：类似npm的规则包生态系统正在形成
3. AI辅助规则优化：AI将建议规则改进点，形成闭环
4. 标准化协议：Model Context Protocol (MCP)可能成为行业标准

最后一句真心话：写规则文件不是给AI打工，而是把重复沟通的成本一次性买断。我花20分钟写规则，省下了3小时修AI生成的bug——这笔账，初中级程序员更该算清楚。

Happy coding with AI!
—— 一个从AI"受害者"变成"受益者"的工程师

附：各工具官方文档

• Cursor Rules文档
• GitHub Copilot自定义指令指南
• AWS CodeWhisperer定制化文档
• Tabnine MCP配置手册
• Qoder规则指南

💡 附件 AGENTS.md：FastAPI + React 项目规则指南

项目概览：现代化前后端分离Web应用，使用FastAPI提供RESTful API，React构建用户界面。本规则文件指导AI生成符合项目规范的代码。

---

I. Codebase：项目基础

技术栈

• 后端：Python 3.11 + FastAPI 0.110.0
• 前端：React 18 + TypeScript 5.3 + Vite 5.0
• 数据库：PostgreSQL 15 + SQLAlchemy 2.0
• ORM：SQLModel（FastAPI官方推荐，结合Pydantic和SQLAlchemy）
• 构建工具：Poetry（后端依赖管理）+ npm（前端依赖管理）

项目结构

project-root/
├── backend/                   # FastAPI后端
│   ├── app/
│   │   ├── core/              # 核心功能
│   │   │   ├── config.py      # 配置管理
│   │   │   ├── security.py    # 认证授权
│   │   │   └── logging.py     # 日志配置
│   │   ├── api/               # API路由
│   │   │   ├── v1/            # API版本1
│   │   │   │   ├── endpoints/ # 业务端点
│   │   │   │   └── __init__.py
│   │   ├── models/            # 数据模型
│   │   ├── schemas/           # Pydantic模型
│   │   ├── services/          # 业务逻辑
│   │   ├── utils/             # 工具函数
│   │   └── main.py            # 应用入口
│   ├── tests/                 # 后端测试
│   ├── alembic/               # 数据库迁移
│   └── requirements.txt
│
├── frontend/                  # React前端
│   ├── src/
│   │   ├── components/        # 可复用组件
│   │   ├── layouts/           # 布局组件
│   │   ├── pages/             # 页面组件
│   │   ├── services/          # API服务
│   │   ├── hooks/             # 自定义Hooks
│   │   ├── context/           # React Context
│   │   ├── utils/             # 工具函数
│   │   ├── types/             # TypeScript类型
│   │   ├── assets/            # 静态资源
│   │   ├── styles/            # 全局样式
│   │   ├── App.tsx            # 根组件
│   │   └── main.tsx           # 应用入口
│   ├── public/
│   ├── tests/                 # 前端测试
│   └── package.json
│
├── .env.example               # 环境变量模板
├── docker-compose.yml         # 容器编排
├── .gitignore
└── README.md

---

II. Dependencies：关键依赖

后端依赖

• fastapi[all]==0.110.0：核心框架，包含所有可选依赖
• uvicorn[standard]==0.29.0：ASGI服务器
• sqlmodel==0.0.16：数据模型（SQLAlchemy + Pydantic集成）
• python-jose[cryptography]==3.3.0：JWT令牌处理
• passlib[bcrypt]==1.7.4：密码哈希
• alembic==1.13.1：数据库迁移
• httpx==0.27.0：HTTP客户端（用于服务间调用）
• redis==5.0.1：缓存和会话管理
• python-multipart==0.0.9：文件上传支持
• loguru==0.7.2：日志记录

前端依赖

• react@18.2.0 + react-dom@18.2.0：核心库
• typescript@5.3.3：类型系统
• vite@5.0.12：构建工具
• axios@1.6.7：HTTP客户端
• react-router-dom@6.21.3：路由管理
• @tanstack/react-query@5.28.4：数据获取和缓存
• zod@3.22.4：表单验证
• tailwindcss@3.4.1 + postcss@8.4.35 + autoprefixer@10.4.18：样式方案
• react-hook-form@7.51.0：表单处理
• date-fns@3.3.1：日期处理

关键约束

• 禁止使用已弃用的FastAPI依赖注入方式（如Depends(get_db)必须使用上下文管理器）
• 必须使用SQLModel而非纯SQLAlchemy模型
• 禁止在React组件中直接使用axios，必须通过services/api.ts封装
• 必须使用Zod进行表单验证，禁止仅用HTML5验证

---

III. Config：配置管理

配置文件

• 后端：backend/app/core/config.py（基于Pydantic Settings）
• 前端：frontend/src/config.ts（环境变量映射）
• 环境变量：.env文件（已加入.gitignore）

关键环境变量

# 后端环境变量
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/dbname
SECRET_KEY=your_32_byte_secure_key_here
ALGORITHM=HS256
ACCESS_TOKEN_EXPIRE_MINUTES=30
REDIS_URL=redis://localhost:6379/0
ENVIRONMENT=development  # development, staging, production

# 前端环境变量（VITE_前缀）
VITE_API_BASE_URL=http://localhost:8000/api/v1
VITE_WS_BASE_URL=ws://localhost:8000/ws

配置使用规范

• 后端：必须通过from app.core.config import settings导入配置
• 前端：必须通过import { API_BASE_URL } from '@/config'使用配置
• 禁止在代码中硬编码敏感信息或环境相关URL
• 开发环境：使用ENVIRONMENT=development，自动启用CORS和详细错误
• 生产环境：ENVIRONMENT=production，禁用调试信息，启用安全头

---

IV. Backing Services：外部服务

数据库

• 主数据库：PostgreSQL 15（异步连接使用asyncpg驱动）
• 连接池：使用SQLModel的异步会话管理
• 迁移工具：Alembic（迁移脚本存放在backend/alembic/versions/）
• 连接示例：

  from sqlmodel import create_engine, Session
  from app.core.config import settings
  
  engine = create_engine(settings.DATABASE_URL, echo=settings.ENVIRONMENT == "development")
  

缓存

• Redis 7.2：用于会话管理、速率限制和临时数据存储
• 连接方式：使用redis.asyncio.Redis客户端
• 键前缀：所有键必须包含环境前缀，如dev:user:session:{user_id}

消息队列

• RabbitMQ 3.12：用于异步任务（邮件发送、数据处理）
• 库：aio-pika（异步AMQP客户端）
• 交换器命名：{environment}.{service}.{type}（如dev.notifications.email）

外部API

• 认证服务：使用Keycloak（OIDC协议）
• 支付网关：Stripe API（测试模式使用测试密钥）
• 文件存储：AWS S3（通过boto3访问）

---

V. Build & Run：构建与运行

后端命令

# 安装依赖
poetry install

# 运行开发服务器（自动重载）
poetry run uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

# 运行测试
poetry run pytest -v

# 生成数据库迁移
poetry run alembic revision --autogenerate -m "描述变更"

# 应用数据库迁移
poetry run alembic upgrade head

# 生产环境构建
poetry export -f requirements.txt --output requirements.txt --without-hashes
docker build -t backend-app -f Dockerfile.backend .

前端命令

# 安装依赖
npm install

# 开发服务器（自动重载）
npm run dev

# 构建生产版本
npm run build

# 运行测试
npm run test

# 代码格式化
npm run format

# 生产环境构建
docker build -t frontend-app -f Dockerfile.frontend .

Docker Compose

# docker-compose.yml
version: '3.8'
services:
  backend:
    build:
      context: .
      dockerfile: Dockerfile.backend
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql+asyncpg://user:password@db:5432/app
    depends_on:
      - db
      - redis
  
  frontend:
    build:
      context: .
      dockerfile: Dockerfile.frontend
    ports:
      - "3000:3000"
    environment:
      - VITE_API_BASE_URL=http://backend:8000/api/v1
  
  db:
    image: postgres:15
    environment:
      POSTGRES_DB: app
      POSTGRES_USER: user
      POSTGRES_PASSWORD: password
  
  redis:
    image: redis:7.2-alpine

---

VI. Port Binding：端口分配

服务端口

• 8000：FastAPI后端（HTTP API）

  • /api/v1/*：RESTful API端点
  • /docs：Swagger UI（仅开发环境）
  • /redoc：ReDoc文档（仅开发环境）
  • /metrics：Prometheus指标（需认证）

• 8001：后台管理API（独立路由，严格权限控制）

  • /admin/*：管理功能端点

前端端口

• 3000：React开发服务器
• 80：生产环境Nginx（静态文件服务）
• 443：HTTPS（生产环境）

WebSocket

• 8000：复用HTTP端口（FastAPI支持WebSocket升级）
  • /ws/notifications：实时通知
  • /ws/chat：聊天功能

约束

• 禁止修改默认端口，除非有特殊安全要求
• 开发环境：前端通过proxy代理到后端，避免CORS问题
• 生产环境：使用Nginx反向代理，前端静态文件和后端API统一入口

---

VII. Logs：日志规范

后端日志

• 框架：loguru + structlog（结构化日志）
• 级别：
  • DEBUG：开发环境详细日志
  • INFO：关键操作（用户登录、数据变更）
  • WARNING：潜在问题（慢查询、重试）
  • ERROR：异常和错误
  • CRITICAL：系统级故障
• 格式：JSON格式（生产环境），包含request_id、user_id、timestamp
• 敏感数据：自动过滤密码、token、个人身份信息
• 示例：

  from app.core.logging import logger
  
  # 正确：包含上下文信息
  logger.info("User logged in", user_id=user.id, ip_address=request.client.host)
  
  # 错误：禁止使用print()
  # print("Debug info")  # ❌ 严禁使用
  

前端日志

• 框架：使用console封装，通过环境变量控制
• 生产环境：仅记录ERROR级别，使用Sentry捕获异常
• 开发环境：记录DEBUG信息，包含组件名称和状态
• 敏感数据：禁止记录用户输入、token、个人数据
• 示例：

  // utils/logger.ts
  export const logger = {
    debug: (message: string, context?: object) => {
      if (import.meta.env.DEV) {
        console.debug(`[DEBUG] ${message}`, context);
      }
    },
    error: (error: Error, context?: object) => {
      console.error(`[ERROR] ${error.message}`, { ...context, stack: error.stack });
      // 生产环境上报到Sentry
      if (import.meta.env.PROD) {
        Sentry.captureException(error, { extra: context });
      }
    }
  };
  

错误处理规范

• 后端：使用FastAPI异常处理器，统一返回格式

  from fastapi import HTTPException, status
  
  # 正确：使用标准HTTP状态码
  raise HTTPException(
      status_code=status.HTTP_404_NOT_FOUND,
      detail="Resource not found"
  )
  

• 前端：使用React Query错误边界，友好用户提示

  // components/ErrorBoundary.tsx
  useQuery({
    queryKey: ['userData'],
    queryFn: fetchUserData,
    onError: (error) => {
      logger.error(error, { context: 'user_data_fetch' });
      toast.error('加载用户数据失败，请重试');
    }
  });
  

---

VIII. Code Style：代码风格

Python (后端)

• 格式化：使用Black（行宽88字符）
• 静态检查：ruff（替代flake8 + isort）
• 类型提示：必须使用类型注解，包括函数参数和返回值
• 异步：使用async/await，避免阻塞调用
• 依赖注入：使用FastAPI的Depends机制
• 示例：

  from typing import Annotated
  from fastapi import Depends, HTTPException
  
  async def get_current_user(
      token: Annotated[str, Depends(oauth2_scheme)]
  ) -> User:
      try:
          payload = jwt.decode(token, settings.SECRET_KEY, algorithms=[settings.ALGORITHM])
          user_id: str = payload.get("sub")
          if user_id is None:
              raise credentials_exception
      except JWTError:
          raise credentials_exception
      return await User.get(user_id)
  

TypeScript (前端)

• 格式化：Prettier（行宽80字符，单引号）
• 静态检查：ESLint + TypeScript ESLint
• 组件规范：
  • 函数组件优先
  • 使用TypeScript泛型
  • Props使用接口定义
• 状态管理：优先使用React Query + Context API，避免过度使用Redux
• 示例：

  // components/UserProfile.tsx
  interface UserProfileProps {
    user: {
      id: string;
      name: string;
      email: string;
      avatarUrl?: string;
    };
    isLoading?: boolean;
    onError?: (error: Error) => void;
  }
  
  export const UserProfile: React.FC<UserProfileProps> = ({
    user,
    isLoading = false,
    onError
  }) => {
    // 组件逻辑
  };
  

---

IX. Security：安全规范

认证与授权

• JWT令牌：访问令牌30分钟，刷新令牌7天
• 权限控制：基于角色的访问控制（RBAC）
  • user：普通用户权限
  • admin：管理权限
  • system：系统服务权限
• 敏感操作：二次验证（如密码修改、资金操作）

数据验证

• 后端：使用Pydantic模型验证所有输入
• 前端：使用Zod验证表单，后端仍需验证
• 禁止信任客户端输入，所有API端点必须验证

安全头

• 后端：使用fastapi.middleware.cors.CORSMiddleware
• 生产环境：启用CSP、HSTS、X-Content-Type-Options
• 示例：

  from fastapi.middleware.cors import CORSMiddleware
  
  app.add_middleware(
      CORSMiddleware,
      allow_origins=settings.BACKEND_CORS_ORIGINS,
      allow_credentials=True,
      allow_methods=["*"],
      allow_headers=["*"],
  )
  

---

X. Testing：测试规范

后端测试

• 框架：pytest + httpx
• 覆盖率：>80%（核心业务逻辑>95%）
• 测试类型：
  • 单元测试：tests/unit/
  • 集成测试：tests/integration/
  • 端到端测试：tests/e2e/
• 示例：

  # tests/unit/test_user_service.py
  async def test_create_user_success(user_service, mock_user_repo):
      user_data = UserCreate(email="test@example.com", password="securepass123")
      created_user = await user_service.create_user(user_data)
      
      assert created_user.email == user_data.email
      assert created_user.hashed_password != user_data.password
      mock_user_repo.create.assert_called_once()
  

前端测试

• 框架：Vitest + React Testing Library
• 覆盖率：>70%（核心组件>85%）
• 测试类型：
  • 单元测试：组件、工具函数
  • 集成测试：页面流程
  • E2E测试：Cypress（关键用户旅程）
• 示例：

  // tests/components/UserProfile.test.tsx
  it('displays user information correctly', () => {
    const mockUser = {
      id: '1',
      name: 'John Doe',
      email: 'john@example.com'
    };
    
    render(<UserProfile user={mockUser} />);
    
    expect(screen.getByText('John Doe')).toBeInTheDocument();
    expect(screen.getByText('john@example.com')).toBeInTheDocument();
  });
  

---

XI. Performance：性能要求

后端性能

• API响应时间：<200ms（P95）
• 数据库查询：
  • 避免N+1查询，使用SQLModel的select().options(selectinload())
  • 复杂查询使用缓存（Redis TTL 5分钟）
• 限流：使用slowapi进行速率限制（100请求/分钟/IP）

前端性能

• Bundle大小：主包<200KB（gzip后）
• 首次内容绘制（FCP）：<1.5s
• 优化策略：
  • 代码分割（React.lazy + Suspense）
  • 图片懒加载
  • API响应缓存（React Query staleTime）

---

XII. Deployment：部署规范

环境

• 开发环境：本地Docker Compose
• Staging环境：Vercel（前端）+ Render（后端）
• 生产环境：AWS ECS Fargate + RDS PostgreSQL

CI/CD

• GitHub Actions：.github/workflows/
  • backend-ci.yml：后端测试和构建
  • frontend-ci.yml：前端测试和构建
  • deploy-prod.yml：生产环境部署
• 部署流程：
  1. 代码推送触发测试
  2. 测试通过后自动部署到staging
  3. 人工确认后部署到production
  4. 部署后运行健康检查

监控

• 后端：Prometheus + Grafana（指标收集）
• 前端：Sentry（错误监控）+ Plausible（分析）
• 日志：ELK Stack（集中日志管理）

---

规则文件维护：本文件应随项目演进持续更新。当AI生成不符合规范的代码时，应首先检查并完善此规则文件。
最后更新：2025-12-07
维护者：@team-lead

Happy qoding!
—— Qoder Team