跳到主要内容

变更（Mutation）

网关前缀：${API_BASE}/data/mutation...

后端控制器：MutationController（/api/v1/mutation）。

请求体字段说明（MutationRequest）​

核心字段：

  • version：字符串，必填，版本号（当前使用 "1.0"）
  • transaction：布尔，可选，是否启用事务（建议批量操作时开启）
  • audit：对象，可选
    • actor：字符串，可选
    • reason：字符串，可选
  • operations：数组，必填，变更操作列表（MutationItem）

MutationItem​

  • op：insert | update | upsert | delete，必填
  • entity：字符串，必填，实体名
  • values：Array<Record<string, any>>，可选（insert/upsert 常用）
  • match_on：string[]，可选（upsert 常用，指定匹配字段）
  • set：Record<string, any>，可选（update 常用）
  • where：Predicate，可选（update/delete 常用）
  • optimistic_lock：对象，可选
    • field：字符串，必填
    • expected：任意类型，可选
  • returning：string[]，可选（返回字段）
  • cascade：布尔，可选
  • validate：数组，可选（服务端表达式校验）
    • expr：字符串，必填
    • message：字符串，可选

Predicate 结构同查询接口（comparison/logical/not）。

执行变更（推荐入口）​

  • POST /mutation/execute
  • 权限：isAuthenticated()
  • 请求头：
    • Authorization: Bearer <token>
    • X-Tenant-Id: <tenantId>
    • Content-Type: application/json

示例：插入​

curl -X POST \
  "${API_BASE}/data/mutation/execute" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: tenant-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0",
    "transaction": true,
    "operations": [
      {
        "op": "insert",
        "entity": "customers",
        "values": [
          { "name": "Alice", "email": "alice@example.com", "age": 18 }
        ],
        "returning": ["id"]
      }
    ]
  }'

示例：更新（where + set）​

curl -X POST \
  "${API_BASE}/data/mutation/execute" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: tenant-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0",
    "transaction": true,
    "operations": [
      {
        "op": "update",
        "entity": "orders",
        "where": { "type": "comparison", "field": "id", "op": "eq", "value": 10001 },
        "set": { "status": "PAID" }
      }
    ]
  }'

示例：Upsert（match_on）​

curl -X POST \
  "${API_BASE}/data/mutation/execute" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: tenant-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0",
    "transaction": true,
    "operations": [
      {
        "op": "upsert",
        "entity": "customers",
        "match_on": ["email"],
        "values": [
          { "name": "Alice", "email": "alice@example.com" }
        ]
      }
    ]
  }'

示例：删除​

curl -X POST \
  "${API_BASE}/data/mutation/execute" \
  -H "Authorization: Bearer <token>" \
  -H "X-Tenant-Id: tenant-abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "version": "1.0",
    "transaction": true,
    "operations": [
      {
        "op": "delete",
        "entity": "orders",
        "where": { "type": "comparison", "field": "id", "op": "eq", "value": 10001 }
      }
    ]
  }'

批量执行变更​

  • POST /mutation/batch
  • 权限：isAuthenticated()
  • 请求体：MutationRequest[]

验证变更 DSL​

  • POST /mutation/validate
  • 权限：permitAll
  • 请求体：MutationRequest

便捷接口（等价于 execute）​

  • POST /mutation/insert
  • PUT /mutation/update
  • DELETE /mutation/delete