资源 CRUD 通用参数

本文整理 collection/resource 风格接口在增删改查时常见的通用参数。接口形态通常是：

/api/{resource}:{action}

例如：

/api/yiask_report:list
/api/yiask_report:get
/api/yiask_report:create
/api/yiask_report:update
/api/yiask_report:destroy

resource 不是普通 query 参数，而是资源名或集合名。:list、:get、:create、:update、:destroy 是动作名。

通用请求头

Header	说明
`Authorization: Bearer <token>`	登录 token 或 API key。
`x-spaces: <space>`	多空间场景下指定空间，例如 `sinopharm`。
`Content-Type: application/json`	`POST` 请求提交 JSON body 时使用。

查询列表：list

GET /api/{resource}:list

用于查询多条记录，返回数组和分页信息。

参数	位置	类型	说明
`page`	query	number	页码。
`pageSize`	query	number	每页条数。
`filter`	query	object	过滤条件。通常是 JSON 对象。
`sort`	query	string/string[]	排序字段。`-createdAt` 表示倒序，`createdAt` 表示正序。
`fields`	query	string/string[]	只返回指定字段。
`appends`	query	string/string[]	追加加载关联字段。
`except`	query	string/string[]	排除指定字段。

示例：

curl -G 'http://localhost:13000/api/yiask_report:list' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-spaces: sinopharm' \
  --data-urlencode 'page=1' \
  --data-urlencode 'pageSize=20' \
  --data-urlencode 'sort[]=-createdAt' \
  --data-urlencode 'appends[]=allowUsers'

也可以用逗号形式：

/api/yiask_report:list?page=1&pageSize=20&sort=-createdAt&fields=id,fileName,createdAt

查询单条：get

GET /api/{resource}:get

用于查询单条记录。通常通过 filterByTk 指定主键或目标键。

参数	位置	类型	说明
`filterByTk`	query	string/number/object	按目标键查询，默认通常是 `id`。
`filter`	query	object	额外过滤条件。
`sort`	query	string/string[]	某些关联场景下可用于排序。
`fields`	query	string/string[]	只返回指定字段。
`appends`	query	string/string[]	追加加载关联字段。
`except`	query	string/string[]	排除指定字段。

示例：

curl 'http://localhost:13000/api/yiask_report:get?filterByTk=123' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-spaces: sinopharm'

带关联：

/api/yiask_report:get?filterByTk=123&appends[]=allowUsers&appends[]=session

新增：create

POST /api/{resource}:create

用于创建记录。字段值放在 JSON body 里。

参数	位置	类型	说明
`whitelist`	query	string/string[]	允许写入的字段白名单。
`blacklist`	query	string/string[]	禁止写入的字段黑名单。
body	body	object	要创建的数据。

示例：

curl 'http://localhost:13000/api/yiask_report:create' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-spaces: sinopharm' \
  -H 'Content-Type: application/json' \
  --data '{
    "fileName": "report.xlsx",
    "mimeType": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
    "fileType": "report",
    "pureMode": false
  }'

只允许写入部分字段：

/api/yiask_report:create?whitelist[]=fileName&whitelist[]=mimeType

更新：update

POST /api/{resource}:update

用于更新记录。目标记录通常由 filterByTk 或 filter 指定，更新值放在 JSON body 里。

参数	位置	类型	说明
`filterByTk`	query	string/number/object	按目标键定位要更新的记录，默认通常是 `id`。
`filter`	query	object	按条件定位要更新的记录。
`whitelist`	query	string/string[]	允许更新的字段白名单。
`blacklist`	query	string/string[]	禁止更新的字段黑名单。
body	body	object	要更新的数据。

注意：更新操作至少应提供 filterByTk 或 filter 之一，否则容易变成无目标更新，通常会被框架拦截。

示例：

curl 'http://localhost:13000/api/yiask_report:update?filterByTk=123' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-spaces: sinopharm' \
  -H 'Content-Type: application/json' \
  --data '{
    "memo": "已确认",
    "pureMode": true
  }'

限制只更新 memo：

/api/yiask_report:update?filterByTk=123&whitelist[]=memo

删除：destroy

POST /api/{resource}:destroy

用于删除记录。目标记录通常由 filterByTk 或 filter 指定。

参数	位置	类型	说明
`filterByTk`	query	string/number/string[]/number[]	按目标键删除。默认通常是 `id`。
`filter`	query	object	按条件删除。

注意：删除操作至少应提供 filterByTk 或 filter 之一。批量删除可以传多个 filterByTk，具体编码方式取决于调用端。

删除单条：

curl -X POST 'http://localhost:13000/api/yiask_report:destroy?filterByTk=123' \
  -H 'Authorization: Bearer <token>' \
  -H 'x-spaces: sinopharm'

删除多条的一种常见写法：

/api/yiask_report:destroy?filterByTk[]=123&filterByTk[]=456

也可能使用逗号形式，是否支持要看当前资源解析逻辑：

/api/yiask_report:destroy?filterByTk=123,456

参数格式说明

sort、fields、appends、except、whitelist、blacklist 通常支持数组或逗号字符串两种形式。

数组形式：

fields[]=id&fields[]=fileName
appends[]=allowUsers
sort[]=-createdAt

逗号形式：

fields=id,fileName
appends=allowUsers
sort=-createdAt

filter 是对象参数，建议用 curl -G --data-urlencode 或客户端 SDK 传递，避免手写 URL 编码出错。

以 yiask_report 为例

yiask_report 的普通字段包括：

id
assistantMessageId
sessionId
createdAt
createdById
spaceName
relativePath
fileName
mimeType
size
memo
fileType
pureMode

可用于 appends 的关联字段包括：

createdBy
space
message
session
allowUsers

例如查询报告列表并带出可访问用户：

/api/yiask_report:list?appends[]=allowUsers&sort[]=-createdAt&page=1&pageSize=20

常见状态码判断

状态	含义
`200`	请求成功。
`401`	token 无效、过期或未登录。
`403`	已登录但无权限。
`404`	资源或 action 不存在，或者对应插件没有启用。
`500`	服务端异常，需要看服务端日志。

#资源 CRUD 通用参数

#通用请求头

#查询列表：list

#查询单条：get

#新增：create

#更新：update

#删除：destroy

#参数格式说明

#以 yiask_report 为例

#常见状态码判断