PHP侧如何设计接口让前端拿到默认选中状态

在前后端分离的开发模式下，前端经常需要渲染一个选项列表并让部分选项“默认选中”。这个选中状态可能来自用户历史设置、会员等级权益或者运营活动规则，一旦放到前端去计算，很容易出现“默认值对不上”的口水战。最稳妥的做法是：默认选中状态由后端接口直接给，前端只负责消费。那PHP侧具体该怎么设计这个接口？很多新同学会直接把 `checked = 1` 塞进列表数据里，但这并不总是最优解。今天聊聊我的一些实践经验。

先想清楚：默认选中状态是谁的“默认”？

设计接口前，先要明确这个默认值是全局统一默认，还是用户自定义默认。举例：国家列表默认选中中国，这是全局默认；而用户收到通知的渠道偏好（邮件/短信/站内信），则是用户个性化默认。

如果是全局默认，可以在PHP代码里定义一个常量或配置文件，然后封装成一个统一查询方法。如果是用户个性化默认，则需要从用户表、用户偏好表或第三方服务读取。接口返回的数据结构应该保持一致，避免前端为两种场景写两套逻辑。

关键设计：选项与选中状态分开展示

很多接口会这样写：

{
  "id": 1,
  "name": "邮箱通知",
  "is_selected": true
}

这种方案简单直观，每个选项自带一个 `is_selected` 字段，前端拿到后直接赋值给 checkbox 或 radio 即可。PHP侧实现也很简单：

$options = [
    ['id' => 1, 'name' => '邮箱通知', 'is_selected' => false],
    ['id' => 2, 'name' => '短信通知', 'is_selected' => true],
];

但问题在于：如果某个选项完全没有资格被选中（比如用户未实名导致不能选“线下支付”），那这个字段就会产生歧义。是“可选但未选中”还是“不可选”？所以建议把“是否可选”和“是否选中”分开：

- `selected`：表示当前是否被选中
- `disabled`：表示用户是否有权操作该选项

这样更符合前端真实使用场景，也方便后端统一控制权限。

更推荐的方式：返回选中的 ID 数组

当选项数量较多，或者选项数据是动态来自数据库时，我倾向于把“选项列表”和“默认选中的ID列表”分开返回。比如一个用户的角色权限树：

{
  "code": 0,
  "message": "ok",
  "data": {
    "all_roles": [
      { "id": 1, "name": "管理员" },
      { "id": 2, "name": "编辑" },
      { "id": 3, "name": "访客" }
    ],
    "default_selected_ids": [1, 3]
  }
}

前端只需要判断 `default_selected_ids` 里是否包含某个选项的 id，就能决定是否显示选中。这样做的好处是：默认状态与选项数据解耦，以后默认值逻辑变化时不需要重发一遍全量选项数据。PHP侧可以用 `in_array()` 很容易地组装响应：

$allRoles = Role::all();
$defaultIds = [1, 3]; // 实际业务逻辑中取出

$data = [
    'all_roles' => $allRoles,
    'default_selected_ids' => $defaultIds,
];

如果前端需要对每个选项做标记，可以让他们自己在前端组合。大部分现代前端框架（Vue、React）都擅长处理这种结构。

PHP侧的具体实现与一些坑

我的习惯是在 Service 层写一个方法，专门负责计算默认选中状态。比如有个 `PermissionService::getDefaultCheckedIds($userId, $scope)`，内部读取配置、用户设置、业务规则，最后返回一个数组。

这里有几个比较容易踩的坑：

1. 不要把 PHP 的 0/1 直接当布尔值输出。如果数据库字段是 `tinyint`，PDO 取出来是字符串 `"0"` 或 `"1"`，如果直接塞进 JSON，前端可能会把它们当字符串。PHP7+ 更好用严格比较，但输出时最好手动转换成布尔值：`(bool)$value`。如果你用 Laravel，可以在模型里使用 `casts` 属性或者 API Resource 中转换。

2. 空数组和 `null` 要区分。假如用户没有任何默认选中项，接口应返回 `"default_selected_ids": []`，而不是缺省字段或 `null`。`null` 会让前端还要做一层兼容处理，实在没必要。

3. 不要默认选中全部。有些后台需求是“默认全选”，但用户其实只勾选了一部分。如果后端每次没有提交记录就强制全选，会让用户觉得很困惑。更好的做法是：首次打开时按默认规则全选，但一旦用户有过自定义保存，则读取用户记录。

接口文档别忘了说明

设计完之后，一定要在接口文档里明确：选中字段的含义、缺省行为、是否包含 disabled 状态、默认值是否会随用户操作改变。不要默认前端能猜出你的逻辑。PHP后端同学如果打开一个老项目，看到 `checked` 字段，应该清楚它是来自用户表还是配置表，而不是把业务逻辑写在控制器里。

接口设计没有银弹，但遵循“语义清晰、数据结构稳定、默认状态单一数据源”这几个原则，前端拿到的默认选中状态就会很干净，减少来回扯皮。多从使用方角度思考，少给前端留“自主发挥”的空间，很多线上问题其实都能避免。