---
name: model-field-accessor-first
description: MallBase ThinkPHP 模型字段访问器与素材回显规则；在 Model 字段读写、访问器、修改器、with 关联、素材 ID 回显或 Service 字段组装优化时使用。
---

# ThinkPHP 规则：模型语义优先，素材回显批量处理

## 适用范围

- `backend/app/*/model/**`
- `backend/app/*/service/**`
- 重点字段：JSON 字段、路径/URL 字段、素材 ID 字段、模型关联、需要补充 `*_full_url` 的返回字段

## 强制规则

1. 正式模型字段的结构语义优先放在 Model 中处理，例如关联、枚举文案、JSON 归一化、修改器。
2. 正式模型字段的写入，优先依赖 Model 类型转换、修改器和 `$model->save()`。
3. Service 允许做保存前业务归一化，例如字段裁剪、结构标准化、业务校验。
4. 简单展示型关联优先使用模型关联 + `with()`，避免重复手写 `ids -> map -> foreach`。
5. JSON 字段如果定义了获取器，必须兼容 `think\model\type\Json` 对象输入，不能假设传入值一定是数组。
6. 路径/URL 字段可以在模型访问器中补充 `*_full_url`。
7. 素材 ID 字段禁止在模型访问器中查素材表或调用只能处理路径的 `buildUploadUrl()` 伪装成 URL 回显。
8. 素材 ID 的 `*_full_url` 回显必须在 Service 层或专用回显服务中批量解析，避免模型访问器隐式 N+1。
9. 关联字段参与筛选、排序、聚合时，使用 `join`、`exists` 或明确的关联 ID 查询，不依赖 `with()`。
10. 禁止在 Controller / Service / Model 中使用 `var_dump`、`dump`、`echo`、`die` 这类会污染接口响应的调试输出。

## 推荐做法

1. 正式字段先在 Model 中声明 `$json`、`$jsonAssoc`、`$append`。
2. 一对一、一对多等简单展示关系先定义模型关联，读取时优先 `with()`。
3. 读取路径/URL 字段时，可以通过 `get*Attr()` 补充展示字段。
4. 读取素材 ID 字段时，用 `AssetHydrator` 或等价批量解析工具补充 `*_full_url`。
5. 保存时让 Service 只做结构归一化，再交给 Model 持久化。
6. 若 Swoole 常驻进程未刷新字段定义，优先重启服务，不在业务代码里加绕行逻辑。

## 素材字段判定

- 字段类型或注释是素材 ID，例如 `bigint unsigned COMMENT '头像素材ID'`：不要在模型访问器里拼 URL。
- 字段类型是路径字符串，例如 `varchar(255) COMMENT '头像'` 且存 `/static/...`、`/uploads/...`、`https://...`：可以使用 `buildUploadUrl()`。
- 同一个接口返回多条记录时，素材 URL 必须批量解析，不允许每条记录独立查素材。

## 反例

- 在 `User::getAvatarFullUrlAttr()` 里把素材 ID `1` 传给 `buildUploadUrl('1')`。
- 在模型访问器里通过素材 ID 查询 `upload_asset` 表。
- Service 中为简单关联展示手写多层 `array_column -> whereIn -> map -> foreach`，而模型已有清晰关系可用。
- 只包一层 `app()->make()` 且没有测试替身价值的私有方法。
- 在 `getSpecMetaAttr()` 里直接 `var_dump($value)`

## 自检清单

- [ ] 简单展示型关联是否已优先使用 `with()`。
- [ ] 关联字段参与查询条件时，是否在查询构建方法中处理。
- [ ] 素材 ID 字段是否避免了模型访问器隐式查询。
- [ ] 素材 URL 是否通过批量回显补充。
- [ ] 路径/URL 字段的访问器是否与 schema 匹配。
- [ ] JSON 字段获取器是否兼容 `think\model\type\Json`。
- [ ] 展示增强是否只追加字段，不覆盖原始存储值。
- [ ] Service 中是否还存在无收益薄封装。
- [ ] 接口链路中是否已清除调试输出。