ecto-essentials

Ecto 基础要点

遵循仓库的 Ecto 和数据库约定。业务规则放在上下文模块或纯领域模块中；Repo 调用放在持久化边界。

Schema 和 changeset

• 使用 schema 对持久化数据建模，并使用 changeset 验证外部输入。
• 对外部 map 使用 cast/3，并显式列出允许的字段。对可信的内部更新使用 change/2。
• 使用 unique_constraint/3、foreign_key_constraint/3 或相应的约束辅助函数，将数据库约束附加到 changeset，以便将预期的数据库错误作为 changeset 错误返回。
• 明确指定关联的所有权和删除行为。仅当嵌套输入属于公开操作的一部分时，才使用 cast_assoc/3。

查询和关联

• 使用命名绑定和参数化值组合 Ecto.Query 片段。绝不要将用户输入插入 SQL。
• 在查询函数中保留可复用的过滤和排序逻辑；在上下文模块中处理策略和编排。
• 预加载调用方所需的数据。对于列表，检查查询次数，并优先使用联接或批量预加载，而不是逐行调用 Repo.get/2。
• 根据调用方对数据缺失和错误的预期约定，使用 Repo.one/1、Repo.all/1 及其 bang 变体。

写入和事务

• 对预期的失败返回 {:ok, value} / {:error, changeset_or_reason}。
• 当事务包含多个命名步骤，或调用方需要关心失败步骤时，使用 Ecto.Multi。对于小型原子操作块，使用普通事务。
• 不要在数据库事务中执行网络调用或其他不可逆的副作用。
• 对于 upsert，明确指定冲突目标，并确认数据库约束与其匹配。

验证

针对变更后的持久化行为添加或更新测试。先运行相关测试，再运行涵盖 Ecto 和迁移的项目检查。仅当更窄范围的行为是核心内容时，才使用 ecto-changeset-patterns、ecto-nested-associations 或 ecto-migration。