Python后端开发准则

Python后端开发准则

一、总体原则

1. 工程优先于实现

• 优先保证系统结构清晰、可维护，而不是快速实现功能
• 避免"脚本式开发"，所有代码必须具备工程化属性

2. 分层强约束

• 必须严格分层：API / Service / Repository / Model / Schema
• 禁止跨层调用（例如 API 直接操作数据库）

3. 单一职责原则（SRP）

• 每个模块、函数、类只负责一件事
• 避免"上帝函数"和"万能类"

---

二、项目结构规范

推荐结构：

app/
├── api/            # 接口层（路由）
├── services/       # 业务逻辑层
├── crud/           # 数据访问层（可选）
├── models/         # ORM模型
├── schemas/        # 数据结构定义
├── core/           # 配置 / 安全 / 日志
├── db/             # 数据库连接
├── utils/          # 工具函数

强制规则

• API 层不得包含业务逻辑
• Service 层不得依赖 Web 框架
• Model 不得用于接口返回
• Schema 不得用于数据库操作

---

三、API 层规范（Controller）

职责

• 接收请求
• 参数校验
• 调用 Service
• 返回响应

禁止行为

• ❌ 写业务逻辑
• ❌ 直接操作数据库
• ❌ 写复杂条件判断

示例

@router.post("/users")
def create_user(user: UserCreate):
    return user_service.create_user(user)

---

四、Service 层规范（核心）

职责

• 核心业务逻辑实现
• 流程编排
• 调用 Repository / 外部服务

强制规则

• 必须可单元测试（无框架依赖）
• 不依赖 FastAPI / Flask 等框架
• 不直接处理 HTTP 请求/响应

示例

def create_user(user):
    # 业务逻辑
    return {...}

---

五、Repository / CRUD 层规范

职责

• 封装数据库操作
• 提供统一数据访问接口

强制规则

• 所有 SQL / ORM 操作必须集中管理
• 禁止在 Service / API 中写 SQL

---

六、Model 与 Schema 分离

Model（数据库结构）

• 定义表结构
• 仅用于 ORM

Schema（数据结构）

• 定义请求 / 响应格式
• 用于数据校验

强制规则

• ❌ 不允许直接返回 Model
• ❌ 不允许用 Schema 操作数据库

---

七、配置管理

强制规则

• 所有配置必须集中管理（config.py）
• 禁止硬编码配置（数据库、API Key 等）

示例

DATABASE_URL=...
REDIS_URL=...

---

八、日志规范

强制规则

• 必须使用统一日志模块

• 禁止使用 print

• 日志必须包含：

  • 时间
  • 级别
  • 业务上下文

建议

• 使用结构化日志（JSON）
• 接入日志系统（ELK / Loki）

---

九、异常处理规范

强制规则

• 统一异常处理入口
• 不允许直接抛出裸异常

示例

raise BusinessException("用户不存在")

---

十、依赖注入规范

原则

• 使用依赖注入管理资源（DB / Redis / Service）
• 避免全局变量

---

十一、测试规范（关键）

强制规则

• Service 层必须可单测
• 单元测试不得依赖数据库 / 网络
• API 测试与业务测试分离

覆盖范围

• 核心业务逻辑（必须）
• 边界条件（必须）
• 异常路径（必须）

---

十二、数据库规范

强制规则

• 使用迁移工具（如 Alembic）
• 禁止手动改表
• 表结构必须版本化管理

---

十三、接口设计规范

REST 风格（推荐）

GET    /resources
POST   /resources
GET    /resources/{id}
PUT    /resources/{id}
DELETE /resources/{id}

命名规范

• 使用复数名词
• 使用小写 + 下划线或短横线

---

十四、异步与并发

原则

• IO 操作必须使用异步
• CPU 密集型任务必须使用任务队列

---

十五、安全规范

强制规则

• 所有接口必须鉴权（除公开接口）
• 敏感数据必须加密
• 禁止日志输出敏感信息

---

十六、扩展性设计（高级）

建议目录

app/
├── agents/
├── tools/
├── workflows/

原则

• 业务逻辑模块化
• 支持插件化扩展
• 支持任务编排（Workflow）

---

十七、禁止事项（红线）

• ❌ API 层写业务逻辑
• ❌ Service 依赖框架
• ❌ 直接操作数据库（绕过 Repository）
• ❌ 使用全局变量共享状态
• ❌ 配置硬编码
• ❌ 无日志 / print 调试
• ❌ 无测试直接上线

---

十八、代码质量标准

必须满足

• 可读性高
• 可测试
• 可维护
• 可扩展

---

十九、演进路径建议

1. 基础 CRUD 架构
2. 引入 Service 分层
3. 引入任务队列
4. 抽象业务流程
5. 引入 Agent / Workflow

---

二十、核心总结

一个合格的 Python 后端系统必须具备：

• 清晰分层
• 可测试性
• 可扩展性
• 工程化规范
• 严格约束而非自由开发

---