后端【免费下载链接】mikro-ormTypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.项目地址https://gitcode.com/gh_mirrors/mi/mikro-orm点击查看免费下载本指南基于当前仓库 version-7.1 版本文档 展开。自 v6 起mikro-orm 使用 JavaScript 原生BigInt表示数据库中的bigint列主键定义因此不再需要显式指定类型同时BigIntType允许你将 bigint 列灵活映射为bigint、string或number三种 JS 目标类型。读完本文你将掌握 BigInt 主键的零配置声明方式、三种映射模式的取舍以及BigIntType在序列化、JSON 反序列化与不同 SQL 平台下的底层行为。为什么需要专门处理 BigInt 主键在分布式系统、雪花算法 ID 或高流量自增表中主键经常超出 32 位整数的范围数据库侧使用bigint8 字节最大约 9.2 × 10^18来承载。传统 JavaScriptnumber是双精度浮点数只有2^53 - 1即Number.MAX_SAFE_INTEGER以内的整数才能被精确表示直接以number承载大主键存在精度丢失风险。mikro-orm 从 v6 开始引入原生BigInt支持bigint类型的属性默认映射为 JS 原生BigInt无需在装饰器选项中显式声明类型。同时提供BigIntType自定义类型用于按需把列值映射到bigint、string或number。零配置用法原生 bigint 主键自 v6 起bigint属性直接用原生BigInt类型声明即可装饰器里不需要写typePrimaryKey() id: bigint;从源码看这一零配置行为是有据可依的在 Platform.ts 中bigint这个 JS 类型名会被解析并返回Type.getType(BigIntType)同时内置类型注册表 types/index.ts 中bigint: BigIntType也使得你可以显式写{ type: bigint }来达到同样效果。也就是说原生声明与type: bigint最终都会落到同一个BigIntType实例上。BigIntType 三种目标类型模式如果需要把 bigint 列映射为其他 JS 类型可以实例化BigIntType并传入模式参数。其类型签名定义在 BigIntType.tsexport class BigIntTypeMode extends bigint | number | string bigint三种模式对比如下依据源码convertToDatabaseValue/convertToJSValue/toJSON/fromJSON的实现整理模式JS 属性类型入库值JS 端读取结果JSON 序列化输出适用场景bigint默认bigint十进制字符串原生BigInt十进制字符串需要精确表示超大主键stringstring十进制字符串字符串十进制字符串与前端/API 以字符串传 IDnumbernumber十进制字符串number纯number主键在安全整数范围内、追求数字运算便利对应的实体定义示例PrimaryKey({ type: new BigIntType(bigint) }) id1: bigint; PrimaryKey({ type: new BigIntType(string) }) id2: string; PrimaryKey({ type: new BigIntType(number) }) id3: number;⚠️ 原文档明确强调JavaScript 无法表示bigint的全部取值——当映射到number类型时只有Number.MAX_SAFE_INTEGER2^53 - 1以内的值才是安全支持的。超出该范围的大主键请使用bigint或string模式。源码级解析BigIntType 的四个关键行为1. 入库转换一律字符串化convertToDatabaseValue将 JS 值转为十进制字符串再交给数据库驱动return value;无论哪种模式落库的 SQL 绑定值都是字符串这也与多数数据库驱动如 pg、mysql2默认以字符串返回bigint列的行为吻合——BigIntType正是为此设计它会在读取时把驱动返回的字符串转换回目标 JS 类型见 BigIntType.ts。2. 读取转换按模式分派convertToJSValue依据this.mode分派number走Number(value)string走String(value)默认分支走BigInt(String(value))。这也是三种模式行为差异的根源BigIntType.ts。3. 序列化与 JSON 反序列化安全优先原生BigInt直接交给JSON.stringify会抛出TypeError因此toJSON做了特殊处理number模式原样返回数值其余模式返回十进制字符串BigIntType.ts。fromJSON则承担反序列化校验职责只接受形如^-?\d$的十进制字符串或整数number更重要的是在number模式下若反序列化得到的值不是安全整数Number.isSafeInteger为 false会直接抛出ValidationError.invalidType——源码注释明确说明这是为了让被篡改的游标tampered cursor失败得响亮而不是被Number静默四舍五入BigIntType.ts。这意味着基于 bigint 主键的游标分页在number模式下天然具备溢出防护。4. 比较逻辑影响去重与查询compareAsType返回mode ?? bigintcompareValues以字符串比较保证 Identity Map 中主键去重和 where 条件比较的一致性BigIntType.ts。数据库列类型平台差异与自增处理BigIntType.getColumnType委托给平台的getBigIntTypeDeclarationSQLBigIntType.ts。基类 Platform.ts 的默认实现直接返回bigintPostgreSQL 平台则做了自增特化——当属性为自增列时返回bigserial否则返回bigint见 BasePostgreSqlPlatform.ts。这也解释了文档标题限定MySQL and PostgreSQL的原因这两个平台都原生支持 bigint 主键且 Schema 生成器能正确处理其声明 SQL。工程实践建议与测试佐证ID 精度优先大主键雪花 ID、分布式自增务必使用默认bigint或string模式避免number模式在超过 2^53 时静默丢精度。API 交互bigint模式序列化输出为字符串前端可安全接收number模式则输出纯数字适合主键较小的存量系统。游标分页number模式下的fromJSON安全整数校验为游标篡改提供了防护BigIntType.ts。仓库测试对此有充分覆盖例如 GH2410.test.ts 在 PostgreSQL 实体上以PrimaryKey({ type: BigIntType })使用该类型此外 GH482.test.ts、GH5146.test.ts、GH5528.test.ts 等 issue 回归测试均涉及 bigint 主键场景可作为继续深入阅读的入口。小结mikro-orm 对bigint主键的支持可以概括为v6 起默认以原生BigInt承载零配置声明需要时通过BigIntType(bigint | string | number)切换目标 JS 类型BigIntType在入库、读取、JSON 序列化/反序列化、列类型声明四个环节分别做了字符串化、模式分派、安全校验与平台适配。在 MySQL / PostgreSQL 上定义大主键实体时优先选择bigint或string模式把number模式留给安全整数范围内的场景即可。赞分享后端【免费下载链接】mikro-ormTypeScript ORM for Node.js based on Data Mapper, Unit of Work and Identity Map patterns. Supports MongoDB, MySQL, MariaDB, MS SQL Server, PostgreSQL and SQLite/libSQL databases.项目地址https://gitcode.com/gh_mirrors/mi/mikro-orm点击查看免费下载相关推荐mikro-orm 原生 BigInt 主键实战指南MySQL 与 PostgreSQL 下的 BigIntType 映射详解mikro orm 原生 BigInt 主键实战指南MySQL 与 PostgreSQL 下的 BigIntType 映射详解 导读 本文聚焦 mikro o后端mikro-orm 原生 BigInt 主键实战MySQL 与 PostgreSQL 下的精度安全实践mikro orm 原生 BigInt 主键实战MySQL 与 PostgreSQL 下的精度安全实践 本文基于 mikro orm 官方文档 Using n后端MikroORM 原生 BigInt 主键使用指南三模式映射、平台差异与源码级转换原理MikroORM 原生 BigInt 主键使用指南三模式映射、平台差异与源码级转换原理 本文是 MikroORM 7.x 系列关于 bigint 原生主键P后端上一篇终极指南5分钟彻底解决Webpack循环依赖让项目告别死循环噩梦下一篇Imagine Engine社区贡献指南如何参与开源游戏引擎开发创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考