Python后端开发准则
一、总体原则
1. 工程优先于实现
- 优先保证系统结构清晰、可维护，而不是快速实现功能
- 避免“脚本式开发”，所有代码必须具备工程化属性
2. 分层强约束
- 必须严格分层：API / Service / Repository / Model / Schema
- 禁止跨层调用（例如 API 直接操作数据库）
3. 单一职责原则（SRP）
- 每个模块、函数、类只负责一件事
- 避免“上帝函数”和“万能类”
二、项目结构规范
推荐结构：
app/
├── api/
├── services/
├── crud/
├── models/
├── 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（数据库结构）
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 调试
- 无测试直接上线
十八、代码质量标准
必须满足
十九、演进路径建议
- 基础 CRUD 架构
- 引入 Service 分层
- 引入任务队列
- 抽象业务流程
- 引入 Agent / Workflow
二十、核心总结
一个合格的 Python 后端系统必须具备：
- 清晰分层
- 可测试性
- 可扩展性
- 工程化规范
- 严格约束而非自由开发
