跳到主要内容
版本：Next

排序调整

本文档引用的文件

目录​

  1. 简介
  2. API端点说明
  3. 路径参数详解
  4. 排序逻辑与持久化机制
  5. 业务场景与排序字段意义
  6. 权限与业务约束
  7. 响应示例
  8. 错误码说明
  9. 调用流程图

简介​

本文档详细说明了用于调整实体排序的API接口 PUT /{id}/AdjustSort/{sort} 的功能、参数、行为及使用约束。该接口允许通过指定实体ID和目标排序值来重新设置实体在列表中的展示顺序，广泛应用于前端展示顺序控制等业务场景。

API端点说明​

  • 端点路径: PUT /{id}/AdjustSort/{sort}
  • 功能描述: 调整指定实体的排序值，并自动重新计算其他实体的排序以保持连续性
  • 控制器: MyEntityNameController
  • 对应方法: AdjustSortAsync(Guid id, int sort)

Section sources

路径参数详解​

参数类型必需描述
idGuid是实体的唯一主键标识符，用于定位需要调整排序的具体记录
sortint是目标排序值，表示该实体在排序列表中期望的位置（从1开始）

Section sources

排序逻辑与持久化机制​

当调用 AdjustSortAsync 接口时，系统执行以下步骤：

  1. 从数据库获取所有实体并按当前排序字段升序排列
  2. 根据目标排序值重新分配所有实体的排序编号，确保排序连续且无重复
  3. 若目标排序位置前移（即排序值变小），则原位置之后、目标位置之前的实体排序值自动加1
  4. 若目标排序位置后移（即排序值变大），则原位置之前、目标位置之后的实体排序值自动减1
  5. 更新目标实体的排序值为指定值
  6. 所有变更通过 UpdateManyAsync 方法批量持久化到数据库

实体的排序字段在 MyEntityName 领域模型中定义为 Sort，类型为 int，默认值为0。

Diagram sources

Section sources

业务场景与排序字段意义​

排序字段 Sort 的主要业务意义在于：

  • 控制前端界面中实体列表的展示顺序
  • 支持用户自定义排序偏好
  • 在导出数据或生成报表时保持一致的顺序逻辑
  • 默认情况下，系统按 Sort 字段升序排列查询结果

此机制确保了用户可以通过简单的API调用实现直观的“上移”、“下移”或“置顶”操作。

Section sources

权限与业务约束​

  • 权限要求: 该接口目前未标注 [Authorize] 属性，表示无需特定权限即可调用（但实际部署中可能受全局过滤器控制）
  • 业务约束:
    • 不允许存在重复的排序值，系统会自动调整其他实体以避免冲突
    • 排序值必须为整数，且建议从1开始
    • 实体必须存在，否则操作无效
    • 操作会触发批量更新，影响性能时需注意调用频率

Section sources

响应示例​

成功响应（204 No Content）​

HTTP/1.1 204 No Content
Content-Length: 0

说明：排序调整成功，无返回内容。

错误码说明​

状态码原因说明
400 Bad Request参数无效id 不是有效的GUID格式，或 sort 不是有效整数
404 Not Found实体不存在提供的 id 在数据库中找不到对应记录
500 Internal Server Error服务器内部错误数据库更新失败或其他未处理异常

Section sources

调用流程图​

Diagram sources