如何设计一个后端项目的架构？

Python 后端项目架构笔记

1. 后端项目核心思想

一个成熟 Python 后端项目通常采用分层架构（Layered Architecture）。

每个人只做自己的事情，不关注不相干的

比如数据库的只curd不做什么安全校验登录

核心目标：

• 降低代码耦合
• 分离职责
• 方便测试
• 方便扩展
• 方便团队协作

整体调用链：

用户请求

    ↓

API Router（接口层）

    ↓

Service（业务层）

    ↓

Repository（数据访问层）

    ↓

Model（数据库模型）

    ↓

Database（数据库）

---

2. 常见项目结构

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（接口层）

位置：

api/

作用：

负责 HTTP 世界和程序世界的连接。

负责：

✅ 接收请求

✅ 参数解析

✅ 调用 Service

✅ 返回响应

例如：

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

    return user_service.create(user)

不要写：

sql = "select * from users"

原因：

API 不应该知道数据库。

---

4. Schema（数据校验层）

位置：

schemas/

作用：

定义：

• 请求格式
• 返回格式

例如：

用户注册：

class UserCreate(BaseModel):

    username:str

    password:str

    email:str

请求：

{
    "username":"tom",
    "password":"123456",
    "email":"[email protected]"
}

Schema负责检查：

• 有没有字段
• 类型对不对
• 格式是否正确

常用：

FastAPI:

Pydantic

---

5. Service（业务逻辑层）⭐

位置：

services/

这是项目的大脑。

负责：

• 业务规则
• 流程控制
• 权限判断
• 事务

例如：

注册用户：

注册流程：

1. 查询邮箱是否存在

2. 密码加密

3. 创建用户

4. 创建用户资料

5. 发送邮件

6. 返回结果

代码：

class UserService:


    def register(self,data):

        check_email()

        hash_password()

        create_user()

        send_email()

Service 不关心：

数据库怎么查询。

---

6. Repository（数据访问层）⭐

位置：

repositories/

作用：

专门负责数据库 CRUD。

例如：

class UserRepository:


    def create(user):

        db.add(user)


    def get_by_id(id):

        return db.query(User)

负责：

✅ 查询

✅ 新增

✅ 修改

✅ 删除

不负责：

❌ 用户权限

❌ 发邮件

❌ 业务流程

---

7. Model（数据库模型）

位置：

models/

作用：

描述数据库表。

例如：

数据库：

users表

对应：

class User(Base):

    __tablename__="users"


    id

    username

    password

ORM关系：

Python对象

      ↓

SQLAlchemy

      ↓

数据库表

---

8. Database 层

位置：

database.py

负责：

Engine

数据库连接池：

engine

Session

数据库会话：

SessionLocal

Base

ORM基类：

class Base(DeclarativeBase):
    pass

结构：

database.py

    |
    |
    ↓

models/user.py

    |
    |
    ↓

数据库表

---

9. Session 生命周期

推荐：

不要：

repo里面创建Session

而是：

Request进入

    ↓

创建Session

    ↓

Repository使用

    ↓

请求结束

    ↓

关闭Session

FastAPI：

def get_db():

    db = SessionLocal()

    try:

        yield db

    finally:

        db.close()

---

10. Repository 和 Service 的区别

Repository

关注：

数据怎么拿？

例如：

get_user_by_email()

---

Service

关注：

为什么拿？

例如：

登录：

用户输入邮箱密码

↓

Service:

    查询用户

    校验密码

    生成Token

↓

返回

---

11. Transaction（事务）

简单项目：

Repository commit：

repo.create()

commit()

大型项目：

Service控制：

try:

    创建用户

    创建资料

    添加积分


    commit()


except:

    rollback()

原因：

保证：

全部成功

或者

全部失败

---

12. 数据库迁移

不要生产环境使用：

Base.metadata.create_all()

原因：

无法管理历史变化。

生产：

使用：

Alembic

流程：

修改Model

↓

alembic revision

↓

生成迁移文件

↓

alembic upgrade

↓

数据库更新

---

13. 完整请求流程

例：

注册用户

POST /users


↓

API

接收JSON


↓

Schema

验证参数


↓

Service

处理注册逻辑


↓

Repository

保存数据库


↓

Model

映射数据


↓

PostgreSQL

存储

---

14. 如果做 AI 后端

普通后端：

API

↓

Service

↓

Repository

↓

Database

AI 后端：

API

↓

Service

↓

Agent

↓

+----------------+

Tools

Memory

RAG

Vector DB

LLM

+----------------+

↓

Database

常见目录：

app/

├── agents/

├── tools/

├── chains/

├── memory/

├── vectorstore/

├── services/

└── repositories/

---

最后记忆口诀 🐱

API

负责进来


Schema

负责格式


Service

负责为什么做


Repository

负责怎么存取


Model

负责存什么


Database

负责存在哪里

一个成熟 Python 后端的核心不是“文件夹多”，而是：

每一层只做自己的事情。

小项目可以：

API → Service → Database

大型项目：

API → Service → Repository → ORM → Database

慢慢演进即可。🐾