基础CRUD操作

本文档中引用的文件

• /lmes-template/src/CMS.Plugin.MyPluginName/Controller/MyEntityNameController.cs
• /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.Application.Contracts/Dtos/MyEntityNames/MyEntityNameDto.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/GetMyEntityNamesInput.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.Domain/MyEntityNames/MyEntityName.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.Domain.Shared/MyEntityNames/MyEntityNameConsts.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/Extensions/CMSPluginEfCoreExtensions.MyEntityName.cs

目录

1. API端点说明
2. 数据传输对象（DTO）结构
3. 响应格式与示例
4. 输入验证机制
5. 软删除与审计字段

API端点说明

本节详细描述 MyEntityName 实体的基础CRUD操作API端点，包括HTTP方法、请求路径、参数类型和功能说明。

GET /{id}

• HTTP方法: GET
• 路径: /api/v\{version\}/MyPluginName/MyEntityName/\{id\}
• 功能: 根据唯一标识符获取单个 MyEntityName 实体
• 参数:
  • id (路径参数): Guid 类型，表示实体的唯一标识符
• 返回值: MyEntityNameDto 对象

POST

• HTTP方法: POST
• 路径: /api/v\{version\}/MyPluginName/MyEntityName
• 功能: 创建新的 MyEntityName 实体
• 请求体: MyEntityNameCreateDto 对象
• 返回值: 创建后的 MyEntityNameDto 对象

PUT /{id}

• HTTP方法: PUT
• 路径: /api/v\{version\}/MyPluginName/MyEntityName/\{id\}
• 功能: 更新指定ID的 MyEntityName 实体
• 参数:
  • id (路径参数): Guid 类型，表示要更新的实体标识符
• 请求体: MyEntityNameUpdateDto 对象
• 返回值: 更新后的 MyEntityNameDto 对象

DELETE /{id}

• HTTP方法: DELETE
• 路径: /api/v\{version\}/MyPluginName/MyEntityName/\{id\}
• 功能: 删除指定ID的 MyEntityName 实体（软删除）
• 参数:
  • id (路径参数): Guid 类型，表示要删除的实体标识符
• 返回值: 无内容（204 No Content）

批量删除

• HTTP方法: DELETE
• 路径: /api/v\{version\}/MyPluginName/MyEntityName
• 功能: 批量删除多个 MyEntityName 实体
• 请求体: 包含多个 Guid 的数组
• 返回值: 无内容（204 No Content）

本节来源

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

数据传输对象（DTO）结构

本节描述 MyEntityName 相关DTO类的数据结构及字段约束。

MyEntityNameDto

表示 MyEntityName 实体的数据传输对象，继承自 ExtensibleEntityDto<Guid> 并实现 IHasConcurrencyStamp 接口。

• Code (字符串): 编号，最大长度64
• Name (字符串): 名称，最大长度64
• Sort (整数): 排序值
• Remark (字符串): 备注，最大长度256
• IsDisabled (布尔值): 是否禁用
• ConcurrencyStamp (字符串): 并发戳，用于乐观锁
• GetExportData() 方法: 返回字典格式的导出数据

MyEntityNameCreateDto

用于创建 MyEntityName 实体的DTO，继承自 MyEntityNameCreateOrUpdateDtoBase。

• 继承字段:
  • Code (字符串): 编号
  • Name (字符串): 名称
  • Remark (字符串): 备注
• 特有字段:
  • Sort (可空整数): 排序值
  • IsDisabled (可空布尔值): 是否禁用，默认为 false

MyEntityNameUpdateDto

用于更新 MyEntityName 实体的DTO，继承自 MyEntityNameCreateOrUpdateDtoBase 并实现 IHasConcurrencyStamp 接口。

• 继承字段:
  • Code (字符串): 编号
  • Name (字符串): 名称
  • Remark (字符串): 备注
• 特有字段:
  • ConcurrencyStamp (字符串): 并发戳

MyEntityNameCreateOrUpdateDtoBase

MyEntityNameCreateDto 和 MyEntityNameUpdateDto 的基类，包含共享字段。

• Code (字符串): 编号
• Name (字符串): 名称
• Remark (字符串): 备注

GetMyEntityNamesInput

用于查询 MyEntityName 列表的输入参数，继承自 ExtensiblePagedAndSortedResultRequestDto。

• Filter (字符串): 通用过滤条件
• Name (字符串): 按名称过滤

本节来源

• /lmes-template/src/CMS.Plugin.MyPluginName.Application.Contracts/Dtos/MyEntityNames/MyEntityNameDto.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/GetMyEntityNamesInput.cs

响应格式与示例

成功响应示例

创建操作成功响应

{
  "id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "code": "MYCODE001",
  "name": "示例名称",
  "sort": 1,
  "remark": "这是一个示例",
  "isDisabled": false,
  "concurrencyStamp": "8d7e6f5a-4b3c-2a1f-0e9d-8c7b6a5f4e3d"
}

404 未找到错误

当请求的资源不存在时返回：

{
  "error": {
    "code": "EntityNotFound",
    "message": "未找到指定ID的MyEntityName实体"
  }
}

400 验证错误

当输入数据验证失败时返回：

{
  "error": {
    "code": "ValidationError",
    "message": "输入验证失败",
    "details": "名称字段不能为空，最大长度为64个字符"
  }
}

名称已存在错误

当创建或更新时名称已存在时返回：

{
  "error": {
    "code": "NameAlreadyExists",
    "message": "名称 '示例名称' 已经存在"
  }
}

本节来源

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

输入验证机制

ABP框架在 MyEntityNameAppService 中实现了全面的输入验证机制，确保数据的完整性和一致性。

服务端验证

在 MyEntityNameAppService 的 CheckCreateOrUpdateDtoAsync 方法中执行以下验证：

• 编号验证: 非空且最大长度为64字符
• 名称验证: 非空且最大长度为64字符
• 备注验证: 最大长度为256字符

这些验证通过ABP框架的 Check 工具类实现，当验证失败时会抛出带有本地化消息的 UserFriendlyException。

业务规则验证

除了基本字段验证外，还实现了以下业务规则验证：

• 名称唯一性: 在创建时检查名称是否已存在，防止重复
• 更新时的名称唯一性: 在更新时检查新名称是否与其他实体冲突（排除自身）
• 导入时的重复检查: 在批量导入时检查Excel表格中是否存在重复名称

并发控制

使用 ConcurrencyStamp 字段实现乐观锁机制，防止并发更新冲突。在更新操作中，如果并发戳不匹配，将导致更新失败。

本节来源

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

软删除与审计字段

软删除行为

MyEntityName 实体实现了软删除机制，删除操作不会从数据库中物理移除记录，而是通过设置 IsDeleted 标志来标记删除状态。

• 删除操作调用 DeleteAsync 方法
• 实体的 IsDeleted 字段被设置为 true
• DeletionTime 字段记录删除时间
• DeleterId 字段记录执行删除操作的用户ID
• 被删除的实体在常规查询中不可见，但可以通过特定查询获取

审计字段自动填充

MyEntityName 实体继承自 FullAuditedAggregateRoot<Guid>，自动管理以下审计字段：

• CreationTime: 创建时间，由框架在实体创建时自动设置
• CreatorId: 创建者ID，记录创建实体的用户
• LastModificationTime: 最后修改时间，每次更新时自动更新
• LastModifierId: 最后修改者ID，记录最后修改实体的用户
• IsDeleted: 删除标志，用于软删除
• DeletionTime: 删除时间，软删除时设置
• DeleterId: 删除者ID，记录执行删除操作的用户

这些审计字段由ABP框架自动管理，无需在应用服务中手动设置。

排序调整

系统提供了专门的 AdjustSortAsync 方法来处理实体的排序调整，确保在重新排序时维护正确的顺序逻辑。

本节来源

• /lmes-template/src/CMS.Plugin.MyPluginName.Domain/MyEntityNames/MyEntityName.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.Application/Implements/MyEntityNameAppService.cs
• /lmes-template/src/CMS.Plugin.MyPluginName.EntityFrameworkCore/Extensions/CMSPluginEfCoreExtensions.MyEntityName.cs