441 lines
13 KiB
Markdown
441 lines
13 KiB
Markdown
# 业务逻辑层（Service）
|
||
|
||
业务逻辑层是模块开发的第三步，也是最核心的部分。所有 CRUD 操作、业务规则、数据处理都封装在 Service 层的独立函数中。
|
||
|
||
## 文件位置
|
||
|
||
```
|
||
application/example/services.py
|
||
```
|
||
|
||
## 命名规范
|
||
|
||
| 函数类型 | 命名格式 | 示例 |
|
||
|:----|:----|:----|
|
||
| 分页查询 | `get_<m>_page` | `get_example_page` |
|
||
| 列表查询 | `get_<m>_list` | `get_example_list` |
|
||
| 详情查询 | `get_<m>_detail` | `get_example_detail` |
|
||
| 添加 | `add_<m>` | `add_example` |
|
||
| 更新 | `update_<m>` | `update_example` |
|
||
| 删除 | `delete_<m>s` | `delete_examples` |
|
||
| 状态更新 | `update_<m>_status` | `update_example_status` |
|
||
| 数据列表 | `get_<m>_data` | `get_example_data` |
|
||
|
||
## 分页查询
|
||
|
||
```python
|
||
def get_example_page(request):
|
||
"""
|
||
查询案例分页数据
|
||
|
||
Args:
|
||
request: HttpRequest对象
|
||
- pageNo: 当前页码（可选，默认为1）
|
||
- pageSize: 每页记录数（可选，默认为PAGE_SIZE）
|
||
- name: 案例名称（可选，模糊查询）
|
||
- type: 案例类型（可选，精确匹配）
|
||
- status: 案例状态（可选，精确匹配）
|
||
|
||
Returns:
|
||
R: 包含分页数据的JSON响应
|
||
"""
|
||
try:
|
||
# 获取分页参数
|
||
page_no = int(request.GET.get('pageNo', 1))
|
||
page_size = int(request.GET.get('pageSize', PAGE_SIZE))
|
||
|
||
# 构建基础查询（只查询未删除的记录）
|
||
query = Example.objects.filter(is_delete=False)
|
||
|
||
# 应用筛选条件
|
||
query = _apply_filters(query, request)
|
||
|
||
# 按排序字段升序排列
|
||
query = query.order_by("sort")
|
||
|
||
# 执行分页查询
|
||
paginator = Paginator(query, page_size)
|
||
try:
|
||
page_list = paginator.page(page_no)
|
||
except (PageNotAnInteger, InvalidPage, EmptyPage):
|
||
page_list = paginator.page(1)
|
||
page_no = 1
|
||
|
||
# 构建并返回分页数据
|
||
page_data = _build_page_data(page_list, paginator, page_no, page_size)
|
||
return R.ok(data=page_data)
|
||
|
||
except Exception as e:
|
||
logging.error(f"查询案例分页数据异常: {str(e)}")
|
||
return R.failed(msg="查询失败，请稍后重试")
|
||
```
|
||
|
||
### 筛选条件应用
|
||
|
||
```python
|
||
def _apply_filters(queryset, request):
|
||
"""应用查询筛选条件（私有辅助函数）"""
|
||
# 案例名称模糊筛选
|
||
name = request.GET.get('name')
|
||
if name:
|
||
queryset = queryset.filter(name__contains=name)
|
||
|
||
# 案例类型筛选（精确匹配）
|
||
type = request.GET.get('type')
|
||
if type:
|
||
queryset = queryset.filter(type=type)
|
||
|
||
# 案例状态筛选（精确匹配）
|
||
status = request.GET.get('status')
|
||
if status:
|
||
queryset = queryset.filter(status=status)
|
||
|
||
return queryset
|
||
```
|
||
|
||
### 分页数据构建
|
||
|
||
```python
|
||
def _build_page_data(page_list, paginator, page_no, page_size):
|
||
"""构建分页返回数据（私有辅助函数）"""
|
||
records = []
|
||
for item in page_list:
|
||
record = {
|
||
'id': item.id,
|
||
'name': item.name,
|
||
'avatar': get_file_url(item.avatar) if item.avatar else "",
|
||
'type': item.type,
|
||
'status': item.status,
|
||
'sort': item.sort,
|
||
'createUser': item.create_user,
|
||
'createTime': format_datetime(item.create_time),
|
||
'updateUser': item.update_user,
|
||
'updateTime': format_datetime(item.update_time),
|
||
}
|
||
records.append(record)
|
||
|
||
return {
|
||
'records': records,
|
||
'total': paginator.count,
|
||
'size': page_size,
|
||
'current': page_no,
|
||
'pages': paginator.num_pages
|
||
}
|
||
```
|
||
|
||
### 分页响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"records": [...],
|
||
"total": 100,
|
||
"size": 10,
|
||
"current": 1,
|
||
"pages": 10
|
||
},
|
||
"msg": "操作成功",
|
||
"ok": true
|
||
}
|
||
```
|
||
|
||
## 详情查询
|
||
|
||
```python
|
||
def get_example_detail(id):
|
||
"""
|
||
根据ID查询案例详情
|
||
|
||
Args:
|
||
id: 案例ID
|
||
|
||
Returns:
|
||
dict/None: 案例详情字典，不存在时返回None
|
||
"""
|
||
try:
|
||
instance = Example.objects.filter(is_delete=False, id=id).first()
|
||
if not instance:
|
||
return None
|
||
|
||
return {
|
||
'id': instance.id,
|
||
'name': instance.name,
|
||
'avatar': get_file_url(instance.avatar) if instance.avatar else "",
|
||
'type': instance.type,
|
||
'status': instance.status,
|
||
'sort': instance.sort,
|
||
}
|
||
except Exception as e:
|
||
logging.error(f"查询案例详情异常，ID: {id}, 错误: {str(e)}")
|
||
return None
|
||
```
|
||
|
||
## 添加记录
|
||
|
||
```python
|
||
def add_example(request):
|
||
"""
|
||
添加案例
|
||
|
||
处理流程：
|
||
1. 解析请求体中的JSON数据
|
||
2. 表单验证
|
||
3. 处理头像图片（保存到 example 目录）
|
||
4. 创建数据库记录
|
||
"""
|
||
# 解析请求参数
|
||
data, error = parse_request_body(request)
|
||
if error:
|
||
return R.failed(msg=error)
|
||
|
||
# 表单验证
|
||
form = forms.ExampleForm(data)
|
||
if not form.is_valid():
|
||
return R.failed(msg=regular.get_err(form))
|
||
|
||
try:
|
||
cleaned_data = form.cleaned_data
|
||
|
||
# 处理头像图片
|
||
avatar = cleaned_data.get('avatar')
|
||
if avatar:
|
||
avatar = save_file(avatar, "example")
|
||
|
||
# 创建案例记录
|
||
Example.objects.create(
|
||
name=cleaned_data.get('name'),
|
||
avatar=avatar,
|
||
type=cleaned_data.get('type'),
|
||
status=cleaned_data.get('status'),
|
||
sort=cleaned_data.get('sort'),
|
||
create_user=get_username(request),
|
||
update_user=get_username(request)
|
||
)
|
||
return R.ok(msg="创建成功")
|
||
except Exception as e:
|
||
logging.error(f"添加案例异常: {str(e)}")
|
||
return R.failed(msg="添加失败，请稍后重试")
|
||
```
|
||
|
||
### 添加流程说明
|
||
|
||
```
|
||
请求 → parse_request_body → 表单验证 → 处理文件 → ORM.create → 返回结果
|
||
```
|
||
|
||
| 步骤 | 函数 | 说明 |
|
||
|:----|:----|:----|
|
||
| 解析请求体 | `parse_request_body(request)` | 解析 JSON 请求体 |
|
||
| 表单验证 | `forms.ExampleForm(data)` | 验证数据合法性 |
|
||
| 处理文件 | `save_file(url, dir)` | 临时文件迁移到正式目录 |
|
||
| 创建记录 | `Example.objects.create(...)` | ORM 创建数据库记录 |
|
||
| 获取用户名 | `get_username(request)` | 从 JWT token 解析当前用户 |
|
||
|
||
## 更新记录
|
||
|
||
```python
|
||
def update_example(request):
|
||
"""
|
||
更新案例
|
||
|
||
处理流程：
|
||
1. 解析请求体中的JSON数据
|
||
2. 验证案例ID
|
||
3. 表单验证
|
||
4. 查询现有记录
|
||
5. 处理头像图片（如有变化则保存新图片）
|
||
6. 更新各字段
|
||
7. 保存更新
|
||
"""
|
||
# 解析请求参数
|
||
data, error = parse_request_body(request)
|
||
if error:
|
||
return R.failed(msg=error)
|
||
|
||
# 验证案例ID
|
||
instance_id = data.get('id')
|
||
if not instance_id or not str(instance_id).isdigit() or int(instance_id) <= 0:
|
||
return R.failed("案例ID无效")
|
||
instance_id = int(instance_id)
|
||
|
||
# 表单验证
|
||
form = forms.ExampleForm(data)
|
||
if not form.is_valid():
|
||
return R.failed(msg=regular.get_err(form))
|
||
|
||
try:
|
||
# 查询案例记录
|
||
instance = Example.objects.filter(id=instance_id, is_delete=False).first()
|
||
if not instance:
|
||
return R.failed("案例不存在")
|
||
|
||
cleaned_data = form.cleaned_data
|
||
|
||
# 处理头像图片（仅当有新图片且与当前不同时保存）
|
||
avatar = cleaned_data.get('avatar')
|
||
if avatar and avatar != instance.avatar:
|
||
avatar = save_file(avatar, "example")
|
||
else:
|
||
avatar = instance.avatar
|
||
|
||
# 更新各字段
|
||
instance.name = cleaned_data.get('name')
|
||
instance.avatar = avatar
|
||
instance.type = cleaned_data.get('type')
|
||
instance.status = cleaned_data.get('status')
|
||
instance.sort = cleaned_data.get('sort')
|
||
instance.update_user = get_username(request)
|
||
instance.save()
|
||
|
||
return R.ok(msg="更新成功")
|
||
except Exception as e:
|
||
logging.error(f"更新案例异常，ID: {instance_id}, 错误: {str(e)}")
|
||
return R.failed(msg="更新失败，请稍后重试")
|
||
```
|
||
|
||
## 删除记录（批量）
|
||
|
||
```python
|
||
def delete_examples(instance_ids):
|
||
"""
|
||
删除案例（批量删除）
|
||
|
||
采用逻辑删除方式（is_delete=True），而非物理删除。
|
||
支持逗号分隔的多个ID。
|
||
|
||
Args:
|
||
instance_ids: 案例ID字符串，多个ID用逗号分隔
|
||
例如: "1" 或 "1,2,3"
|
||
"""
|
||
if not instance_ids:
|
||
return R.failed("记录ID不存在")
|
||
|
||
try:
|
||
# 解析ID列表
|
||
id_list = [int(id_str.strip()) for id_str in instance_ids.split(',') if id_str.strip()]
|
||
if not id_list:
|
||
return R.failed("无效的记录ID")
|
||
|
||
# 批量更新删除标识（逻辑删除）
|
||
updated_count = Example.objects.filter(
|
||
id__in=id_list,
|
||
is_delete=False
|
||
).update(is_delete=True)
|
||
|
||
return R.ok(msg=f"本次共删除{updated_count}条数据")
|
||
except ValueError:
|
||
return R.failed("记录ID格式错误")
|
||
except Exception as e:
|
||
logging.error(f"删除案例异常，IDs: {instance_ids}, 错误: {str(e)}")
|
||
return R.failed(msg="删除失败，请稍后重试")
|
||
```
|
||
|
||
### 逻辑删除说明
|
||
|
||
项目采用逻辑删除（软删除），而非物理删除：
|
||
|
||
```python
|
||
# 逻辑删除：设置 is_delete=True
|
||
Example.objects.filter(id__in=id_list).update(is_delete=True)
|
||
|
||
# 物理删除（不推荐）：真正删除数据库记录
|
||
Example.objects.filter(id__in=id_list).delete()
|
||
```
|
||
|
||
所有查询都必须加 `is_delete=False` 条件过滤已删除的数据。
|
||
|
||
## 状态更新
|
||
|
||
```python
|
||
def update_example_status(request):
|
||
"""
|
||
更新案例状态
|
||
|
||
单独更新案例的启用/禁用状态，不涉及其他字段。
|
||
"""
|
||
# 解析请求参数
|
||
data, error = parse_request_body(request)
|
||
if error:
|
||
return R.failed(msg=error)
|
||
|
||
# 验证案例ID
|
||
instance_id = data.get('id')
|
||
if not instance_id or not str(instance_id).isdigit() or int(instance_id) <= 0:
|
||
return R.failed("案例ID无效")
|
||
instance_id = int(instance_id)
|
||
|
||
# 验证状态值（1=启用, 2=禁用）
|
||
status = data.get('status')
|
||
if status is None:
|
||
return R.failed("状态值不能为空")
|
||
try:
|
||
status = int(status)
|
||
if status not in [1, 2]:
|
||
return R.failed("状态值无效")
|
||
except ValueError:
|
||
return R.failed("状态值格式错误")
|
||
|
||
try:
|
||
instance = Example.objects.filter(id=instance_id, is_delete=False).first()
|
||
if not instance:
|
||
return R.failed("案例不存在")
|
||
|
||
instance.status = status
|
||
instance.update_user = get_username(request)
|
||
instance.save()
|
||
|
||
return R.ok(msg="状态更新成功")
|
||
except Exception as e:
|
||
logging.error(f"更新案例状态异常，ID: {instance_id}, 错误: {str(e)}")
|
||
return R.failed(msg="状态更新失败，请稍后重试")
|
||
```
|
||
|
||
## 数据列表（下拉选择）
|
||
|
||
```python
|
||
def get_example_data():
|
||
"""
|
||
获取所有启用的案例列表
|
||
|
||
通常用于前端下拉选择框等场景。
|
||
只返回 status=1（启用）且未删除的记录。
|
||
"""
|
||
try:
|
||
queryset = Example.objects.filter(
|
||
is_delete=False,
|
||
status=1
|
||
).order_by("sort").values()
|
||
|
||
return list(queryset)
|
||
except Exception as e:
|
||
logging.error(f"获取案例列表异常: {str(e)}")
|
||
return []
|
||
```
|
||
|
||
## 常用工具函数
|
||
|
||
| 函数 | 来源 | 用途 |
|
||
|:----|:----|:----|
|
||
| `parse_request_body(request)` | `utils/common.py` | 解析 JSON 请求体 |
|
||
| `regular.get_err(form)` | `utils/regular.py` | 提取表单错误信息 |
|
||
| `get_username(request)` | `utils/security.py` | 从 JWT 获取当前用户名 |
|
||
| `get_file_url(path)` | `utils/common.py` | 拼接文件完整 URL |
|
||
| `save_file(url, dir)` | `utils/common.py` | 保存文件到正式目录 |
|
||
| `format_datetime(dt)` | `utils/common.py` | 格式化日期时间 |
|
||
| `R.ok()` / `R.failed()` | `utils/R.py` | 统一响应格式 |
|
||
|
||
## 开发要点
|
||
|
||
1. **所有查询都要加 `is_delete=False`**：过滤已删除的数据
|
||
2. **使用 `parse_request_body()` 解析请求体**：统一的 JSON 解析方式
|
||
3. **表单验证失败时使用 `regular.get_err()` 提取错误**：统一的错误信息格式
|
||
4. **使用 `get_username(request)` 获取当前用户**：从 JWT token 解析
|
||
5. **文件处理使用 `save_file()`**：临时文件迁移到正式目录
|
||
6. **批量删除支持逗号分隔的多个 ID**：如 "1,2,3"
|
||
7. **所有异常都要捕获并记录日志**：使用 `logging.error()`
|
||
|
||
## 总结
|
||
|
||
Service 层封装所有业务逻辑，每个 CRUD 操作都是独立的函数。使用 `parse_request_body` 解析请求体，`forms.ModelForm` 验证数据，`R.ok()` / `R.failed()` 返回统一响应。所有查询都必须加 `is_delete=False` 过滤已删除数据，批量删除采用逻辑删除方式。
|