实体 API

动态实体数据的 CRUD 操作。

🎯 概述

实体 API 提供对项目动态实体数据的完整操作能力。所有请求需要 JWT Token 或 API Key 认证。

基础路径： /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}

📝 CRUD 操作

GET - 查询实体列表

路径： /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}

查询参数：

page: 页码（默认 1）
limit: 每页数量（默认 20）
sort: 排序字段
order: 排序方向（asc/desc）
filter[field]: 字段过滤

示例：


GET /api/v1/tenant_7375b0cd/projects/tenant_7375b0cd_project_6888d012be80c/entities/users?page=1&limit=20&sort=created&order=desc

响应：


{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "张三",
      "email": "zhangsan@example.com",
      "avatar": 123,
      "created": 1704067200
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 50,
    "pages": 3
  }
}

GET - 获取单个实体

路径： /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}/{id}

示例：


GET /api/v1/tenant_7375b0cd/projects/tenant_7375b0cd_project_6888d012be80c/entities/users/1

响应：


{
  "success": true,
  "data": {
    "id": 1,
    "name": "张三",
    "email": "zhangsan@example.com",
    "avatar": 123,
    "created": 1704067200,
    "updated": 1704153600
  }
}

POST - 创建实体

路径： /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}

请求：


{
  "name": "李四",
  "email": "lisi@example.com",
  "avatar": 124
}

响应：


{
  "success": true,
  "data": {
    "id": 2,
    "name": "李四",
    "email": "lisi@example.com",
    "avatar": 124,
    "created": 1704240000
  },
  "message": "Entity created successfully"
}

PUT - 更新实体

路径： /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}/{id}

请求：


{
  "name": "李四（已更新）",
  "email": "lisi_new@example.com"
}

响应：


{
  "success": true,
  "data": {
    "id": 2,
    "name": "李四（已更新）",
    "email": "lisi_new@example.com",
    "updated": 1704326400
  },
  "message": "Entity updated successfully"
}

DELETE - 删除实体

路径： /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}/{id}

响应：


{
  "success": true,
  "message": "Entity deleted successfully"
}

🔍 高级查询

字段过滤

使用 filter[field] 参数进行精确匹配：


GET /api/v1/{tenant_id}/projects/{project_id}/entities/users?filter[status]=active

排序

使用 sort 和 order 参数：


GET /api/v1/{tenant_id}/projects/{project_id}/entities/users?sort=created&order=desc

分页

使用 page 和 limit 参数：


GET /api/v1/{tenant_id}/projects/{project_id}/entities/users?page=2&limit=50

🔗 关联字段搜索

GET - 搜索可引用实体

路径： /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}/fields/{field_name}/search

查询参数：

q: 搜索关键词

示例：


GET /api/v1/tenant_7375b0cd/projects/tenant_7375b0cd_project_6888d012be80c/entities/user_activities/fields/user_id/search?q=张

响应：


{
  "success": true,
  "data": [
    {
      "id": 1,
      "label": "张三",
      "value": 1
    }
  ]
}

📁 带文件上传的创建/更新

⚠️ 重要区别：文件上传 API 与默认数据 API 的区别

特性	默认数据 API	文件上传 API
Content-Type	`application/json`	`multipart/form-data`
文件字段处理	只接受文件 ID (FID)	自动上传文件并获取 FID
路径	`/entities/{entity_name}`	`/entities/{entity_name}` (POST) 或 `/entities/{entity_name}/{id}/upload` (更新)
使用场景	已有文件 ID，直接关联	同时上传文件和创建/更新实体

POST - 创建实体（带文件）

路径： /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}

Content-Type: multipart/form-data

表单字段：

name: 用户名
email: 邮箱
avatar: 文件数据（图片二进制）

示例：


curl -X POST \
  "http://YOUR_HOST/api/v1/tenant_7375b0cd/projects/tenant_7375b0cd_project_6888d012be80c/entities/users" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "name=王五" \
  -F "email=wangwu@example.com" \
  -F "avatar=@/path/to/avatar.jpg"

响应：


{
  "success": true,
  "data": {
    "id": 3,
    "name": "王五",
    "email": "wangwu@example.com",
    "avatar": 125,
    "created": 1704412800
  }
}

说明：

自动上传 avatar 文件到文件系统
自动创建文件记录（fid: 125）
自动关联文件 ID 到 avatar 字段

POST - 更新实体（带文件）

路径： /api/v1/{tenant_id}/projects/{project_id}/entities/{entity_name}/{id}/upload

Content-Type: multipart/form-data

⚠️ 注意： 更新操作使用 特殊路径 /upload 后缀

示例：


curl -X POST \
  "http://YOUR_HOST/api/v1/tenant_7375b0cd/projects/tenant_7375b0cd_project_6888d012be80c/entities/users/3/upload" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "name=王五（更新）" \
  -F "avatar=@/path/to/new_avatar.jpg"

🔄 两种 API 的使用对比

方式 1: 默认数据 API（先上传文件，再关联）


# 步骤 1: 上传文件
curl -X POST \
  "http://YOUR_HOST/api/v1/tenant_7375b0cd/project/tenant_7375b0cd_project_6888d012be80c/media/upload" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "file=@avatar.jpg"
 
# 响应: {"fid": 125}
 
# 步骤 2: 创建实体，填入文件 ID
curl -X POST \
  "http://YOUR_HOST/api/v1/tenant_7375b0cd/projects/tenant_7375b0cd_project_6888d012be80c/entities/users" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "王五",
    "email": "wangwu@example.com",
    "avatar": 125
  }'

方式 2: 文件上传 API（一步完成）


# 一次请求同时上传文件和创建实体
curl -X POST \
  "http://YOUR_HOST/api/v1/tenant_7375b0cd/projects/tenant_7375b0cd_project_6888d012be80c/entities/users" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "name=王五" \
  -F "email=wangwu@example.com" \
  -F "avatar=@avatar.jpg"

推荐使用场景：

✅ 文件上传 API：用户注册、个人资料编辑等需要同时上传文件的场景
✅ 默认数据 API：已有文件 ID，只需关联引用的场景

📁 文件和媒体管理

💡 提示：文件和媒体资源的操作应通过实体 API 完成，无需单独的文件 API。

文件在实体中的操作方式

创建/更新实体时上传文件：

使用 multipart/form-data Content-Type
文件字段直接传文件数据
系统自动上传文件并关联 FID

查询实体时获取文件信息：

文件字段返回 FID
通过 FID 构建文件 URL：/files/{tenant_id}/{project_id}/{filename}

示例：


{
  "id": 1,
  "name": "张三",
  "avatar": 123,
  "avatar_url": "/files/tenant_7375b0cd/project_6888d012be80c/avatar_123.jpg"
}

📖 相关资源

认证 API - 用户认证
定义实体 - 创建实体模板
文件上传指南 - 文件配置