# mysql_db_manager

**Repository Path**: Tender-Liu/mysql_db_manager

## Basic Information

- **Project Name**: mysql_db_manager
- **Description**: 使用SQLAlchemy构建的Python数据库应用项目，经典的三层架构（业务逻辑层、数据访问层、模型层），并辅以配置、工具等模块，使代码结构清晰、易于维护。
- **Primary Language**: Python
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 3
- **Forks**: 2
- **Created**: 2025-07-19
- **Last Updated**: 2025-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SQLAlchemy分层架构教学项目

欢迎来到这个使用SQLAlchemy构建的Python数据库应用项目！本项目旨在通过一个清晰、分层的结构，帮助初学者理解和掌握如何在实际项目中应用SQLAlchemy进行数据库操作，特别是对于刚学完面向对象的同学。

## 一、 项目架构解析

本项目采用经典的三层架构（业务逻辑层、数据访问层、模型层），并辅以配置、工具等模块，使代码结构清晰、易于维护。


**各层职责：**

1.  **模型层 (`models`)**: 定义数据表的结构。每一个类代表一张表，类的属性对应表的字段。这是ORM（对象关系映射）的基础。
2.  **数据访问层 (`repositories`)**: 也叫仓储层。这一层专门负责与数据库进行交互，封装所有SQL查询（无论是ORM查询还是原生SQL）。它的任务就是执行CRUD（增删改查），不包含任何业务逻辑。
3.  **业务逻辑层 (`services`)**: 这一层是业务的核心。它调用数据访问层的一个或多个方法，组合起来完成一个完整的业务功能（例如：“用户注册”可能需要先创建用户，再发送欢迎邮件）。**事务管理也应该在这一层完成**。
4.  **应用入口 (`app.py`)**: 程序的起点，负责调用业务逻辑层来执行具体任务。在Web应用中，这一层通常是API的路由处理函数。
5.  **工具和配置 (`utils`, `config`)**: 提供公共能力，如数据库连接管理、装饰器、配置加载等，供其他模块使用。

## 二、 如何运行项目

1.  **安装依赖**: 打开终端，进入项目根目录，运行以下命令：
    ```bash
    pip install -r requirements.txt
    ```
2.  **配置数据库**: 打开`config.yml`文件，根据你自己的MySQL数据库信息，修改`host`, `port`, `username`, `password`, `database`等字段。
3.  **运行程序**: 在终端中运行`app.py`：
    ```bash
    python app.py
    ```
    程序会自动创建`users`表，并执行一个创建和查询用户的示例。

## 三、 如何进行二次开发（重要！）

假设我们需要添加一个新的功能：**文章管理**。下面是标准的开发步骤：

### 第1步：创建模型 (`models/post.py`)

首先，定义`Post`模型来映射数据库中的`posts`表。

```python
# 在 models/post.py 中
from sqlalchemy import Column, Integer, String, Text, ForeignKey
from utils.db_manager import Base

class Post(Base):
    __tablename__ = 'posts'
    id = Column(Integer, primary_key=True)
    title = Column(String(100), nullable=False)
    content = Column(Text, nullable=False)
    user_id = Column(Integer, ForeignKey('users.id')) # 设置外键
```

### 第2步：创建数据访问层 (`repositories/post_repository.py`)

创建`PostRepository`来封装对`posts`表的数据库操作。

```python
# 在 repositories/post_repository.py 中
from models.post import Post

class PostRepository:
    def create(self, session, post_data):
        post = Post(**post_data)
        session.add(post)
        session.flush()
        return post

    def get_by_user_id(self, session, user_id):
        return session.query(Post).filter(Post.user_id == user_id).all()
```

### 第3步：创建业务逻辑层 (`services/post_service.py`)

创建`PostService`来处理与文章相关的业务逻辑，并使用`@transactional`装饰器管理事务。

```python
# 在 services/post_service.py 中
from repositories.post_repository import PostRepository
from utils.decorators import transactional

class PostService:
    def __init__(self):
        self.post_repository = PostRepository()

    @transactional
    def create_post(self, session, post_data):
        # 可以在这里添加业务逻辑，比如检查标题是否合规等
        return self.post_repository.create(session, post_data)

    @transactional
    def get_posts_for_user(self, session, user_id):
        return self.post_repository.get_by_user_id(session, user_id)
```

### 第4步：在应用中使用 (`app.py`)

最后，在`app.py`中调用`PostService`来使用新功能。

```python
# 在 app.py 中
# ... 引入 PostService
from services.post_service import PostService

# ... 在 main 函数中
post_service = PostService()
post_service.create_post({
    'title': 'My First Post',
    'content': 'This is a test.',
    'user_id': new_user.id # 使用之前创建的用户的ID
})

user_posts = post_service.get_posts_for_user(new_user.id)
print(f"{new_user.username}的文章: {user_posts}")
```

通过遵循这个流程，你可以轻松地为项目添加任何新的功能，同时保持代码结构的清晰和一致。