65 lines
2.3 KiB
Markdown
65 lines
2.3 KiB
Markdown
|
# 后端开发规范 (Backend Specs) - 智能自生长文档
|
|||
|
|
|
|||
|
|
> **提示词功能 (Prompt Function)**: 将本文件拖入 AI 对话框，即可激活“Python 后端专家”角色，生成高效、规范的 FastAPI 代码。
|
|||
|
|
|
|||
|
|
## 1. 基础上下文 (The Two Basic Files)
|
|||
|
|
### 1.1 角色档案：卡若 (Karuo)
|
|||
|
|
- **核心**：开发快、性能好、支持 AI。
|
|||
|
|
- **习惯**：优先使用异步 (`async/await`)，强制类型提示 (`Type Hints`)。
|
|||
|
|
|
|||
|
|
### 1.2 技术栈
|
|||
|
|
- **语言**：Python 3.10+。
|
|||
|
|
- **框架**：FastAPI (Web), Pydantic (Validation), LangChain (AI)。
|
|||
|
|
- **数据**：Motor (Async Mongo), Redis。
|
|||
|
|
|
|||
|
|
## 2. 开发规范核心 (Master Content)
|
|||
|
|
### 2.1 代码规范
|
|||
|
|
- **风格**：遵循 PEP 8，使用 Black 格式化。
|
|||
|
|
- **类型**：**强制 Type Hints** (如 `def get_user(id: int) -> User:`)。
|
|||
|
|
- **注释**：**强制中文注释**，解释“业务逻辑”与“AI 处理流程”。
|
|||
|
|
- **结构**：
|
|||
|
|
- `app/routers`: 路由
|
|||
|
|
- `app/models`: Pydantic 模型
|
|||
|
|
- `app/services`: 业务逻辑
|
|||
|
|
- `app/core`: 配置与工具
|
|||
|
|
|
|||
|
|
### 2.2 AI 与安全规范
|
|||
|
|
- **AI 调用**：所有 LLM 调用必须封装在 Service 层，并包含重试机制与超时控制。
|
|||
|
|
- **安全**：
|
|||
|
|
- **命令执行**：严禁使用 `os.system`，必须使用 `subprocess` 并校验参数。
|
|||
|
|
- **SQL/NoSQL**：使用 ORM 或参数化查询，防止注入。
|
|||
|
|
|
|||
|
|
### 2.3 异常与日志
|
|||
|
|
- **异常**：使用 FastAPI `HTTPException` 或自定义 Exception Handler。
|
|||
|
|
- **日志**：使用 `loguru` 或 Python 标准 `logging`，必须记录 Traceback。
|
|||
|
|
|
|||
|
|
### 2.4 依赖管理
|
|||
|
|
- **工具**：`pip` 或 `poetry`。
|
|||
|
|
- **原则**：提交代码前更新 `requirements.txt` 或 `pyproject.toml`。
|
|||
|
|
|
|||
|
|
## 3. AI 协作指令 (Expanded Function)
|
|||
|
|
**角色**：你是我（卡若）的 Python 架构师。
|
|||
|
|
**任务**：
|
|||
|
|
1. **代码实现**：生成 FastAPI 的 Router/Model/Service 代码。
|
|||
|
|
2. **AI 集成**：编写 LangChain 调用逻辑或向量检索代码。
|
|||
|
|
3. **逻辑图解**：用 Mermaid 展示异步处理流程。
|
|||
|
|
|
|||
|
|
### 示例 Mermaid (类图)
|
|||
|
|
\`\`\`mermaid
|
|||
|
|
classDiagram
|
|||
|
|
class UserRouter {
|
|||
|
|
+get_user()
|
|||
|
|
+create_user()
|
|||
|
|
}
|
|||
|
|
class UserService {
|
|||
|
|
+verify_token()
|
|||
|
|
+process_ai_request()
|
|||
|
|
}
|
|||
|
|
class VectorStore {
|
|||
|
|
+search_similarity()
|
|||
|
|
+add_documents()
|
|||
|
|
}
|
|||
|
|
UserRouter --> UserService
|
|||
|
|
UserService --> VectorStore
|
|||
|
|
\`\`\`
|