跳到主要内容
版本：Next

应用服务契约定义

本文档中引用的文件

  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Services/IMyEntityNameAppService.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName/Controller/MyEntityNameController.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application/Implements/MyEntityNameAppService.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNameDto.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/GetMyEntityNamesInput.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNameCreateDto.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNameUpdateDto.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNameCreateOrUpdateDtoBase.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNamesImportModel.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNamesExportModel.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Domain/MyEntityNames/MyEntityName.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Domain/MyEntityNames/IMyEntityNameRepository.cs

目录​

  1. 简介
  2. 接口继承与扩展
  3. 核心操作方法详解
  4. 数据传输对象（DTO）设计
  5. RESTful API 映射
  6. 异常处理机制
  7. 导入导出功能实现
  8. 调用示例
  9. 依赖关系与架构图
  10. 总结

简介​

IMyEntityNameAppService 是 CMS 插件系统中用于管理 MyEntityName 实体的核心应用服务契约接口。该接口基于 ABP 框架的 ICrudAppService 进行扩展，提供了完整的 CRUD（创建、读取、更新、删除）操作，并额外支持批量克隆、排序调整、数据导入导出等业务功能。

通过此接口，前端或其他客户端可以以标准化的方式与后端服务进行交互，所有操作均通过 DTO（数据传输对象）进行封装，确保了类型安全和数据一致性。接口通过控制器暴露为 RESTful API 端点，支持分页、排序、过滤等高级查询功能。

Section sources

  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Services/IMyEntityNameAppService.cs

接口继承与扩展​

IMyEntityNameAppService 接口继承自 ABP 框架提供的 ICrudAppService<TDto, TKey, TGetListInput, TCreateInput, TUpdateInput> 泛型接口，具体实现如下：

public interface IMyEntityNameAppService : ICrudAppService<
    MyEntityNameDto,           // 数据传输对象
    Guid,                      // 实体主键类型
    GetMyEntityNamesInput,     // 查询输入参数
    MyEntityNameCreateDto,     // 创建输入参数
    MyEntityNameUpdateDto      // 更新输入参数
>

这种设计使得该服务天然具备以下标准操作：

  • GetAsync(id)：根据 ID 获取单个实体
  • GetListAsync(input)：分页获取实体列表
  • CreateAsync(input)：创建新实体
  • UpdateAsync(id, input)：更新现有实体
  • DeleteAsync(id)：删除实体

在此基础上，接口进一步扩展了插件特有的业务方法，如批量删除、克隆、排序调整、导入导出等。

Section sources

  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Services/IMyEntityNameAppService.cs

核心操作方法详解​

标准 CRUD 方法​

方法输入参数返回类型说明
GetAsyncGuid idTask<MyEntityNameDto>根据唯一标识获取单个 MyEntityName 实体
GetListAsyncGetMyEntityNamesInput inputTask<PagedResultDto<MyEntityNameDto>>分页查询 MyEntityName 列表，支持过滤和排序
CreateAsyncMyEntityNameCreateDto inputTask<MyEntityNameDto>创建新的 MyEntityName 实体
UpdateAsyncGuid id, MyEntityNameUpdateDto inputTask<MyEntityNameDto>更新指定 ID 的 MyEntityName 实体
DeleteAsyncGuid idTask删除指定 ID 的 MyEntityName 实体

扩展业务方法​

方法输入参数返回类型说明
CloneAsyncIEnumerable<Guid> idsTask<List<MyEntityNameDto>>批量克隆指定 ID 的实体，名称自动追加“副本”标记
DeleteManyAsyncIEnumerable<Guid> idsTask批量删除多个实体
AdjustSortAsyncGuid id, int sortTask调整指定实体的排序值，并自动重排其他实体
ImportAsyncMyEntityNamesImportModel inputTask从 Excel 导入 MyEntityName 数据，支持增量更新
ExportAsyncGetMyEntityNamesInput inputTask<(Dictionary<string, object>, string)>导出数据为 Excel 格式，返回工作表数据和文件名

Section sources

  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Services/IMyEntityNameAppService.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application/Implements/MyEntityNameAppService.cs

数据传输对象（DTO）设计​

MyEntityNameDto​

表示 MyEntityName 实体的数据传输对象，继承自 ExtensibleEntityDto<Guid> 并实现 IHasConcurrencyStamp，用于并发控制。

属性说明：

  • Code：编号（字符串）
  • Name：名称（字符串）
  • Sort：排序（整数）
  • Remark：备注（字符串）
  • IsDisabled：是否禁用（布尔值）
  • ConcurrencyStamp：并发戳（用于乐观锁）

Section sources

  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNameDto.cs

GetMyEntityNamesInput​

查询输入参数，继承自 ExtensiblePagedAndSortedResultRequestDto，支持分页、排序和过滤。

属性说明：

  • Filter：通用过滤条件
  • Name：按名称精确查询

Section sources

  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/GetMyEntityNamesInput.cs

MyEntityNameCreateDto 与 MyEntityNameUpdateDto​

分别用于创建和更新操作，均继承自 MyEntityNameCreateOrUpdateDtoBase。

共同属性：

  • Code：编号
  • Name：名称
  • Remark：备注

特有属性：

  • MyEntityNameCreateDto：Sort（可选排序值），IsDisabled（是否禁用，默认 false）
  • MyEntityNameUpdateDto：ConcurrencyStamp（并发控制戳）

Section sources

  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNameCreateDto.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNameUpdateDto.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNameCreateOrUpdateDtoBase.cs

导入导出模型​

MyEntityNamesImportModel​

用于 Excel 导入，包含一个 MyEntityNameImportModel 列表，每个模型对应一行数据。

MyEntityNamesExportModel​

用于 Excel 导出，定义了导出列的名称和宽度，通过 ExcelColumn 特性标注。

Section sources

  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNamesImportModel.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNamesExportModel.cs

RESTful API 映射​

MyEntityNameController 将 IMyEntityNameAppService 接口映射为标准的 RESTful API 端点：

Diagram sources

  • /lmes-template/src/CMS.Plugin.MyPluginName/Controller/MyEntityNameController.cs

Section sources

  • /lmes-template/src/CMS.Plugin.MyPluginName/Controller/MyEntityNameController.cs

异常处理机制​

服务在执行过程中会抛出以下类型的异常：

  • UserFriendlyException：用户友好型异常，用于提示前端用户具体错误信息，如：

    • 名称已存在
    • 导入数据格式错误
    • 必填字段为空

  • AbpValidationException：参数验证异常，由 ABP 框架自动触发，当输入 DTO 不符合验证规则时抛出。

  • ConcurrencyException：并发冲突异常，当多个用户同时修改同一实体时触发（通过 ConcurrencyStamp 控制）。

所有异常均通过全局异常过滤器（CMSExceptionFilter）统一处理并返回标准化错误响应。

Section sources

  • /lmes-template/src/CMS.Plugin.MyPluginName.Application/Implements/MyEntityNameAppService.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName/Controller/MyEntityNameController.cs

导入导出功能实现​

导入流程​

  1. 前端上传 Excel 文件
  2. 后端读取“配置”工作表数据
  3. 校验数据完整性（名称重复、必填项等）
  4. 区分新增与更新操作
  5. 调用 CreateAsync 或 UpdateAsync 批量处理
  6. 事务性提交，任一失败则整体回滚

导出流程​

  1. 接收查询参数 GetMyEntityNamesInput
  2. 调用 ExportAsync 获取数据
  3. 使用 MiniExcel 库填充模板文件
  4. 返回 FileStreamResult 下载文件

Diagram sources

  • /lmes-template/src/CMS.Plugin.MyPluginName/Controller/MyEntityNameController.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application/Implements/MyEntityNameAppService.cs

调用示例​

获取实体列表（GET）​

GET /api/v1/MyPluginName/MyEntityName?Filter=测试&Sorting=Name&MaxResultCount=10&SkipCount=0
Authorization: Bearer <token>

创建实体（POST）​

POST /api/v1/MyPluginName/MyEntityName
Content-Type: application/json
Authorization: Bearer <token>

{
  "code": "TEST001",
  "name": "测试实体",
  "remark": "这是一个测试",
  "sort": 1
}

批量删除（DELETE）​

DELETE /api/v1/MyPluginName/MyEntityName
Content-Type: application/json
Authorization: Bearer <token>

["a1b2c3d4-e5f6-7890-1234-567890abcdef"]

导入数据（POST）​

POST /api/v1/MyPluginName/MyEntityName/Import
Content-Type: multipart/form-data
Authorization: Bearer <token>

File: data.xlsx

导出数据（GET）​

GET /api/v1/MyPluginName/MyEntityName/Export?Filter=生产环境
Authorization: Bearer <token>

Section sources

  • /lmes-template/src/CMS.Plugin.MyPluginName/Controller/MyEntityNameController.cs

依赖关系与架构图​

Diagram sources

  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Services/IMyEntityNameAppService.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName/Controller/MyEntityNameController.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application/Implements/MyEntityNameAppService.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Domain/MyEntityNames/IMyEntityNameRepository.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Domain/MyEntityNames/MyEntityName.cs

总结​

IMyEntityNameAppService 接口通过继承 ABP 框架的 ICrudAppService，实现了标准化的 CRUD 操作，并在此基础上扩展了克隆、排序、导入导出等实用功能。接口设计遵循 RESTful 原则，通过 DTO 进行数据封装，确保了类型安全和可维护性。

控制器层将接口方法映射为 HTTP 端点，支持 JSON 和文件上传等多种交互方式。整个服务采用依赖注入和仓储模式，实现了业务逻辑与数据访问的解耦，便于测试和扩展。

该接口为前端提供了稳定、可预测的 API 合约，是插件系统中实体管理的核心服务契约。

Section sources

  • /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Services/IMyEntityNameAppService.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName.Application/Implements/MyEntityNameAppService.cs
  • /lmes-template/src/CMS.Plugin.MyPluginName/Controller/MyEntityNameController.cs