# 分层架构设计

本章详细描述 的三层架构设计，包括各层的职责边界、依赖方向、通信方式，并以岗位（Position）模块为实例贯穿说明。

## 三层架构概览

:::tip 架构分层原则
采用经典的三层架构，核心原则是：**依赖单向、职责单一、接口隔离**。上层只依赖下层接口，下层不感知上层存在。
:::

```
┌─────────────────────────────────────────────────────────────┐
│ HTTP 层 (Endpoint) │
│ api/v1/endpoints/position.py │
│ 职责：路由定义 · 权限装饰器 · 参数接收 · 响应返回 │
│ 原则：不含业务逻辑，仅做请求转发 │
└──────────────────────────┬──────────────────────────────────┘
 │ 调用
 ▼
┌─────────────────────────────────────────────────────────────┐
│ 业务层 (Service) │
│ modules/system/position/service.py │
│ 职责：业务逻辑 · 校验规则 · 字段组装 · 序列化加工 │
│ 原则：不直接操作数据库，通过 Repository 访问数据 │
└──────────────────────────┬──────────────────────────────────┘
 │ 调用
 ▼
┌─────────────────────────────────────────────────────────────┐
│ 数据层 (Repository) │
│ modules/system/position/repository.py │
│ 职责：数据库 CRUD · 查询条件组装 · 软删除过滤 │
│ 原则：只做数据访问原语，不做业务校验和响应封装 │
└──────────────────────────┬──────────────────────────────────┘
 │
 ▼
┌─────────────────────────────────────────────────────────────┐
│ 数据库 (MySQL / PostgreSQL / etc.) │
└─────────────────────────────────────────────────────────────┘
```

## 各层详细职责

### 第一层：HTTP 层（Endpoint）

**目录位置**：`src/api/v1/endpoints/{module}.py`

**核心职责**：

1. **路由定义**：声明 HTTP 方法、URL 路径、请求参数类型
2. **权限控制**：通过 `@permission_required` 装饰器声明所需权限
3. **演示模式保护**：通过 `@check_demo` 装饰器阻止演示环境的写操作
4. **参数接收**：通过 Pydantic 模型自动校验请求体
5. **响应返回**：直接返回 Service 层的 `R` 对象

**设计原则**：

- 不包含任何业务逻辑
- 不直接访问数据库
- 仅做请求转发和响应返回
- 权限字符串遵循 `sys:{module}:{action}` 格式

**代码示例**（岗位模块）：

```python
# src/api/v1/endpoints/position.py
# +======================================================================
# | 模块: 岗位路由层
# | 说明: 提供岗位信息的增删改查、状态管理、列表获取等 API 接口
# +======================================================================

from fastapi import APIRouter, Request

from modules.system.position.schemas import PositionForm, PositionStatusForm
from core.access_decorators import check_demo
from core.access_decorators import permission_required
from modules.system.position.service import position_service

from core import R

# ============================================================
# 创建路由实例
# ============================================================
router = APIRouter()


# ============================================================
# 查询分页数据
# ============================================================
@router.get('/page', summary='查询分页数据')
@permission_required("sys:position:page")
def page(request: Request):
    """
    获取岗位分页列表
    :param request: FastAPI请求对象
    :return: 分页数据响应
    """
    return position_service.get_page(request)


# ============================================================
# 查询岗位详情
# ============================================================
@router.get('/detail/{id}', summary='查询岗位详情')
@permission_required("sys:position:detail")
def detail(request: Request, id):
    """
    根据岗位ID查询详细信息
    :param request: FastAPI请求对象
    :param id: 岗位ID（路径参数）
    :return: 岗位详情数据
    """
    return R.ok(data=position_service.get_detail(id))


# ============================================================
# 获取岗位列表
# ============================================================
@router.get('/list', summary='获取岗位列表')
@permission_required("sys:position:list")
def get_position_list(request: Request):
    """
    获取所有岗位列表（无分页，用于下拉选择）
    :param request: FastAPI请求对象
    :return: 岗位列表数据
    """
    return R.ok(data=position_service.get_position_list(request))


# ============================================================
# 添加岗位
# ============================================================
@router.post('/add', summary='添加岗位')
@permission_required("sys:position:add")
@check_demo
def add(request: Request, data: PositionForm):
    """
    新增岗位
    :param request: FastAPI请求对象
    :param data: 岗位表单数据
    :return: 添加结果响应
    """
    return position_service.add(request, data)


# ============================================================
# 更新岗位
# ============================================================
@router.put('/update', summary='更新岗位')
@permission_required("sys:position:update")
@check_demo
def update(request: Request, data: PositionForm):
    """
    更新岗位信息
    :param request: FastAPI请求对象
    :param data: 岗位表单数据（必须包含 id 字段）
    :return: 更新结果响应
    """
    return position_service.update(request, data)


# ============================================================
# 删除岗位
# ============================================================
@router.delete('/delete/{id}', summary='删除岗位')
@permission_required("sys:position:delete")
@check_demo
def delete(request: Request, id):
    """
    根据ID删除单个岗位
    :param request: FastAPI请求对象
    :param id: 岗位ID（路径参数）
    :return: 删除结果响应
    """
    return position_service.delete(id)


# ============================================================
# 设置岗位状态
# ============================================================
@router.put('/status', summary='设置岗位状态')
@permission_required("sys:position:status")
@check_demo
def status(request: Request, data: PositionStatusForm):
    """
    修改岗位状态（启用/禁用）
    :param request: FastAPI请求对象
    :param data: 状态表单数据
    :return: 状态更新结果响应
    """
    return position_service.update_status(request, data)


# ============================================================
# 批量删除岗位
# ============================================================
@router.delete('/batchDelete', summary='批量删除岗位')
@permission_required("sys:position:batchDelete")
@check_demo
async def batch_delete(request: Request):
    """
    批量删除岗位（请求体需传入 ID 数组）

    Request Body 示例:
        [1, 2, 3]  # 岗位ID数组

    :param request: FastAPI请求对象
    :return: 批量删除结果响应
    """
    return await position_service.batch_delete(request)
```

:::tip 装饰器顺序
装饰器按从上到下执行：先 `@permission_required`（鉴权），再 `@check_demo`（演示模式），最后才是路由函数。批量删除端点为 `async def`，因为需要 `await parse_batch_ids(request)` 异步读取请求体。
:::

### 第二层：业务层（Service）

**目录位置**：`src/modules/{group}/{name}/service.py`

**核心职责**：

1. **业务逻辑编排**：组合多个数据操作完成业务流程
2. **唯一性校验**：通过 `unique_fields` 声明唯一约束
3. **字段组装**：`_build_create_fields` / `_build_update_fields` 组装入库字段
4. **序列化加工**：`_serialize` / `_serialize_detail` 加工响应数据
5. **文件处理**：文件字段迁移、URL 补全
6. **前置/后置钩子**：`_before_add` / `_before_update` / `_before_delete` 扩展点

**设计原则**：

- 通过 Repository 访问数据库，不直接使用 `db.query()`
- 返回 `R` 对象，不做 JSONResponse 封装
- 通过声明差异点定制通用 CRUD，减少重复代码

**代码示例**（岗位模块）：

```python
# src/modules/system/position/service.py
# +======================================================================
# | 模块: 岗位业务逻辑层
# | 说明: 岗位的增删改查、唯一性校验、状态管理等业务处理
# +======================================================================

from typing import Optional

from core.base_service import BaseService
from modules.system.position.models import Position
from modules.system.position.repository import position_repo
from modules.system.user.models import User
from modules.system.user.repository import user_repo
from utils.request import parse_id_list


# ============================================================
# 岗位业务服务类
# ============================================================
class PositionService(BaseService[Position]):
    """岗位业务服务类，继承基础服务获得通用 CRUD 能力"""
    # 数据访问与模型
    repo = position_repo
    model = Position
    # 分页差异点
    page_like_fields = ('name',)
    page_eq_fields = ('status',)
    page_order_by = (('sort', 'asc'),)
    # 唯一性校验
    unique_fields = {'name': '岗位名称不能重复'}

    # ============================================================
    # 删除前校验
    # ============================================================
    def _before_delete(self, ids) -> Optional[str]:
        """删除前校验：存在用户引用该岗位时禁止删除，避免用户岗位悬空"""
        id_list = parse_id_list(str(ids))
        if id_list and user_repo.filter(User.position_id.in_(id_list), User.is_delete == 0).first():
            return "存在用户引用该岗位，请先调整用户岗位"
        return None

    # ============================================================
    # 获取岗位数据列表
    # ============================================================
    def get_position_list(self, request):
        """获取岗位数据列表"""
        # 与 /page 一致的筛选条件：name 模糊、status 精确；保留软删过滤与排序
        query = self._apply_page_filters(self.repo.filter_by(), request)
        query = query.order_by(self.model.sort.asc())
        # 返回结果
        return [v.to_dict() for v in query.all()]


# ============================================================
# 模块级单例
# ============================================================
position_service = PositionService()
```

:::tip Service 层的两种模式
简单 CRUD 模块继承 `BaseService`，只需声明差异点即可获得完整的增删改查能力。复杂模块（如用户、角色、菜单）在继承基础上添加自定义方法，或完全自定义 Service 函数。
:::

### 第三层：数据层（Repository）

**目录位置**：`src/modules/{group}/{name}/repository.py`

**核心职责**：

1. **CRUD 操作**：`create` / `update` / `batch_delete` / `get_by_id` 等
2. **查询构建**：`filter` / `filter_by` / `get_one` / `get_all` / `count`
3. **分页查询**：`paginate` 返回 `(items, total)` 元组
4. **软删除过滤**：等值方法自动追加 `is_delete=0`
5. **数据清洗**：`_clean_model_data` 将 camelCase 转 snake_case

**设计原则**：

- 只做数据访问原语，不做 R 封装
- 等值方法自动软删过滤，`filter()` 为原始出口
- 删除的 R 响应由 Service 层 `batch_delete_with_r` 统一产出

**代码示例**（岗位模块）：

```python
# src/modules/system/position/repository.py
# +======================================================================
# | 模块: 岗位数据访问层
# | 说明: 封装岗位模型的数据访问操作
# +======================================================================

"""modules/system/position 数据访问层。"""
from modules.system.position.models import Position
from core.base_repository import BaseRepository


# ============================================================
# 岗位仓库类
# ============================================================
class PositionRepository(BaseRepository[Position]):
    """岗位数据仓库，继承基础仓库获得通用 CRUD 能力"""
    pass


# ============================================================
# 仓库实例
# ============================================================
position_repo = PositionRepository(Position)
```

:::tip Repository 基类提供的方法
`BaseRepository` 提供以下通用方法，子类可直接使用：

- **查询**：`get_by_id` / `get_by_ids` / `get_one` / `get_all` / `count` / `exists` / `exists_by_field`
- **分页**：`paginate` 返回 `(items, total)`
- **写操作**：`create` / `update` / `batch_delete`
- **条件构建**：`filter`（原始出口） / `filter_by`（等值出口）
:::

## 依赖方向

```
HTTP 层 ──依赖──→ Service 层 ──依赖──→ Repository 层 ──依赖──→ Model
 │ │ │
 │ │ │
 ▼ ▼ ▼
R (响应封装) R (响应封装) BaseRepository (基类)
Pydantic BaseRepository get_db_session()
AccessDecorator BaseService SQLAlchemy ORM
```

:::warning 依赖规则
- HTTP 层只依赖 Service 层，不直接调用 Repository
- Service 层通过 Repository 访问数据库，不直接使用 `db.query()`
- Repository 层只依赖 Model 和数据库会话
- 下层不感知上层存在，不调用上层方法
:::

## 模型层（Model）

**目录位置**：`src/modules/{group}/{name}/models.py`

模型层定义数据库表结构，继承 `base_model`（通用字段）和 `base_db`（持久化方法）。

```python
# src/modules/system/position/models.py
from sqlalchemy import Column, String, Integer, text

from core.base_db import base_db
from core.base_model import base_model
from core.config import DB_PREFIX


# ============================================================
# 岗位模型
# ============================================================
class Position(base_model, base_db):
    """岗位模型类"""
    # ============================================================
    # 表名配置
    # ============================================================
    __tablename__ = DB_PREFIX + "position"
    __table_comment__ = "岗位表"

    # ============================================================
    # 字段定义
    # ============================================================
    # 岗位名称
    name = Column(String(255), nullable=False, index=True, comment="岗位名称")
    # 岗位状态：1-在用 2-停用
    status = Column(Integer, default=0, server_default=text('0'), index=True, comment="岗位状态：1-在用 2-停用")
    # 岗位排序
    sort = Column(Integer, default=0, server_default=text('0'), comment="岗位排序")

    # ============================================================
    # 内置方法
    # ============================================================
    def __repr__(self):
        """返回岗位名称作为字符串表示"""
        return '岗位：{}'.format(self.name)
```

## Schema 层（校验）

**目录位置**：`src/modules/{group}/{name}/schemas.py`

Schema 层定义请求参数的校验规则，使用 Pydantic v2 的 `BaseModel` + `Field`。

```python
# src/modules/system/position/schemas.py
# +======================================================================
# | 模块: 岗位表单验证
# | 说明: 岗位创建/编辑/状态更新的请求数据校验
# +======================================================================

from typing import Optional

from pydantic import BaseModel, Field
from core.base_schemas import BaseForm


# ============================================================
# 岗位表单类
# ============================================================
class PositionForm(BaseForm):
    """岗位创建/编辑表单"""
    name: str = Field(..., min_length=1, max_length=150, description="岗位名称")
    status: int = Field(..., ge=1, le=2, description="岗位状态：1-在用 2-停用")
    sort: int = Field(..., ge=0, le=99999, description="岗位排序")


# ============================================================
# 设置状态表单类
# ============================================================
class PositionStatusForm(BaseModel):
    """岗位状态更新表单"""
    id: int = Field(..., gt=0, description="岗位ID")
    status: int = Field(..., ge=1, le=2, description="岗位状态：1-在用 2-停用")
```

## 完整调用链路示例

以添加岗位为例，展示三层之间的调用关系：

```
POST /api/v1/position/add
│
├─ 1. Endpoint (position.py)
│ @permission_required("sys:position:add")
│ @check_demo
│ def add(request, data: PositionForm):
│ return position_service.add(request, data)
│
├─ 2. Service (service.py)
│ def add(self, request, data):
│ err = self._check_unique(data) # 唯一性校验
│ self._before_add(request, data) # 前置钩子
│ fields = self._build_create_fields() # 字段组装
│ self.repo.create(**fields) # 调用 Repository
│ return R.ok(msg='添加成功')
│
├─ 3. Repository (base_repository.py)
│ def create(self, **fields):
│ obj = self.model(**self._clean_model_data(fields))
│ obj.save() # add + flush
│ return obj
│
├─ 4. Model (base_db.py)
│ def save(self):
│ db = get_db_session()
│ db.add(self)
│ db.flush() # SQL 发送到数据库
│
└─ 5. Database
 INSERT INTO fastapi_position (name, status, sort, create_user, ...)
 VALUES ('高级工程师', 1, 10, '管理员', ...)
```

## 各层文件职责一览

| 文件 | 层次 | 职责 | 是否包含业务逻辑 |
|:---|:---:|:---|:---:|
| `endpoints/position.py` | HTTP | 路由、权限、参数接收 | 否 |
| `position/schemas.py` | HTTP | 请求参数校验规则 | 否 |
| `position/service.py` | 业务 | 业务逻辑、校验、序列化 | 是 |
| `position/repository.py` | 数据 | 数据库 CRUD、查询构建 | 否 |
| `position/models.py` | 数据 | 表结构定义、字段映射 | 否 |

## 总结

三层架构通过依赖单向和职责单一实现了良好的关注点分离。HTTP 层只关心请求接收和响应返回，Service 层只关心业务逻辑编排，Repository 层只关心数据访问。这种分层使得每一层都可以独立测试、独立替换，系统在模块数量增长时仍能保持清晰的代码结构。以岗位模块为例，完整实现一个 CRUD 模块只需 5 个文件，其中 Repository 和 Model 几乎零代码，开发者只需关注 Service 层的业务差异点。