签入版本
This commit is contained in:
@@ -0,0 +1,440 @@
|
||||
# 业务逻辑层（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` 过滤已删除数据，批量删除采用逻辑删除方式。
|
||||
Reference in New Issue
Block a user