应用服务契约定义

本文档中引用的文件

• IMyEntityNameAppService.cs
• MyEntityNameController.cs
• MyEntityNameAppService.cs
• MyEntityNameDto.cs
• GetMyEntityNamesInput.cs
• MyEntityNameCreateDto.cs
• MyEntityNameUpdateDto.cs
• MyEntityNameCreateOrUpdateDtoBase.cs
• MyEntityNamesImportModel.cs
• MyEntityNamesExportModel.cs
• MyEntityName.cs
• 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

• 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

• IMyEntityNameAppService.cs

核心操作方法详解

标准 CRUD 方法

方法	输入参数	返回类型	说明
GetAsync	Guid id	Task<MyEntityNameDto>	根据唯一标识获取单个 MyEntityName 实体
GetListAsync	GetMyEntityNamesInput input	Task<PagedResultDto<MyEntityNameDto>>	分页查询 MyEntityName 列表，支持过滤和排序
CreateAsync	MyEntityNameCreateDto input	Task<MyEntityNameDto>	创建新的 MyEntityName 实体
UpdateAsync	Guid id, MyEntityNameUpdateDto input	Task<MyEntityNameDto>	更新指定 ID 的 MyEntityName 实体
DeleteAsync	Guid id	Task	删除指定 ID 的 MyEntityName 实体

扩展业务方法

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

Section sources

• IMyEntityNameAppService.cs
• MyEntityNameAppService.cs

数据传输对象（DTO）设计

MyEntityNameDto

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

属性说明：

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

Section sources

• MyEntityNameDto.cs

GetMyEntityNamesInput

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

属性说明：

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

Section sources

• GetMyEntityNamesInput.cs

MyEntityNameCreateDto 与 MyEntityNameUpdateDto

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

共同属性：

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

特有属性：

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

Section sources

• MyEntityNameCreateDto.cs
• MyEntityNameUpdateDto.cs
• MyEntityNameCreateOrUpdateDtoBase.cs

导入导出模型

MyEntityNamesImportModel

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

MyEntityNamesExportModel

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

Section sources

• MyEntityNamesImportModel.cs
• MyEntityNamesExportModel.cs

RESTful API 映射

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

Diagram sources

• MyEntityNameController.cs

Section sources

• MyEntityNameController.cs

异常处理机制

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

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

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

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

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

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

Section sources

• MyEntityNameAppService.cs
• MyEntityNameController.cs

导入导出功能实现

导入流程

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

导出流程

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

Diagram sources

• MyEntityNameController.cs
• 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

• MyEntityNameController.cs

依赖关系与架构图

Diagram sources

• IMyEntityNameAppService.cs
• MyEntityNameController.cs
• MyEntityNameAppService.cs
• IMyEntityNameRepository.cs
• MyEntityName.cs

总结

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

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

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

Section sources

• IMyEntityNameAppService.cs
• MyEntityNameAppService.cs
• MyEntityNameController.cs