---
name: crud-operation
when: 'CRUD, 增删改查, 新建接口, 修改数据, 删除数据, 查询详情, 编辑, 保存, 入库, 新增功能'
scope:
  - backend
products:
  - '*'
id: ka-pattern-crud-operation
asset_kind: pattern
lifecycle_status: active
authority: supporting
routes:
  - '*'
primary_triggers:
  - CRUD
  - 增删改查
  - 新建接口
  - 修改数据
  - 删除数据
  - 查询详情
  - 编辑
  - 保存
  - 入库
  - 新增功能
priority: P2
specificity: 3
version: 1.0.0
last_reviewed: '2026-05-22'
consumes: []
emits: []
secondary_triggers: []
negative_triggers: []
type: pattern
status: active
---

## 决策规则
- 必须遵循 Controller → Service → Mapper/Repository 三层分离
- 禁止 Controller 包含业务逻辑（if/else 分支、计算、状态机）
- 禁止 DTO 和 Entity 混用，外部请求不可直接操作数据库字段
- 批量操作禁止在循环中逐条调用数据库
- 写操作 Service 方法必须有 @Transactional 注解
- 删除操作必须记录操作人和原因
- 列表查询接口必须返回分页结构（total、list、pageNum、pageSize），禁止返回全量数据
- 创建/更新接口必须返回完整实体或 ID，禁止返回 void
- 逻辑删除必须使用统一字段（如 is_deleted），禁止物理删除业务数据
- 并发更新场景必须使用乐观锁（version 字段或更新时间条件），防止数据覆盖
- 批量更新/删除操作必须有数量上限（如 ≤ 500 条），防止大批量锁表

## 验收项
- [AC-01] Controller 无业务逻辑
- [AC-02] DTO/Entity 分离
- [AC-03] 写操作有事务注解
- [AC-04] 批量操作使用 batch SQL
- [AC-05] 删除有审计记录
- [AC-06] 列表查询返回分页结构
- [AC-07] 创建/更新返回完整数据
- [AC-08] 逻辑删除而非物理删除
- [AC-09] 并发更新有乐观锁保护
