签入版本
This commit is contained in:
@@ -0,0 +1,312 @@
|
||||
# Service层规范
|
||||
|
||||
## 概述
|
||||
|
||||
Service 层是业务逻辑层，每个模块的 `services.py` 包含该模块的所有业务函数。采用函数式风格，每个函数对应一个业务操作。
|
||||
|
||||
:::tip 设计原则
|
||||
- 所有业务逻辑集中在 Service 层
|
||||
- View 层只负责接收请求和返回响应
|
||||
- Model 层只负责数据定义
|
||||
- Form 层只负责数据验证
|
||||
:::
|
||||
|
||||
## 函数命名规范
|
||||
|
||||
| 函数名 | 说明 | 参数 | 返回值 |
|
||||
|:----|:----|:----|:----|
|
||||
| `get_{m}_page` | 分页查询 | request | R.ok(data=page_data) |
|
||||
| `get_{m}_list` | 列表查询（不分页） | request | list |
|
||||
| `get_{m}_detail` | 详情查询 | id | dict/None |
|
||||
| `add_{m}` | 添加记录 | request | R.ok/R.failed |
|
||||
| `update_{m}` | 更新记录 | request | R.ok/R.failed |
|
||||
| `delete_{m}s` | 删除记录（支持批量） | instance_ids | R.ok/R.failed |
|
||||
| `update_{m}_status` | 更新状态 | request | R.ok/R.failed |
|
||||
| `get_{m}_data` | 获取数据列表（下拉选择） | - | list |
|
||||
|
||||
## 完整示例
|
||||
|
||||
以案例模块为例，`application/example/services.py` 的典型结构：
|
||||
|
||||
```python
|
||||
import logging
|
||||
from django.core.paginator import Paginator, PageNotAnInteger, InvalidPage, EmptyPage
|
||||
from application.example import forms
|
||||
from application.example.models import Example
|
||||
from constant.constants import PAGE_SIZE
|
||||
from utils import R, regular
|
||||
from utils.common import format_datetime, parse_request_body, save_file
|
||||
from utils.security import get_username
|
||||
|
||||
|
||||
# =============================================================
|
||||
# 分页查询服务
|
||||
# =============================================================
|
||||
|
||||
def get_example_page(request):
|
||||
"""查询案例分页数据"""
|
||||
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="查询失败，请稍后重试")
|
||||
|
||||
|
||||
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
|
||||
|
||||
|
||||
def _build_page_data(page_list, paginator, page_no, page_size):
|
||||
"""构建分页返回数据"""
|
||||
records = []
|
||||
for item in page_list:
|
||||
record = {
|
||||
'id': item.id,
|
||||
'name': item.name,
|
||||
'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
|
||||
}
|
||||
|
||||
|
||||
# =============================================================
|
||||
# 详情查询服务
|
||||
# =============================================================
|
||||
|
||||
def get_example_detail(id):
|
||||
"""根据ID查询案例详情"""
|
||||
try:
|
||||
instance = Example.objects.filter(is_delete=False, id=id).first()
|
||||
if not instance:
|
||||
return None
|
||||
|
||||
return {
|
||||
'id': instance.id,
|
||||
'name': instance.name,
|
||||
'type': instance.type,
|
||||
'status': instance.status,
|
||||
'sort': instance.sort,
|
||||
}
|
||||
except Exception as e:
|
||||
logging.error(f"查询案例详情异常，ID: {id}, 错误: {str(e)}")
|
||||
return None
|
||||
|
||||
|
||||
# =============================================================
|
||||
# 添加服务
|
||||
# =============================================================
|
||||
|
||||
def add_example(request):
|
||||
"""添加案例"""
|
||||
# 解析请求参数
|
||||
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
|
||||
Example.objects.create(
|
||||
name=cleaned_data.get('name'),
|
||||
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="添加失败，请稍后重试")
|
||||
|
||||
|
||||
# =============================================================
|
||||
# 更新服务
|
||||
# =============================================================
|
||||
|
||||
def update_example(request):
|
||||
"""更新案例"""
|
||||
data, error = parse_request_body(request)
|
||||
if error:
|
||||
return R.failed(msg=error)
|
||||
|
||||
instance_id = data.get('id')
|
||||
if not instance_id:
|
||||
return R.failed("案例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
|
||||
instance.name = cleaned_data.get('name')
|
||||
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="更新失败，请稍后重试")
|
||||
|
||||
|
||||
# =============================================================
|
||||
# 删除服务（支持批量）
|
||||
# =============================================================
|
||||
|
||||
def delete_examples(instance_ids):
|
||||
"""删除案例（批量删除）"""
|
||||
if not instance_ids:
|
||||
return R.failed("记录ID不存在")
|
||||
|
||||
try:
|
||||
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="删除失败，请稍后重试")
|
||||
|
||||
|
||||
# =============================================================
|
||||
# 状态更新服务
|
||||
# =============================================================
|
||||
|
||||
def update_example_status(request):
|
||||
"""更新案例状态"""
|
||||
data, error = parse_request_body(request)
|
||||
if error:
|
||||
return R.failed(msg=error)
|
||||
|
||||
instance_id = data.get('id')
|
||||
if not instance_id:
|
||||
return R.failed("案例ID无效")
|
||||
|
||||
status = data.get('status')
|
||||
if status is None:
|
||||
return R.failed("状态值不能为空")
|
||||
|
||||
try:
|
||||
instance = Example.objects.filter(id=instance_id, is_delete=False).first()
|
||||
if not instance:
|
||||
return R.failed("案例不存在")
|
||||
|
||||
instance.status = int(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="状态更新失败，请稍后重试")
|
||||
```
|
||||
|
||||
## 关键约定
|
||||
|
||||
### 请求体解析
|
||||
|
||||
所有 POST/PUT/DELETE 请求使用 `parse_request_body(request)` 解析 JSON 请求体：
|
||||
|
||||
```python
|
||||
data, error = parse_request_body(request)
|
||||
if error:
|
||||
return R.failed(msg=error)
|
||||
```
|
||||
|
||||
### 表单验证
|
||||
|
||||
在 ORM 操作之前进行表单验证：
|
||||
|
||||
```python
|
||||
form = forms.ExampleForm(data)
|
||||
if not form.is_valid():
|
||||
return R.failed(msg=regular.get_err(form))
|
||||
```
|
||||
|
||||
### 操作人记录
|
||||
|
||||
创建和更新操作需记录操作人：
|
||||
|
||||
```python
|
||||
from utils.security import get_username
|
||||
|
||||
instance.create_user = get_username(request)
|
||||
instance.update_user = get_username(request)
|
||||
```
|
||||
|
||||
### 异常处理
|
||||
|
||||
所有 Service 函数使用 try/except 包裹，记录日志并返回友好错误信息：
|
||||
|
||||
```python
|
||||
try:
|
||||
# 业务逻辑
|
||||
except Exception as e:
|
||||
logging.error(f"操作异常: {str(e)}")
|
||||
return R.failed(msg="操作失败，请稍后重试")
|
||||
```
|
||||
|
||||
## 总结
|
||||
|
||||
Service 层采用函数式风格，每个函数对应一个业务操作。关键约定：使用 `parse_request_body` 解析请求体、表单验证在 ORM 操作之前、记录操作人、try/except 包裹异常处理。所有查询过滤 `is_delete=False`，返回标准 R 响应。
|
||||
Reference in New Issue
Block a user