在只有一两个接口时,直接在路由函数中执行 select() 很容易理解。随着项目逐渐出现用户、项目、成员、任务和权限规则,路由如果同时负责参数校验、权限判断、事务控制和数据库查询,很快就会变得难以修改和测试。
select()
分层不是为了增加文件数量,而是让不同类型的变化停留在各自的位置:
Request
HTTPException
以“创建任务”为例,HTTP 层需要知道接口是 POST /api/v1/projects/{project_id}/tasks,成功时返回 201;业务层需要保证当前用户是项目成员,并且任务编号在项目内唯一;持久化层则负责把这些要求转换成 SQLAlchemy 查询。
POST /api/v1/projects/{project_id}/tasks
这些职责之间只有一个主要依赖方向:
HTTP 请求由 Route 和 Schema 处理,Route 调用 Service 编排业务,Service 调用 Repository,Repository 使用 AsyncSession 和 ORM Model 访问 PostgreSQL。返回结果沿反方向传回,代码依赖保持单向,Repository 不依赖 HTTP Schema。
FLOW / RELATIONSHIP
HTTP 请求
Route + Schema
HTTP 输入与输出
Service
业务规则与事务边界
Repository
查询与持久化
AsyncSession + Model
事务状态与数据库映射
PostgreSQL
返回结果沿相反方向传回,但代码依赖不应该倒置。例如,Repository 不应导入 TaskCreate,否则数据库访问层会被 HTTP 请求结构绑定;Service 也不应抛出 HTTPException,否则它很难在后台任务或测试中复用。
TaskCreate
分层也不是机械规则。只有一条简单查询的模块可以先用函数组织;当业务规则、事务或查询开始重复时,再提取 Service 或 Repository。判断标准是职责是否清楚,而不是文件数量是否足够多。
可以把数据库相关代码组织成下面的结构:
目录图省略了各个 Python 包中的 __init__.py。db 也不是所有数据库业务的容器:Engine、Session、ORM 模型和查询与持久化直接相关;权限流程、编号规则和跨实体操作仍然属于 services。
__init__.py
db
services
一次创建请求会按下面的顺序执行:
POST /api/v1/projects/12/tasks 进入路由完成参数校验,TaskService 检查成员身份并开启事务,ProjectRepository 查询成员关系并预留任务编号,TaskRepository 插入任务并 flush。Service 提交事务后,路由转换为 TaskRead,FastAPI 返回 201 JSON。
POST 创建任务
/api/v1/projects/12/tasks
tasks.py
校验路径参数与请求体
TaskService
成员检查与事务控制
ProjectRepository
查询成员、预留编号
TaskRepository
写入任务并 flush
结束事务并提交
TaskRead
路由转换响应对象
201 JSON
FastAPI 返回成功响应
这条路径可以帮助我们判断代码应该放在哪里。如果某段代码需要读取 Path 或设置 HTTP 状态码,它属于 Route;如果它要协调多个查询并决定一起提交或回滚,它属于 Service。
Path
此段落已有评论,按 Enter 查看评论及回复列表。
连接 GitHub 后查看和发表评论,也可在 GitHub 查看公开讨论。
1. 分层解决什么问题
在只有一两个接口时,直接在路由函数中执行
select()很容易理解。随着项目逐渐出现用户、项目、成员、任务和权限规则,路由如果同时负责参数校验、权限判断、事务控制和数据库查询,很快就会变得难以修改和测试。分层不是为了增加文件数量,而是让不同类型的变化停留在各自的位置:
Request、HTTPException以“创建任务”为例,HTTP 层需要知道接口是
POST /api/v1/projects/{project_id}/tasks,成功时返回 201;业务层需要保证当前用户是项目成员,并且任务编号在项目内唯一;持久化层则负责把这些要求转换成 SQLAlchemy 查询。这些职责之间只有一个主要依赖方向:
HTTP 请求由 Route 和 Schema 处理,Route 调用 Service 编排业务,Service 调用 Repository,Repository 使用 AsyncSession 和 ORM Model 访问 PostgreSQL。返回结果沿反方向传回,代码依赖保持单向,Repository 不依赖 HTTP Schema。
FLOW / RELATIONSHIP
HTTP 请求
Route + Schema
HTTP 输入与输出
Service
业务规则与事务边界
Repository
查询与持久化
AsyncSession + Model
事务状态与数据库映射
PostgreSQL
返回结果沿相反方向传回,但代码依赖不应该倒置。例如,Repository 不应导入
TaskCreate,否则数据库访问层会被 HTTP 请求结构绑定;Service 也不应抛出HTTPException,否则它很难在后台任务或测试中复用。分层也不是机械规则。只有一条简单查询的模块可以先用函数组织;当业务规则、事务或查询开始重复时,再提取 Service 或 Repository。判断标准是职责是否清楚,而不是文件数量是否足够多。
2. 目录与请求流
可以把数据库相关代码组织成下面的结构:
目录图省略了各个 Python 包中的
__init__.py。db也不是所有数据库业务的容器:Engine、Session、ORM 模型和查询与持久化直接相关;权限流程、编号规则和跨实体操作仍然属于services。一次创建请求会按下面的顺序执行:
POST /api/v1/projects/12/tasks 进入路由完成参数校验,TaskService 检查成员身份并开启事务,ProjectRepository 查询成员关系并预留任务编号,TaskRepository 插入任务并 flush。Service 提交事务后,路由转换为 TaskRead,FastAPI 返回 201 JSON。
FLOW / RELATIONSHIP
POST 创建任务
/api/v1/projects/12/tasks
tasks.py
校验路径参数与请求体
TaskService
成员检查与事务控制
ProjectRepository
查询成员、预留编号
TaskRepository
写入任务并 flush
TaskService
结束事务并提交
TaskRead
路由转换响应对象
201 JSON
FastAPI 返回成功响应
这条路径可以帮助我们判断代码应该放在哪里。如果某段代码需要读取
Path或设置 HTTP 状态码,它属于 Route;如果它要协调多个查询并决定一起提交或回滚,它属于 Service。