CodeIgniter 4 的实体类是数据库层原生组件，专注数据结构与业务逻辑表达，不执行SQL；必须继承Entity类并与Model配合使用，通过$datamap和$casts控制字段映射与类型转换，用于API序列化和视图封装。
CodeIgniter 4 的实体类（Entity）不是可选插件，而是数据库层的原生能力——它不负责查库，只专注表达“一行数据该长什么样”以及“这行数据该懂什么业务规则”。用错地方（比如当成模型或直接查数据库）是新手最常踩的坑。
Entity 类必须继承 CodeIgniter\Entity 并配对 Model 使用
实体类本身不会执行 SQL，也不能独立调用 find() 或 save()。它必须和一个继承 CodeIgniter\Model 的模型类配合使用，由模型负责持久化，实体只承载数据和逻辑。
- 创建命令：
php spark make:entity User（生成在app/Entities/） - 实体类里不能写数据库操作，但可以加方法：
public function getFullName(): string { return $this->first_name . ' ' . $this->last_name; } - 模型中需显式指定实体：
protected $returnType = \App\Entities\User::class; - 调用时自动转换：
$user = $this->userModel->find(1);→ 返回的是User实例，不是数组
$datamap 和 $casts 是字段映射与类型转换的核心配置
数据库字段名和 PHP 属性名不一致？日期存成字符串却要当 DateTime 用？全靠这两个属性控制。
-
$datamap = ['user_id' => 'id', 'created_at' => 'createdAt'];：把数据库字段user_id映射为实体属性$id -
$casts = ['is_active' => 'boolean', 'created_at' => 'datetime'];：读取时自动转布尔、自动实例化DateTime对象 - 注意：
$casts中的datetime默认用Y-m-d H:i:s格式解析；若数据库存的是时间戳，得自定义转换器并实现CastInterface - 字段名未在
$datamap中声明 → 实体里无法通过属性访问（哪怕数据库有该列）
实体方法不能访问模型或服务，但可安全用于 API 序列化
实体类运行在数据层之上，没有 $this->db，也没有请求上下文。但它特别适合做“出参净化”和“视图友好封装”。
立即学习“PHP免费学习笔记（深入）”；
- 避免在控制器里拼接字段：
['full_name' => $user['first_name'] . ' ' . $user['last_name']]→ 改成实体方法$user->getFullName() - API 返回前可统一处理：
return $this->response->setJSON($user->toArray());，toArray()会尊重$casts和$datamap - 不要在实体里调
service('cache')或查其他表——这类逻辑应上移到服务类或模型的业务方法中 - 若需验证，用框架的
Validation类校验原始输入，而不是在实体__set()中抛异常
真正容易被忽略的是：实体一旦启用 $returnType，模型的 asArray() 就失效了；而如果你在实体里改了 $attributes 却没同步更新 $datamap，save() 会静默丢掉字段——连 warning 都不报。
