跳到主要内容
版本：Next

基础CRUD操作

本文档中引用的文件

目录​

  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）

本节来源

数据传输对象（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 (字符串): 按名称过滤

本节来源

响应格式与示例​

成功响应示例​

创建操作成功响应​

{
  "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": "名称 '示例名称' 已经存在"
  }
}

本节来源

输入验证机制​

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

服务端验证​

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

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

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

业务规则验证​

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

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

并发控制​

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

本节来源

软删除与审计字段​

软删除行为​

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

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

审计字段自动填充​

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

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

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

排序调整​

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

本节来源