跳到主要内容
版本：Next

API参考

简介​

本API文档详细描述了MyEntityNameController暴露的RESTful接口，用于管理MyEntityName实体的创建、查询、更新和删除操作。该控制器遵循ABP框架的CRUD模式，并提供了扩展功能如克隆、批量删除、排序调整以及导入导出功能。

API基础路径为：/api/v{version}/MyPluginName/MyEntityName，其中{version}表示API版本号。

本控制器实现了以下核心功能：

  • 单个实体的增删改查
  • 分页查询支持
  • 批量操作（删除、克隆）
  • 排序管理
  • Excel文件导入导出
  • 并发控制（通过ConcurrencyStamp）

认证与安全​

该API的某些端点需要身份验证，具体如下：

  • 需要认证的端点：

    • POST /api/v{version}/MyPluginName/MyEntityName/Import - 导入操作需要授权

  • 无需认证的端点：

    • 所有GET请求（获取单个实体、列表、导出）
    • 创建、更新、删除、克隆等操作在当前实现中未启用认证（注释掉了[Authorize]）

安全过滤器： 控制器应用了多个ABP框架提供的过滤器：

  • CMSLanguageFilter：语言过滤
  • CMSUowActionFilter：工作单元管理
  • CMSAuditActionFilter：审计日志
  • CMSExceptionFilter：异常处理

版本控制​

API采用基于URL的版本控制机制，通过apiVersion路由约束实现。

版本格式：

/api/v{version}/MyPluginName/MyEntityName

其中{version}为版本号，例如v1、v2等。

这种设计允许在不破坏现有客户端的情况下进行API演进和升级。

数据模型​

MyEntityNameDto（响应模型）​

表示MyEntityName实体的数据传输对象，用于API响应。

字段类型说明约束
IdGuid唯一标识符由系统生成
Codestring编号最大长度64字符
Namestring名称必填，最大长度64字符，唯一
Sortint排序值用于界面排序
Remarkstring备注最大长度256字符
IsDisabledbool?是否禁用可为空
ConcurrencyStampstring并发戳用于乐观并发控制

MyEntityNameCreateDto（创建请求模型）​

用于创建新MyEntityName实体的请求数据模型。

字段类型说明约束默认值
Codestring编号必填，最大长度64字符-
Namestring名称必填，最大长度64字符，唯一-
Remarkstring备注最大长度256字符-
Sortint?排序值可为空系统自动分配
IsDisabledbool?是否禁用可为空false

继承自MyEntityNameCreateOrUpdateDtoBase。

MyEntityNameUpdateDto（更新请求模型）​

用于更新现有MyEntityName实体的请求数据模型。

字段类型说明约束
Codestring编号必填，最大长度64字符
Namestring名称必填，最大长度64字符，唯一
Remarkstring备注最大长度256字符
ConcurrencyStampstring并发戳必填，用于防止并发修改

继承自MyEntityNameCreateOrUpdateDtoBase并实现IHasConcurrencyStamp接口。

GetMyEntityNamesInput（查询参数模型）​

用于分页查询MyEntityName实体的输入参数。

字段类型说明约束
Filterstring通用过滤条件可为空
Namestring按名称过滤可为空
Sortingstring排序字段默认按Sort排序
MaxResultCountint每页最大结果数默认值由系统配置
SkipCountint跳过记录数用于分页

继承自ABP框架的ExtensiblePagedAndSortedResultRequestDto。

API端点​

获取单个MyEntityName​

GET /api/v\{version\}/MyPluginName/MyEntityName/\{id\}

参数：

  • id (path): 实体唯一标识符 (Guid)

响应：

  • 200 OK: 返回MyEntityNameDto对象
  • 404 Not Found: 实体不存在

查询MyEntityName列表​

GET /api/v\{version\}/MyPluginName/MyEntityName

查询参数：

  • Filter (query): 通用过滤
  • Name (query): 名称过滤
  • Sorting (query): 排序字段
  • MaxResultCount (query): 每页大小
  • SkipCount (query): 分页偏移

响应：

  • 200 OK: 返回PagedResultDto<MyEntityNameDto>对象

创建MyEntityName​

POST /api/v\{version\}/MyPluginName/MyEntityName

请求体： MyEntityNameCreateDto JSON对象

响应：

  • 200 OK: 返回创建的MyEntityNameDto对象
  • 400 Bad Request: 验证失败

更新MyEntityName​

PUT /api/v\{version\}/MyPluginName/MyEntityName/\{id\}

参数：

  • id (path): 实体唯一标识符 (Guid)

请求体： MyEntityNameUpdateDto JSON对象

响应：

  • 200 OK: 返回更新后的MyEntityNameDto对象
  • 400 Bad Request: 验证失败
  • 404 Not Found: 实体不存在

克隆MyEntityName​

POST /api/v\{version\}/MyPluginName/MyEntityName/Clone

请求体：

[ "guid1", "guid2", ... ]

响应：

  • 200 OK: 返回克隆的MyEntityNameDto对象列表

克隆时名称会自动添加"_副本"后缀，如果名称已存在则继续添加后缀直到唯一。

删除MyEntityName（单个）​

DELETE /api/v\{version\}/MyPluginName/MyEntityName/\{id\}

参数：

  • id (path): 实体唯一标识符 (Guid)

响应：

  • 200 OK: 删除成功
  • 404 Not Found: 实体不存在

批量删除MyEntityName​

DELETE /api/v\{version\}/MyPluginName/MyEntityName

请求体：

[ "guid1", "guid2", ... ]

响应：

  • 200 OK: 批量删除成功

调整排序​

PUT /api/v\{version\}/MyPluginName/MyEntityName/\{id\}/AdjustSort/\{sort\}

参数：

  • id (path): 实体唯一标识符 (Guid)
  • sort (path): 新的排序值 (int)

响应：

  • 200 OK: 排序调整成功

此操作会自动调整其他实体的排序值以保持连续性。

错误处理​

系统采用统一的错误处理机制，主要通过CMSExceptionFilter和UserFriendlyException实现。

常见错误代码​

错误代码说明触发条件
CMS.Plugin.MyPluginName:NameAlreadyExists名称已存在创建或更新时名称重复
UserFriendlyException用户友好异常输入验证失败或业务规则违反

错误响应格式​

{
  "error": {
    "code": "错误代码",
    "message": "错误消息",
    "details": "详细信息",
    "data": {}
  }
}

导入导出功能​

导出MyEntityName​

GET /api/v{version}/MyPluginName/MyEntityName/Export

参数： 与查询列表相同的查询参数

响应：

  • 200 OK: 返回Excel文件流
  • 文件名格式：{导出名称}_{时间戳}.xlsx

使用预定义模板MyEntityName导出模板.xlsx进行导出。

导入MyEntityName​

POST /api/v{version}/MyPluginName/MyEntityName/Import

认证： 需要授权

请求：

  • Content-Type: multipart/form-data
  • 表单字段：file (Excel文件)

处理逻辑：

  1. 检查文件是否包含"配置"工作表
  2. 验证数据完整性（名称不能为空）
  3. 检查名称重复
  4. 区分新增和更新操作
  5. 逐行处理，遇到错误立即终止

校验规则：

  • 名称不能为空
  • 同一导入文件中名称不能重复
  • 系统中已存在的名称不能重复（更新操作除外）

性能优化建议​

查询优化​

  1. 合理使用分页参数：避免获取过多数据，设置合理的MaxResultCount
  2. 精确过滤：使用Name和Filter参数缩小查询范围
  3. 避免频繁全表扫描：确保数据库在常用查询字段上建立索引

批量操作​

  1. 批量删除：优先使用批量删除接口而非多次单个删除
  2. 批量克隆：支持一次克隆多个实体，减少网络往返

导入导出​

  1. 模板预加载：导出模板应缓存以提高性能
  2. 大数据量分批处理：对于大量数据的导入，建议分批进行
  3. 异步处理：考虑将大规模导入导出操作改为异步任务

缓存策略​

  1. 读取缓存：对频繁读取但不常变更的数据实施缓存
  2. 缓存失效：在创建、更新、删除操作后及时清除相关缓存

常见错误排查​

400 Bad Request​

可能原因：

  • 请求体JSON格式错误
  • 必填字段缺失（Code、Name）
  • 字段长度超限
  • 并发戳不匹配

解决方案：

  • 验证请求JSON格式
  • 检查所有必填字段
  • 确保字段长度符合约束
  • 获取最新实体并使用正确的ConcurrencyStamp

名称已存在错误​

错误代码： CMS.Plugin.MyPluginName:NameAlreadyExists

原因：

  • 创建时指定了已存在的名称
  • 更新时修改名称为已存在的名称

解决方案：

  • 检查系统中是否已存在相同名称
  • 使用唯一名称

导入失败​

常见原因：

  1. Excel文件缺少"配置"工作表
  2. 名称列为空
  3. 文件中名称重复
  4. 上传的不是有效的Excel文件

排查步骤：

  1. 确认文件包含"配置"工作表
  2. 检查每行的名称是否填写
  3. 确保文件中没有重复名称
  4. 使用正确的Excel格式

排序异常​

现象： 排序值不连续或重复

原因： 并发修改导致

解决方案：

  • 使用AdjustSort接口统一调整排序
  • 避免直接修改Sort字段

客户端调用示例​

创建操作​

POST /api/v1/MyPluginName/MyEntityName
Content-Type: application/json

{
  "code": "MYCODE001",
  "name": "示例名称",
  "remark": "这是一个示例",
  "sort": 1,
  "isDisabled": false
}

查询列表​

GET /api/v1/MyPluginName/MyEntityName?Name=示例&Sorting=Sort&MaxResultCount=10&SkipCount=0

更新操作​

PUT /api/v1/MyPluginName/MyEntityName/123e4567-e89b-12d3-a456-426614174000
Content-Type: application/json

{
  "code": "MYCODE001",
  "name": "更新后的名称",
  "remark": "已更新",
  "concurrencyStamp": "原始并发戳"
}

批量删除​

DELETE /api/v1/MyPluginName/MyEntityName
Content-Type: application/json

[
  "123e4567-e89b-12d3-a456-426614174000",
  "223e4567-e89b-12d3-a456-426614174000"
]

调整排序​

PUT /api/v1/MyPluginName/MyEntityName/123e4567-e89b-12d3-a456-426614174000/AdjustSort/2