后端写久了你会发现,真正拉开项目差距的,往往不是某个库玩得有多花哨,而是代码的组织方式。今天这堂课,我们聊的是 Python 后端工程化进阶里最核心的四个抓手:分层架构、中间件、日志、异常统一处理。这四个东西单独拿出来都不难,难的是把它们组合成一套可以跨项目复用的骨架。这篇文章我会用 FastAPI 作为样例,带你从零搭一个“类企业级”的后端底座,让你后面的每个业务功能都能直接往这个骨架里填。不管你是刚写过后端接口的初级开发,还是已经带过一两个项目的工程师,这套思路都能帮你解决一个很现实的问题:项目代码越来越多时,怎么保证它不烂掉。
1. 第5课到底在解决什么问题:从“能跑”到“高可用”
1.1 你迟早会碰到的三个工程化痛点
我见过太多次这种场景:项目第一版上线时,所有逻辑都堆在路由文件里,一个接口函数两三百行,里面既要解析参数、又要调数据库、还要拼返回结构。当时跑得好好的,等第二个月需求叠加进来,这个文件开始膨胀到几千行,改一个字段要全局搜索好几处,新增一个接口小心翼翼地复制粘贴老代码。这种状态就是“能跑”,但它和“高可用”之间隔着一整条工程化鸿沟。
高可用后端不只是“服务不挂”,它还包含三层含义:一是代码结构稳定,改一处业务不会震碎另外三处;二是问题可以在生产环境被快速定位,而不是靠开发者远程连服务器猜;三是接口行为可预期,前端拿到每个错误都能知道下一步该做什么。这三件事,恰好分别对应分层架构、日志、异常统一处理。中间件则是把这些能力串联起来的“总装线”,所有请求进出的通用逻辑都可以在中间件层收口。
1.2 三个关键词拆解:分层、中间件、日志与异常
先给这一课定个基调,三个关键词分别解决不同层次的问题:
- 分层架构:解决“代码该放在哪里”。它把输入输出、业务规则、数据访问拆成相互独立又单向依赖的模块,让你避免在一个函数里干所有事。
- 中间件:解决“通用逻辑该在哪里统一处理”。比如全链路请求ID、接口耗时统计、跨域、登录状态校验,这些逻辑不适合塞进业务代码里,放中间件是最合理的。
- 日志与异常统一处理:解决“出了问题怎么发现、怎么反馈”。日志让你看得见系统内部发生了什么,异常处理让你把错误转成规范的响应结构,两者配合,前端用户、后端开发、运维人员才能在同一套语言下协作。
这三个关键词不是孤立的。分层架构给了代码一个清晰的“地图”,中间件和日志在这张地图上划出“主干道”,异常处理则给所有可能的失败点装了统一的路标。后面第 6 节实操中你会看到它们怎么咬合在一起。
1.3 技术选型:为什么用 FastAPI 做演示骨架
标题没限定框架,但我选 FastAPI 当演示骨架,原因有三个。第一,FastAPI 原生支持依赖注入,这跟分层架构配合得特别舒服,你可以在路由函数里声明依赖,而不用在每个 controller 里手动 new 一个 service。第二,它的中间件机制基于 Starlette,既支持简单的装饰器写法,也支持 BaseHTTPMiddleware 的完整中间件类,演示“请求->中间件->路由->响应”这条链路很直观。第三,FastAPI 自带 OpenAPI 文档,你每写一个接口,浏览器打开 /docs 就能看到请求和响应结构,方便验证我们后面做的统一异常处理和响应包装。
当然,如果你团队里用的是 Flask 或 Django,文章里的分层思想、日志策略、中间件思路一样适用。Flask 用 before_request / after_request,Django 用 MIDDLEWARE 配置,底层逻辑殊途同归。我会把重点放在“为什么这么设计”上,代码细节以 FastAPI 为主,其他框架的读者也能按图索骥。
需要模型API调用? 免费领10W Token,多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 分层架构:让每一行代码都待在该待的地方
2.1 经典三层/多层架构的职责边界
后端项目最常见的分层是三层:API 层、Service 层、Repository 层,外面再挂一层 Models 和 Schemas。它的核心规则是“职责单一、单向依赖”。我习惯用一个比喻:API 层是前台服务员,只负责接单、传菜;Service 层是后厨团队,负责按菜谱做菜;Repository 层是仓库管理员,负责从货架上拿原材料。服务员不能跑去仓库自己搬货,仓库管理员也不该跑到前厅跟客人解释菜品。
拆开来看,每一层的职责边界是这样的:
| 层次 | 核心职责 | 典型内容 | 禁止事项 |
|---|---|---|---|
| API 层 | 接收请求、参数校验、调用 Service、返回响应 | 路由函数、Pydantic Schema、Depends | 不写业务规则、不直接操作数据库 |
| Service 层 | 业务规则、事务控制、领域逻辑 | 业务判断、数据组装、异常抛出 | 不出现 HTTP Request/Response、不直接拼 SQL |
| Repository 层 | 数据访问、持久化、ORM 操作 | SQLAlchemy Session、数据库模型映射 | 不返回复杂业务结果、不判业务规则 |
| Models/Schemas | 数据结构约定 | ORM Model、Pydantic Model | 不含业务逻辑、不做数据加工 |
这个表格看起来简单,真正实施的时候,破坏边界的诱惑无处不在。最典型的场景就是“图省事”:在 API 层顺手写一句 db.query(User).filter_by(...),而不是去 Repository 里封装。一个两个接口这么干还能忍受,等数量上来,数据库表结构一变,你会想穿越回去把自己打一顿。
2.2 一套能直接上手的项目目录结构
理论讲完,给出一套我实际在项目里用过的目录结构。它不算最精简,但足够清晰,适合作为中型项目的起点:
code复制my_project/
├── app/
│ ├── api/
│ │ ├── __init__.py
│ │ ├── dependencies.py
│ │ └── v1/
│ │ ├── __init__.py
│ │ ├── router.py
│ │ └── endpoints/
│ │ └── users.py
│ ├── core/
│ │ ├── __init__.py
│ │ ├── config.py
│ │ └── logging.py
│ ├── middleware/
│ │ ├── __init__.py
│ │ ├── request_id.py
│ │ └── timing.py
│ ├── models/
│ │ ├── __init__.py
│ │ └── user.py
│ ├── repositories/
│ │ ├── __init__.py
│ │ └── user_repository.py
│ ├── schemas/
│ │ ├── __init__.py
│ │ └── user.py
│ ├── services/
│ │ ├── __init__.py
│ │ └── user_service.py
│ ├── utils/
│ │ ├── __init__.py
│ │ └── response.py
│ ├── exceptions.py
│ └── main.py
├── .env
├── requirements.txt
└── README.md
注意几个细节。core 放配置和日志这类“基础设施”,middleware 单独建目录放中间件类,api/v1 表示接口版本,以后要做 v2 直接平行加一个包就行。dependencies.py 放依赖注入方法,比如怎么获取一个带数据库连接的 UserService。这样整个项目从 main.py 读进去是自解释的:路由在 api 里,逻辑在 service 里,数据在 repository 里,公共配置在 core 里。
2.3 分层实践中的三条铁律和一个常见破防现场
第一条铁律:上层可以依赖下层,下层绝不反向依赖。也就是说 API 层可以 import Service 层,Service 层可以 import Repository 层,但 Repository 层绝对不能去 import 某个 Service 或者某个路由。一旦出现反向依赖,分层就会退化成一堆模块互相 import,代码耦合度瞬间拉满。
第二条铁律:同层之间尽量通过“上层协调”,不要平级直接互相 import。比如用户注册后要发通知,UserService 需要调用 NotifyService,这不是平级调用,而是 UserService 作为业务编排者主动调用另一个 Service 的公开方法。但如果你在 UserRepository 里直接调 OrderRepository,那就要警惕了,通常这种跨领域的数据访问应该提到 Service 层去编排。
第三条铁律:控制器里不放业务规则。判断邮箱是否重复、余额是否足够、订单状态能否流转,这些都是业务规则,必须放进 Service 层。API 层只负责“传输”和“转换”。
破防现场我见得最多的是:路由函数里写了一大堆 if else 做参数校验和业务判断,最后直接把 ORM 对象返回给前端。这个操作短期看“挺方便”,但前端拿到的时间格式、字段命名、嵌套结构全被 ORM 模型绑死了。后面要改响应结构,只能挨个接口找。正确做法是 API 层用 Pydantic Schema 定义响应模型,在返回时做一次显式转换。
2.4 依赖注入:让层与层之间松耦合
分层之后,有人问:“UserService 要用 UserRepository,是不是在 UserService 里直接 import 一个单例就行?”技术上没问题,但可维护性差。更推荐的做法是依赖注入,在 API 层的 dependencies 里把 UserService 组装好,再传给路由函数。
FastAPI 的 Depends 让这一步实现得非常优雅。比如我在 app/api/dependencies.py 里写:
python复制# app/api/dependencies.py
from app.repositories.user_repository import UserRepository
from app.services.user_service import UserService
def get_user_service():
repo = User
