Python 后端项目架构笔记
1. 后端项目核心思想
一个成熟 Python 后端项目通常采用分层架构（Layered Architecture）。
每个人只做自己的事情，不关注不相干的
比如数据库的只curd不做什么安全校验登录
核心目标：
- 降低代码耦合
- 分离职责
- 方便测试
- 方便扩展
- 方便团队协作
整体调用链：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
| 用户请求
↓
API Router（接口层）
↓
Service（业务层）
↓
Repository（数据访问层）
↓
Model（数据库模型）
↓
Database（数据库）
|
2. 常见项目结构
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
| backend/
├── main.py # 项目入口
├── api/ # API接口层
│ ├── user.py
│ └── auth.py
├── schemas/ # 数据验证模型
│ └── user.py
├── services/ # 业务逻辑层
│ └── user_service.py
├── repositories/ # 数据访问层
│ └── user_repository.py
├── models/ # 数据库ORM模型
│ └── user.py
├── database.py # 数据库配置
├── dependencies.py # 依赖注入
├── core/ # 核心配置
│ ├── config.py
│ └── security.py
├── utils/ # 工具函数
├── migrations/ # 数据库迁移
└── tests/ # 测试
|
3. API Router（接口层）
位置：
作用：
负责 HTTP 世界和程序世界的连接。
负责：
✅ 接收请求
✅ 参数解析
✅ 调用 Service
✅ 返回响应
例如：
1
2
3
4
5
6
| @router.post("/users")
def create_user(
user: UserCreate
):
return user_service.create(user)
|
不要写：
1
| sql = "select * from users"
|
原因：
API 不应该知道数据库。
4. Schema（数据校验层）
位置：
作用：
定义：
例如：
用户注册：
1
2
3
4
5
6
7
| class UserCreate(BaseModel):
username:str
password:str
email:str
|
请求：
1
2
3
4
5
| {
"username":"tom",
"password":"123456",
"email":"tom@qq.com"
}
|
Schema负责检查：
常用：
FastAPI:
5. Service（业务逻辑层）⭐
位置：
这是项目的大脑。
负责：
例如：
注册用户：
1
2
3
4
5
6
7
8
9
10
11
12
13
| 注册流程：
1. 查询邮箱是否存在
2. 密码加密
3. 创建用户
4. 创建用户资料
5. 发送邮件
6. 返回结果
|
代码：
1
2
3
4
5
6
7
8
9
10
11
12
| class UserService:
def register(self,data):
check_email()
hash_password()
create_user()
send_email()
|
Service 不关心：
数据库怎么查询。
6. Repository（数据访问层）⭐
位置：
作用：
专门负责数据库 CRUD。
例如：
1
2
3
4
5
6
7
8
9
10
11
| class UserRepository:
def create(user):
db.add(user)
def get_by_id(id):
return db.query(User)
|
负责：
✅ 查询
✅ 新增
✅ 修改
✅ 删除
不负责：
❌ 用户权限
❌ 发邮件
❌ 业务流程
7. Model（数据库模型）
位置：
作用：
描述数据库表。
例如：
数据库：
对应：
1
2
3
4
5
6
7
8
9
10
| class User(Base):
__tablename__="users"
id
username
password
|
ORM关系：
1
2
3
4
5
6
7
8
9
| Python对象
↓
SQLAlchemy
↓
数据库表
|
8. Database 层
位置：
负责：
Engine
数据库连接池：
Session
数据库会话：
Base
ORM基类：
1
2
| class Base(DeclarativeBase):
pass
|
结构：
1
2
3
4
5
6
7
8
9
10
11
12
13
| database.py
|
|
↓
models/user.py
|
|
↓
数据库表
|
9. Session 生命周期
推荐：
不要：
而是：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| Request进入
↓
创建Session
↓
Repository使用
↓
请求结束
↓
关闭Session
|
FastAPI：
1
2
3
4
5
6
7
8
9
10
11
| def get_db():
db = SessionLocal()
try:
yield db
finally:
db.close()
|
10. Repository 和 Service 的区别
Repository
关注：
数据怎么拿？
例如：
Service
关注：
为什么拿？
例如：
登录：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| 用户输入邮箱密码
↓
Service:
查询用户
校验密码
生成Token
↓
返回
|
11. Transaction（事务）
简单项目：
Repository commit：
大型项目：
Service控制：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| try:
创建用户
创建资料
添加积分
commit()
except:
rollback()
|
原因：
保证：
12. 数据库迁移
不要生产环境使用：
1
| Base.metadata.create_all()
|
原因：
无法管理历史变化。
生产：
使用：
流程：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
| 修改Model
↓
alembic revision
↓
生成迁移文件
↓
alembic upgrade
↓
数据库更新
|
13. 完整请求流程
例：
注册用户
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
| POST /users
↓
API
接收JSON
↓
Schema
验证参数
↓
Service
处理注册逻辑
↓
Repository
保存数据库
↓
Model
映射数据
↓
PostgreSQL
存储
|
14. 如果做 AI 后端
普通后端：
1
2
3
4
5
6
7
8
9
10
11
12
13
| API
↓
Service
↓
Repository
↓
Database
|
AI 后端：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
| API
↓
Service
↓
Agent
↓
+----------------+
Tools
Memory
RAG
Vector DB
LLM
+----------------+
↓
Database
|
常见目录：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
| app/
├── agents/
├── tools/
├── chains/
├── memory/
├── vectorstore/
├── services/
└── repositories/
|
最后记忆口诀 🐱
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
| API
负责进来
Schema
负责格式
Service
负责为什么做
Repository
负责怎么存取
Model
负责存什么
Database
负责存在哪里
|
一个成熟 Python 后端的核心不是“文件夹多”，而是：
每一层只做自己的事情。
小项目可以：
1
| API → Service → Database
|
大型项目：
1
| API → Service → Repository → ORM → Database
|
慢慢演进即可。🐾
