Wave ORM需手动声明映射：实体类加#[Table]、主键字段加#[Column(isPrimary: true)]，非主键字段需显式#[Column]；事务须用Connection显式控制；无自动关联加载，需手动查询组装；PHP 8.1+需处理枚举类型转换。
Wave ORM 的基本映射怎么写
Wave 不是 Laravel Eloquent 那种“开箱即用”的 ORM，它更轻、更显式——你得手动声明实体类和数据库表的对应关系。不写 #[Table] 和 #[Column]，它根本不知道哪个类该映射哪张表。
常见错误是直接 new 一个类然后调用 save()，结果抛出 Wave\Exception\NoMappingFoundException：因为 Wave 根本没扫描到你的类定义。
- 必须在实体类上加
#[Table("users")]，表名要和实际一致（区分大小写） - 主键字段必须显式标注
#[Column(isPrimary: true)]，Wave 不自动猜id - 非主键字段默认不参与 INSERT/UPDATE，要写
#[Column]才会映射 - 类属性名和数据库字段名默认需完全一致；想自定义映射，用
#[Column(name: "user_name")]
示例：
#[Table("users")]
class User
{
#[Column(isPrimary: true)]
public int $id;
#[Column]
public string $name;
#[Column(name: "email_address")]
public string $email;
}
事务操作为什么总不生效
Wave 的事务不是靠模型方法隐式开启的，save()、delete() 这些操作默认各自走独立事务（或自动提交模式）。想跨多个操作共用事务，必须显式获取连接并手动控制。
立即学习“PHP免费学习笔记（深入）”；
典型坑：写了 $user->save(); $profile->save(); 然后以为加个 try/catch 就能回滚——其实两个 save 各自 commit 了，第二个失败时第一个早已落库。
- 事务起点是
$connection = Wave\Connection::get();，不是模型实例 - 所有需要事务包裹的操作，必须用同一个
$connection实例调用insert()、update()等底层方法 - 模型的
save()方法不接受 connection 参数，不能直接塞进事务块里用 - 正确做法是：先用
$connection->beginTransaction()，再用$connection->insert($user)或$connection->update($user)，最后commit()或rollback()
Wave 怎么查关联数据（比如用户+订单）
Wave 没有内置的 with() 或 belongsTo() 关系加载机制。它不自动 JOIN，也不延迟加载。所谓“关联”，得靠你自己组合查询或两次查询手动组装。
容易误以为 User::find(123)->orders 能跑通——其实会报 Undefined property，因为 orders 不是实体字段，Wave 不做魔法属性注入。
- 一对多：先查
User，再用$connection->select(Order::class)->where("user_id = ?", $user->id)->all() - 想 JOIN 查询：用
$connection->raw()->select(...)->from("users")->join("orders", "users.id = orders.user_id")...，返回的是数组，不是对象 - 如果硬要封装成对象关系，得自己写方法，比如在
User类里加public function getOrders(): array { ... }，内部调用 raw 查询 - 注意：Wave 不缓存关联结果，每次调都发新查询
PHP 8.1+ 下运行 Wave 的兼容要点
Wave 依赖属性反射（PHP 8.0+ 的 #[Attribute]），但在 PHP 8.1+ 中，若实体类用了枚举属性（如 public Status $status;），而数据库字段是字符串，Wave 默认不会自动转换——它不做类型 coercion。
常见现象：Cannot assign string to property User::$status of type Status，哪怕数据库里存的是 "active"。
- 解决方案一：把属性改成
string类型，业务层自己转枚举 - 解决方案二：用
#[Column(transform: [Status::class, "from"])]]，要求Status::from()是静态方法且接收字符串参数 - 注意
transform只作用于 SELECT → 对象赋值；INSERT/UPDATE 仍需你确保传入的是可 JSON 序列化的值（比如$user->status = Status::Active->value;） - Wave 不支持 PHP 8.2 的只读类（
readonly class），实体类必须允许属性写入
复杂点不在语法，而在思维切换：Wave 要求你始终清楚“哪一步在操作连接”“哪个对象来自哪次查询”“类型边界在哪”。一旦当成 Eloquent 用，问题就从报错变成数据不一致。
