lucid

Lucid

在 AdonisJS 应用中处理 Lucid 数据库层时使用此技能。Lucid 以数据库为先：迁移会更改数据库，Lucid 会生成 database/schema.ts，模型则继承生成的架构类，并声明关系、钩子、作用域、序列化和领域行为。

如果任务还涉及控制器、路由、验证器、策略、服务或更广泛的 AdonisJS 架构，请同时使用 adonisjs。如果要为 Lucid 行为编写测试，请同时使用 japa。

核心规则

• 将数据库视为事实来源。
• 在迁移中编写架构变更，然后运行迁移或 schema:generate，以更新 database/schema.ts。
• 不要手动编辑生成的 database/schema.ts。
• 模型文件通常应继承生成的架构类，并包含关系、钩子、作用域、序列化重写和领域方法。
• 对于 SQL 密集型查询、报表、一次性脚本，或不需要模型实例化时，使用 db 服务。
• 需要 Active Record 行为、关系、钩子、作用域、序列化或模型实例时，使用模型查询。
• 除非事务生命周期必须跨越函数边界，否则优先使用托管事务 db.transaction(async (trx) => ...)。
• 对具有破坏性的更新或删除查询，始终使用 where 子句限定范围。
• 预加载关系，不要在循环中查询。
• 使用 withCount、withAggregate、has 和 whereHas 进行关系感知型筛选和聚合。

工作流

对于会更改持久化数据的功能开发：

1. 确认现有表、生成的架构类、模型和关系。
2. 先编写或更新迁移。
3. 运行迁移，或注明重新生成 database/schema.ts 所需的命令。
4. 更新模型，使其继承生成的架构类，并添加仅适用于 Lucid 的行为。
5. 当约定不匹配时，使用显式键添加或更新关系。
6. 根据访问模式使用查询构建器、作用域或工厂。
7. 使用有针对性的测试或仓库中提供的类型检查命令进行验证。

采用现有数据库时：

1. 配置连接。
2. 在 schemaGeneration.excludeTables 中排除非托管表。
3. 运行 node ace schema:generate。
4. 仅为应用拥有的表创建模型。
5. 使用架构规则或模型级覆盖处理约定不匹配。

选择合适的 API

需求	首选方式
创建表或更改架构	使用 BaseSchema 的迁移
类型化模型列	来自 database/schema.ts 的生成架构类
行上的领域行为	模型方法和钩子
加载／筛选关系	模型查询构建器
报表或 SQL 密集型读取	db.from、db.query、原始查询构建器
多次写入的一致性	托管事务
测试数据	模型工厂
初始／开发数据	数据库播种器

参考资料

实施前请加载相关的本地参考资料：

• references/schema-and-models.md：迁移、架构生成、架构类、CRUD、作用域、钩子和序列化。
• references/query-builders.md：db 服务查询、模型查询构建器行为、分页、原始 SQL 和调试。
• references/transactions.md：托管／手动事务、隔离级别、保存点、行锁、模型事务，以及事务内的关系写入。
• references/relationships.md：belongsTo、hasOne、hasMany、manyToMany、hasManyThrough、预加载、关系筛选、聚合和写入。
• references/testing.md：测试数据库状态、工厂、工厂关系、中间表属性、钩子和播种器。

每份参考资料都会先介绍关键的实用模式，并在末尾链接到更深入的 Lucid 官方文档。

反模式

避免	推荐
手动编辑 database/schema.ts	使用迁移、架构规则或模型覆盖
在模型文件中手动声明每一列	扩展生成的 *Schema 类
在循环中运行关联查询	使用 preload、嵌套预加载、withCount、withAggregate
未限定范围的 update 或 delete	始终添加明确的 where 条件
为简单操作手动管理事务	使用托管的 db.transaction 回调
为集成流程模拟 Lucid 查询行为	使用 Japa 和测试数据库／工厂
所有报表查询都使用模型	直接使用 db 服务（只需普通行数据时）