select 参数参考

select (GraphQL) / $select (REST) 参数用于指定 API 响应中返回哪些字段，避免传输不需要的数据。REST 通过 URL 查询参数实现，GraphQL 通过声明式查询语法原生支持。

REST：$select

语法

?$select={field1},{field2},{field3}

多个字段以逗号分隔。字段名使用 API 层名称（有 alias 配置则使用别名）。

示例

# 只返回 id、title 和 year
curl "http://localhost:5000/api/Book?\$select=id,title,year"

响应：

{
  "value": [
    { "id": 1, "title": "示例书名", "year": 2024 }
  ]
}

行为规则

场景	行为
不传 $select	返回当前角色有权限访问的全部字段
请求的字段不存在于实体	400 Bad Request
请求的字段被 fields.exclude 排除	400 Bad Request
请求的字段当前角色无访问权	400 Bad Request
字段存在且可访问	正常返回

被权限排除的字段

如果配置了 fields.exclude，不传 $select 时被排除的字段自动不出现在响应中。如果显式通过 $select 请求被排除的字段，返回 400。

$select 不改变其他参数的行为

$select 只影响返回的字段集合。$filter、$orderby、$first、$after 的行为不受 $select 影响——即使筛选条件中引用了未被选中的字段。

与 $filter 等参数组合

curl "http://localhost:5000/api/Book?\$select=id,title,year&\$filter=year%20ge%202000&\$orderby=year%20desc&\$first=10"

参数顺序不影响结果，建议按 $filter → $orderby → $select → $first → $after 书写以提高可读性。

GraphQL：字段选择

GraphQL 的字段选择是协议原生能力——查询中声明哪些字段，响应就只包含哪些字段。不存在 SELECT * 通配符。

基本用法

{
  books {
    items {
      id
      title
      year
    }
  }
}

只返回 id、title、year 字段。

字段别名

在查询中为字段指定别名，重命名响应中的字段名：

{
  books {
    items {
      bookId: id
      bookTitle: title
      publishYear: year
    }
  }
}

响应：

{
  "data": {
    "books": {
      "items": [
        { "bookId": 1, "bookTitle": "示例", "publishYear": 2024 }
      ]
    }
  }
}

嵌套字段选择

在关系查询中可以分别选择当前实体和嵌套实体的字段：

{
  books {
    items {
      id
      title
      category {
        name
      }
    }
  }
}

被权限排除的字段

GraphQL 请求中被 fields.exclude 排除的字段会导致查询错误，errors 数组包含对应错误信息。

REST vs GraphQL

特性	REST $select	GraphQL 字段选择
字段选择	逗号分隔字段名	查询声明中列出字段
字段别名	不支持	支持（alias: field）
嵌套选择	不支持	支持
权限过滤	被禁字段返回 400	被禁字段返回错误
默认行为	不传则返回全部允许字段	必须显式声明

下一步

• filter — 条件筛选参数参考。
• orderby — 排序参数参考。