言映 1.0.0
摘要
1.0.0 把言映从基础模型映射升级为可公开使用的现代 ORM：模型与实体、参数化查询、四类关系、批量预加载、验证与钩子、软删除、乐观锁、模式反射、版本化迁移、环境种子、命令适配及言据数据库能力形成一个稳定边界。
言映继续保持显式设计：应用选择并打开数据库连接，事务对象显式传递，关系只在明确请求时加载，原始 SQL 只能通过明确入口使用。
主要能力
模型与字段
- 整数、大整数、小整数、小数、浮点、布尔、文字、长文字、字节、日期、时间、日期时间、UUID、枚举、言据、JSON、虚拟和自定义字段；
- 单/复合主键、自增、唯一、可空、默认、数据库默认、检查、外键和复合索引；
- 映射列名、getter、setter、自定义序列化/反序列化和方言 SQL 类型；
- 复用言验规则的字段及模型验证。
实体与查询
- 当前值、原始快照、深层言据脏追踪和事务快照；
- 创建、批量创建、更新、批量更新/删除/恢复、查或新建、查或创建、更新或创建；
- 保存、重载、软删除、恢复、物理删除和乐观锁；
- 参数化比较、IN、区间、文字、空值、组合条件、聚合、查并计数和分页；
- 默认/命名作用域及显式包含已删除范围。
关系
- 属于、一对一、一对多和多对多；
- 模型级及查询期条件、排序、字段选择、必需、分离查询和嵌套包含；
- 批量父键查询避免按父项 N+1，多对多使用中间表 JOIN；
- 显式单实体延迟加载和关联计数，不在字段读取时隐式访问数据库。
言据
- 所有后端可用的规范
.yj文本策略； - PostgreSQL JSONB、MySQL/MariaDB JSON、SQLite JSON1 文本的原生结构策略；
- 可选 Schema、字节上限、默认值、空值、稳定比较和日志脱敏；
- 路径存在、缺失、等值、非等值、数字比较和文字包含；
- SQLite 原生结构在写入时编码 JSON，查询物化时恢复言序值。
迁移、种子与命令
- SQL、代码和结构化言据动作迁移；
- 严格递增版本、SHA-256 校验和、历史漂移检查和不可逆标记；
- SQLite 写事务锁、PostgreSQL advisory transaction lock、MySQL/MariaDB 命名锁；
- 状态、检查、干运行升级、升级、按次数回退和回退到版本；
- SQL 与参数化言据数据种子、环境过滤、幂等登记和回退；
- 基于言令的迁移/种子命令对象和稳定 JSON 结果信封。
兼容性
| 项目 | 版本或范围 |
|---|---|
| 言序 | 1.1.12 或后续兼容 1.x |
| 言据 | 1.2.x；固定 v1.2.0 |
| 言库 | 1.x；固定 v1.0.0 |
| 言验 | 1.x；固定 v1.0.0 |
| 言令 | 1.x；固定 v1.0.0 |
| SQLite | 言舟 1.x；原生 SQLite 3.53.2，JSON1 |
| PostgreSQL | 14–18；18.4 已真实验证 |
| MySQL | 8.x；8.4.10 已真实验证 |
| MariaDB | 10.x/11.x；11.8.8 已真实验证 |
核心是纯言序包，不含原生制品。真实驱动须使用对应平台 ABI v2 制品和字节码 VM/YXB。完整矩阵见 COMPATIBILITY.md。
从 0.1 升级
- 把依赖改为
修订 = "v1.0.0"、版 = "^1.0"； - 使用言序 1.1.12 串行更新根包、示例、基准和集成消费者锁；
- 把言据、言库、言验、言令及数据库驱动升级到上表稳定线；
- 检查自由运算符、动态排序、字符串拼 SQL 和隐式软删除假设；这些不安全行为会被拒绝；
- 明确选择言据字段的
规范文本或原生结构，不要把数据库 JSON 当作规范言据； - 用正式迁移替代生产自动同步，先运行检查和干运行；
- 在实际数据库大版本执行升级、读写、关系、路径、回退和重新升级演练。
模型(名称, 表名)构造方式继续兼容；推荐新代码使用 定义模型。详细步骤见 MIGRATION.md。
安全与权限
核心权限保持：
文件 = []
网络 = []
TCP监听 = []
UDP绑定 = []
环境 = []
进程 = false
原生扩展 = false
应用和驱动负责网络目标、TLS、凭据、连接池和原生扩展权限。所有普通条件值参数化；原始条件、SQL 迁移/种子、数据库默认表达式和自定义处理器是受信任代码边界。
安全模型、漏洞报告方式和敏感日志规则分别见 SECURITY_MODEL.md与 SECURITY.md。
验证结果
使用未修改的言序 1.1.12 发布工具链完成本地发布门禁：
- 27 个言序文件通过静态检查与格式检查，其中源码 10 个、规格 14 个、示例/基准/真实数据库消费者各 1 个；
- 14/14 个 ORM 规格通过；
- 机器 API JSON 生成通过，写入计划模块拆分前后公开 API 逐字一致；
- ORM 根包、博客示例、基准和四数据库消费者生成 Release YXB；
- 博客示例和参数化性能基准的源码/Release 路径通过；
- SQLite、PostgreSQL 18.4、MySQL 8.4.10、MariaDB 11.8.8 的真实消费者均在源码与 Release YXB 下通过；
- PostgreSQL、MySQL、MariaDB 测试后均无
yanxu_orm_it_%残留表； - GitHub Actions 工作流通过本地
actionlint检查。
这些结果是本地发布验证；远端 CI 状态以发布 PR 的检查记录为准。
已知限制
模式迁移器只执行开发期安全加法变化，不删除列、不改不兼容类型、不重建主键；- SQLite 不支持在线增加外键/检查约束或一般改列，须使用重建表的显式迁移；
- MySQL/MariaDB DDL 可能隐式提交，无法承诺跨多语句 DDL 原子回滚；
- 生命周期钩子按注册顺序同步执行，不提供后台任务调度；
批量创建逐实体执行参数化写入，以保留验证、钩子、自增键和状态回滚语义，不等同于 COPY；- 连接池、TLS、驱动重试、网络超时、取消、日志和指标由言库及驱动实现；
- 关系预加载按关系/层级批量查询；循环显式延迟加载仍可能形成 N+1；
- 原始 SQL 和自定义回调不能接收未经审计的用户输入。
发布内容
- API：API.md
- 使用：GUIDE.md
- 架构：ARCHITECTURE.md
- 迁移：MIGRATION.md
- 性能：PERFORMANCE.md
- 安全模型：SECURITY_MODEL.md
- 更新记录：CHANGELOG.md