言映：ORM

言映（包名 言映，仓库 yanxu-orm）是言序的显式模型映射与数据库工作流库。它使用言库的连接、方言和事务协议执行 SQL，复用言验进行字段验证，并把模型、查询、关系、迁移和种子保留为可组合对象；它不会隐式打开连接，也没有全局事务状态。

安装并固定公开标签

先安装 ORM，再显式选择驱动：

yanbao add orm --package 言映 --version "^1.0"
yanbao add sqlite --package 言舟 --version "^1.0"

可复现的 SQLite 应用清单：

[依赖]
言映 = { git = "https://github.com/yanxulang/yanxu-orm.git", 修订 = "v1.0.0", 版 = "^1.0" }
言舟 = { git = "https://github.com/yanxulang/yanxu-sqlite.git", 修订 = "v1.0.0", 版 = "^1.0" }

其他稳定驱动：

# PostgreSQL：二选一，不要和下面一项同时作为同一连接使用
言库象城 = { git = "https://github.com/yanxulang/yanxu-postgres.git", 修订 = "v1.0.0", 版 = "^1.0" }

# MySQL / MariaDB
言库海豚 = { git = "https://github.com/yanxulang/yanxu-mysql.git", 修订 = "v1.0.0", 版 = "^1.0" }

更新依赖后重新生成并提交格式 2 锁文件。连接配置、TLS、连接池、取消和驱动原生制品由言库及所选驱动管理。

定义模型与字段

引「包:言映」为 言映；
引「包:言验」为 言验；

定 文章 为 言映.定义模型（「文章」，「posts」）
    .加字段（言映.自增主键（「编号」）.映射（「id」））
    .加字段（言映.大整数字段（「作者号」）.映射（「author_id」））
    .加字段（言映.文字字段（「标题」）.映射（「title」）.不可空（））；

定 用户 为 言映.定义模型（「用户」，「users」）
    .加字段（言映.自增主键（「编号」）.映射（「id」））
    .加字段（言映.文字字段（「邮箱」）
        .映射（「email」）
        .长度（3，254）
        .唯一（）
        .用规则（言验.文本（）.至少（3）））
    .加字段（言映.言据字段（「资料」）
        .映射（「profile」）
        .大小限制（262144）
        .存储为（「原生结构」））
    .加字段（言映.文字字段（「密码摘要」）
        .映射（「password_hash」）
        .脱敏（））
    .启用时间戳（「创建时间」，「更新时间」）
    .启用软删除（「删除时间」）
    .启用乐观锁（「版本」）
    .加关系（言映.一对多（「文章」，文章，「编号」，「作者号」））；

1.0 提供 20 个字段工厂，包括整数、小数、布尔、文字、字节、日期时间、UUID、枚举、JSON、言据、虚拟、自定义字段与自增主键。支持单/复合主键、唯一、可空、默认、数据库默认、检查、外键、复合索引、自定义编解码和映射列名。

数据库默认、检查、SQL类型为 和自定义编解码器属于受信任代码边界，只能接收受审计常量，不能直接接收请求文字。

创建、查询与参数安全

定 新用户 为 用户.创建（{
    「邮箱」：「zijin@example.test」，
    「资料」：{「等级」：2，「标签」：【「新用户」】}，
    「密码摘要」：「已散列值」
}，数据库）；

定 活跃用户 为 言映.查询（用户，数据库）
    .条件式（言映.且式（
        言映.字段（「编号」）.至少（1），
        言映.字段（「邮箱」）.文字结尾（「@example.test」）
    ））
    .选择（【「编号」，「邮箱」，「资料」】）
    .排序（「编号」，「DESC」）
    .分页（1，20）；

言 活跃用户.项目；
言 活跃用户.总数；
言 活跃用户.有下一页（）；

普通条件、IN、区间、文字条件、关系父键与言据路径值都进入参数列。字段先在模型中解析，再由方言安全引用；运算符与排序方向使用固定白名单。参数不能代表表、列、排序或操作符。

查询.SQL() 与 查询.参数() 适合测试生成结果，不应把参数重新拼回 SQL。原条件(SQL, 参数) 是显式厂商扩展点：SQL 片段必须来自受信任源码，动态值仍放进参数列。标识引用不能代替行级授权或租户隔离。

批量创建使用一个事务单元，逐实体保留验证、钩子、自增键和状态回滚语义；任何项失败会回滚整批，单次最多 1,000 项。它不是 PostgreSQL COPY 或数据库专有 bulk loader。

关系与有界预加载

文章.加关系（言映.属于关系（「作者」，用户，「作者号」，「编号」））；

定 文章加载 为 言映.关联（「文章」）
    .选择（【「编号」，「标题」】）
    .排序（「编号」，「ASC」）
    .必需（）；

定 各用户 为 言映.查询（用户，数据库）
    .包含（文章加载）
    .全部（）；

支持 属于关系、一对一、一对多和多对多。预加载会合并父键后执行有界 IN 查询，多对多使用中间表 JOIN；嵌套 包含 也按层批量处理，避免每个父实体一次查询。

关系不会因普通字段读取而隐式访问数据库。单实体延迟加载必须显式调用 实体.加载关联(名称, 连接)；在循环里反复显式延迟加载仍可能形成 N+1。

实体、脏追踪与并发

定 所用户 为 用户.按主键（编号，数据库，假）；

所用户.设（「邮箱」，「new@example.test」）；
置 所用户.取（「资料」）【「等级」】 为 4；

言 所用户.脏字段（）；
言 所用户.变更（）；
所用户.保存（数据库）；

所用户.删除（数据库）；
所用户.恢复（数据库）；

实体保存当前值和原始快照。言据字段按规范序列化结果比较，因此嵌套典或列的原地修改也会被识别。持久化成功后刷新快照；事务失败会恢复数据库和内存事务快照。

启用软删除后，普通根查询与预加载都排除已删除记录；绕过必须显式使用 包含已删除、只查已删除 或 物理删除。启用乐观锁后，原版本进入 UPDATE 条件且成功时递增；影响零行返回 YANYING_OPTIMISTIC_LOCK，不会静默覆盖并发写。

.脱敏() 只让 实体.转日志典() 输出 ***；各值() 和 转普通对象() 仍返回业务值，应用不能把它当作字段级加密。

事务与事务单元

ORM 的“连接”参数可以是真实连接，也可以是实现同一协议的事务对象：

法 创建文章（事务）则
    定 用户项 为 用户.创建（用户数据，事务）；
    文章.创建（{
        「作者号」：用户项.取（「编号」），
        「标题」：「新篇」
    }，事务）；
    归 用户项；
终

定 结果 为 数据库.事务（创建文章）；

需要集中协调已有实体时使用事务单元：

定 单元 为 言映.事务单元（数据库）；
单元.新增（待新增）
    .跟踪（待更新）
    .删除（待删除）；

定 提交摘要 为 单元.提交（）；

事务单元在同一事务内验证并执行新增、更新、删除、强制删除或恢复；失败时恢复实体主键、快照和删除状态。保存点、隔离级别、只读、超时和提交后钩子由言库与驱动提供，言映不创建不可见全局事务。

连接池边界

言映不重复实现连接池。使用象城/海豚的 创建连接池(配置, 池配置)，或用言库连接池组合言舟连接工厂；从租约取得底层连接作为 ORM 参数，并在所有路径释放租约：

定 租约 为 连接池.取得（）；
试 则
    定 用户项 为 用户.创建（用户数据，租约.连接（））；
    租约.释放（）；
救 所误 则
    租约.释放（）；
    抛 所误；
终

租约释放后，不能继续使用租约或先前取得的底层连接，也不能保留其事务或预编译语句。池的大小、等待上限、健康检查、空闲/寿命淘汰和优雅关闭属于言库/驱动配置；池不会自动重放不确定状态的写请求。

开发反射与安全模式计划

定 反射 为 言映.模式反射器（数据库）.读取（用户）；
言 反射；

定 同步器 为 言映.模式迁移器（数据库）；
定 计划 为 同步器.计划（【用户，文章】）；
言 计划.SQL列；
言 计划.警告列；

同步器.应用（【用户，文章】）；

反射器统一读取 SQLite PRAGMA 与 PostgreSQL/MySQL/MariaDB information_schema。开发期模式迁移器只创建缺失表和添加普通列；删除列、改不兼容类型、重建主键等破坏性变化只进入警告，不会自动执行。

生产环境不得用模式同步替代版本化迁移。SQLite 在线增加外键/检查约束和一般改列也不受支持，应编写重建表的显式迁移。

正式迁移、种子与命令

定 各迁移 为 【
    言映.迁移（
        202607180001，
        「创建用户表」，
        「CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT NOT NULL)」，
        「DROP TABLE users」
    ）
】；

定 迁移器 为 言映.默认迁移器（数据库）；
言 迁移器.状态（各迁移）；
言 迁移器.检查（各迁移）；
言 迁移器.干运行升级（各迁移）；
迁移器.升级（各迁移）；

正式迁移支持三种定义：

• 迁移：受信任的升级/降级 SQL；
• 代码迁移：参数化处理器和调用方提供的稳定校验和；
• 动作迁移 / 言据迁移：建表、列、索引、外键等结构化动作。

版本必须严格递增，SHA-256 漂移会阻止继续。SQLite 使用写事务锁，PostgreSQL 使用事务级 advisory lock，MySQL/MariaDB 使用命名锁。锁只协调使用相同登记表与锁号的迁移器。

PostgreSQL 与 SQLite 在其支持范围内可把 DDL 和登记放入事务；MySQL/MariaDB DDL 可能隐式提交，失败后必须审计已完成前缀与真实结构，不能宣称整体回滚。

言映还提供 SQL 种子与参数化 数据种子，按标识、环境和校验和幂等登记；命令行适配器基于言令提供迁移/种子的状态、检查、干运行、执行和回退。生产发布仍须备份、恢复演练并在精确数据库版本运行迁移。

言据字段：TEXT 与原生结构

定 资料模式：典 为 {
    「类型」：「据」，
    「属性」：{「等级」：{「类型」：「数」，「整数」：真}}，
    「必需」：【「等级」】，
    「允许额外」：真
}；

定 资料字段 为 言映.言据字段（「资料」）
    .Schema（资料模式）
    .大小限制（262144）
    .存储为（「规范文本」）；

数据库 JSON 不是规范言据文本。SQLite 的原生结构实际写入 JSON1 可查询文本；MariaDB 只有驱动确认持久基表 JSON_VALID 约束后才结构化解码。驱动未声明能力时，原生结构 和路径查询会明确失败，不会全表加载到内存模拟。

定 高等级 为 言映.查询（用户，数据库）
    .条件式（言映.言据路径（「资料.等级」）.至少（10））
    .全部（）；

言据字段可设置 Schema 与字节上限；验证保证结构，不代表调用者有权读写该模型、字段或行。

四数据库兼容矩阵

支持范围不等于应用的精确补丁、扩展、字符集、排序规则、时区和数据库参数已经验证。上线前必须在实际环境跑迁移、关系、言据路径、并发和回退测试。

权限与运行方式

言映核心固定不申请文件、网络、监听、环境、进程或原生扩展权限：

[权限]
文件 = []
网络 = []
TCP监听 = []
UDP绑定 = []
环境 = []
进程 = false
原生扩展 = false

驱动消费者仍须声明实际权限：言舟文件数据库需要路径文件权限，象城/海豚需要目标网络权限，三套原生驱动都需要 原生扩展 = true。真实驱动依赖 标准:原生，必须通过字节码 VM、包运行或 YXB；ORM 核心测试替身不代表树解释器可以载入真实驱动。

明确限制与安全非目标

• 模型最多 256 个字段、128 个关系；条件深度最多 32；枚举最多 256 项。
• 言据字段默认上限 1 MiB，硬上限 16 MiB；批量创建单次最多 1,000 项。
• 连接池、认证、TLS、查询取消、驱动重试、网络超时、日志与指标属于言库和具体驱动。
• 言映不提供身份认证、行级授权、租户隔离证明、字段加密、密钥管理、备份恢复或在线模式变更编排。
• 原条件、SQL 迁移/种子、数据库默认、检查表达式、自定义 getter/setter/编解码和代码迁移都是受信任扩展点。
• 生命周期钩子同步执行，不能吞掉数据库错误或在事务外制造与主操作不一致的副作用。
• 原始错误详情含位置和踪迹，只适合受控诊断；对外响应应映射为最小错误，不公开模式名、文件路径或堆栈。

错误以 YANYING_ 稳定代码分类，底层数据库错误保留言库/驱动分类。仓库与 1.0.0 Release：yanxulang/yanxu-orm。