字段选择

数据墙DBW 支持按需选择返回字段，而不是像 SELECT * 那样返回整行。这减少了不必要的网络数据传输，也让客户端可以精确控制 API 响应内容。

REST：$select

$select 参数用逗号分隔指定要返回的字段：

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

{
  "value": [
    { "id": 1, "title": "示例图书" }
  ]
}

与筛选排序组合

# 筛选 + 排序 + 字段选择 + 分页
curl "http://localhost:5000/api/Book?\$select=id,title,year&\$filter=year%20ge%202000&\$orderby=title%20asc&\$first=10"

字段不存在或不可访问

如果 $select 请求了不存在的字段，返回 400：

{
  "error": {
    "code": "Bad Request",
    "message": "Invalid field 'xyz' in $select",
    "status": 400
  }
}

如果字段存在但当前角色无权访问（被 fields.exclude 排除），同样返回 400。

不传 $select

不传 $select 时，返回该角色有权访问的所有字段。被 permissions 中 fields.exclude 排除的字段不会出现在响应中——即使没有显式使用 $select。

GraphQL：原生字段选择

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

{
  books {
    items { id title year }
  }
}

{
  "data": {
    "books": {
      "items": [
        { "id": 1, "title": "示例图书", "year": 2023 }
      ]
    }
  }
}

字段别名

在 GraphQL 中可以为字段指定别名，重命名响应中的字段名：

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

响应：

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

别名对于前端适配命名规范（如 camelCase）、对接不同类型系统非常有用。

嵌套字段选择

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

{
  books {
    items {
      id
      title
      authors {
        items { firstName: first_name lastName: last_name }
      }
    }
  }
}

$select vs GraphQL 字段选择

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

字段别名 + $select 的配合

实体配置中的字段别名（fields[].alias）定义了 API 层字段名。$select 和 GraphQL 查询都使用别名后的名称，而不是数据库原始列名。

{
  "fields": [
    { "name": "sku_product_title", "alias": "title" }
  ]
}

# 使用别名，而不是原始列名
curl "http://localhost:5000/api/Book?\$select=id,title"

如果传了原始列名 sku_product_title，可能不被识别而导致 400 错误。始终使用配置中 alias 定义的 API 字段名。

权限限制的字段

在 permissions 中通过 fields.exclude 排除的字段，无论哪种协议都无法访问：

{
  "role": "anonymous",
  "actions": [
    {
      "action": "read",
      "fields": {
        "include": ["*"],
        "exclude": ["internal_notes", "cost_price"]
      }
    }
  ]
}

• REST $select 请求被排除的字段会返回 400。
• GraphQL 查询请求被排除的字段会返回错误。
• 如果不传 $select，被排除的字段自动不出现在响应中。

这确保了字段级权限在两种协议之间完全一致。

实践建议

• 移动端：始终使用 $select 或 GraphQL 字段选择，只拉需要的字段，减少带宽。
• 列表页：$select=id,title 只取列表需要的字段，详情页再取全部。
• 权限规划：通过 fields.exclude 在配置层统一管理敏感字段，不依赖客户端自觉。
• 命名一致性：在 fields[].alias 中统一 API 字段命名风格，让 REST 和 GraphQL 的字段名保持一致。

下一步

• 分页与游标 — 控制每页返回多少条。
• 查询、筛选与排序 — 筛选出要返回哪些记录。