Python后端开发准则

一、总体原则

1. 工程优先于实现

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

2. 分层强约束

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

3. 单一职责原则（SRP）

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

二、项目结构规范

推荐结构：

bash 复制代码

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

强制规则

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

三、API 层规范（Controller）

职责

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

禁止行为

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

示例

less 复制代码

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

四、Service 层规范（核心）

职责

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

强制规则

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

示例

python 复制代码

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

五、Repository / CRUD 层规范

职责

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

强制规则

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

六、Model 与 Schema 分离

Model（数据库结构）

定义表结构
仅用于 ORM

Schema（数据结构）

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

强制规则

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

七、配置管理

强制规则

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

示例

ini 复制代码

DATABASE_URL=...
REDIS_URL=...

八、日志规范

强制规则

必须使用统一日志模块
禁止使用 print
日志必须包含：
- 时间
- 级别
- 业务上下文

建议

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

九、异常处理规范

强制规则

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

示例

java 复制代码

raise BusinessException("用户不存在")

十、依赖注入规范

原则

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

十一、测试规范（关键）

强制规则

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

覆盖范围

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

十二、数据库规范

强制规则

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

十三、接口设计规范

REST 风格（推荐）

bash 复制代码

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

命名规范

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

十四、异步与并发

原则

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

十五、安全规范

强制规则

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

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

建议目录

复制代码

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

原则

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

十七、禁止事项（红线）

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

十八、代码质量标准

必须满足

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

十九、演进路径建议

基础 CRUD 架构
引入 Service 分层
引入任务队列
抽象业务流程
引入 Agent / Workflow

二十、核心总结

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

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