Prisma ORM 4.x升级5.x遇到不兼容更新,源码探查解决方案

2023年 8月 16日 31.5k 0

项目背景

当前在项目中使用Prisma作为后端服务的ORM, Prisma ORM自称”Next-generation Node.js and TypeScript ORM“,支持的数据库有:

  • PostgreSQL
  • MySQL
  • SQLite
  • MongoDB
  • CockroachDB
  • Microsoft SQL Server

其他信息:

  • 后端框架: NestJS
  • 数据库: PostgreSQL

为什么升级5.x

2023/07/12官方发布了Prisma 5.0.0版本,see release note, 概况下来, 升级的主要内容有:

  • 一些预览特性GA, 包括jsonProtocol, fieldReference, extendedWhereUnique, 因此如果在4.x本版里开启过这些特性,升级后可以把显示的开启声明移除掉
  • 通用改进及一些破坏性改动
    • 依赖最低要求版本Nodejs(16.13.0), Typescript(4.7), PostgreSQL(9.6)
    • 主要变化
      • 删除rejectOnNotFound属性
      • 删除一些数组快捷方式
      • cockroachdb提供程序现在是连接到CockroachDB数据库时所需的
      • 已删除生成的Prisma客户端中的runtime/index.js文件
    • 其他变化
      • 删除Prisma CLI中的过时标志
      • 删除库引擎中的beforeExit钩子
      • 删除已弃用的prisma2可执行文件
      • 删除Prisma模式中的已弃用的experimentalFeatures生成属性
      • 重命名migration-engine为schema-engine

其中jsonProtocol正式GA,也是此次升级最大的亮点,升级后,Prisma将基于JSON的网络协议作为与查询引擎通信时使用的默认协议。 其实,在版本4.11.0中就引入了这一预览功能,以提高Prisma的性能。此前,Prisma使用类似GraphQL的协议与查询引擎进行通信。对于拥有较大模型的应用程序,CPU和内存消耗较高,这会导致性能瓶颈。 基于JSON的网络协议在Prisma客户端与查询引擎通信时提高了效率。

在2023/08/01发布的5.1.0版本里,进一步从SQL查询的实现层做了性能优化,具体见Release 5.1.0 · prisma/prisma (github.com)

所以决定升级到当前最新版本5.1.1, 为未来的5.x版本持续升级打下基础。

升级过程

  • package.json依赖升级
    • "prisma": "^4.16.0" => "prisma": "^5.1.1"
    • "@prisma/client": "^4.16.0" => "@prisma/client": "^5.1.1"
  • prisma shcema中移除GA的预览特性
  • 重新生成client npx prisma generate

兼容性问题出现

prisma升级后,服务运行正常,在开发环境运行一段时间后,测试反馈数据产生异常,观察出现异常的数据,发现数据库中某个字段json类型的数据值产生了如下变化:

image.png

javascript对象转换为json后的结果发生了改变,该字段原始javascript对象为:

{
  version: '1.0.0',
  data: Buffer.from('hello world'),
}

初步判断,升级后js对象的序列化逻辑发生了改变,导致Buffer在json中的表示产生了不一致,在升级后,Buffer转换为了base64字符串数据表示。

问题探查

  • 创建prisma-debug项目,分别安装4.16.2和5.1.1版本,省略创建过程,只说主要部分,源码已放到mobiusy/prisma-debug (github.com)
    • prisma schema 定义
      model Case {
        id              String   @id @default(uuid())
        name            String
        rawBinary       Bytes
        archiveSnapshot Json
        createdAt       DateTime @default(now())
        updatedAt       DateTime @updatedAt
      }
      
    • 测试代码
      import { Prisma, PrismaClient } from '@prisma/client';
      const client = new PrismaClient({
        log: ['query', 'info', 'warn', 'error'],
      });
      
      async function write() {
        try {
          client.$connect();
          await client.case.create({
            data: {
              name: 'prisma',
              rawBinary: Buffer.from('hello world'),
              archiveSnapshot: {
                version: '1.0.0',
                data: Buffer.from('hello world'),
              } as unknown as Prisma.InputJsonValue,
            },
          });
        } catch (error) {
          console.error(error);
        } finally {
          client.$disconnect();
        }
      }
      
      function main() {
        write();
      }
      
      main();
      
  • 分别在4.16.2和5.1.1版本中执行以上代码,复现了之前的问题,数据库中archiveSnapshot字段的值产生了不一致的情况
  • 打开prisma:debug, 查看运行输出,在Generated request这一步打印的结果来看,数据有了差异
  • image.png
    4. 下载prisma源码 prisma/prisma

    git clone git@github.com:prisma/prisma.git
    cd prisma
    git checkout 5.1.1
    

    找到源码中对应的代码:

    image.png
    源文件路径:github.com/prisma/pris…

    顺着serializeJsonQuery方法一路往下找,最终定位到具体的序列化逻辑

    issueCode.png

    其中有一个逻辑判断ArrayBuffer.isView(jsValue), 是判断当前字段是否为ArrayBuffer的视图,解释见ArrayBuffer.isView() - JavaScript | MDN (mozilla.org), 当jsValue为Buffer时满足条件,把jsValue转换为base64字符串

  • 至此问题已经比较清晰了,是升级后的jsonProtocol与原来的GraphQLProtocol对于js对象中Buffer字段的序列化实现不同产生的
  • 解决问题

    有两种方案可以解决:

  • 把数据库中原来旧数据转换为新的格式存储
  • 此问题是由于json对象不支持Buffer, Buffer序列化后产生的问题,因此把Buffer数据转换为json支持的数据类型再进行存储就可以
  • 1方案需要清洗数据库,尽量不考虑这种方案
    2方案只需要把Buffer数据转换为同4.16.2版本里序列化后的结果一致的输出即可,因此采用方案2

    代码改动:

    image.png

    复盘

    此问题的直接原因是json序列化器的对Buffer数据的处理逻辑不同导致的,而问题最终在prisma版本升级后暴露出来,其实在最初的版本的业务代码里就埋下了隐患,我们回头看最初的业务实现:

    image.png

    这里强制做了类型定义以满足archiveSnapshot字段的类型,那看一下archiveSnapshot的类型是:

    archiveSnapshot: JsonNullValueInput | InputJsonValue
    
    
      export type InputJsonValue = string | number | boolean | InputJsonObject | InputJsonArray
      export type InputJsonObject = {readonly [Key in string]?: InputJsonValue | null}
      export interface InputJsonArray extends ReadonlyArray {}
    

    InputJsonValue类型不接受Buffer类型,因此在最初的实现里通过as unknown as Prisma.InputJsonValue忽略静态检查警告为当前的问题埋下了伏笔。

    总结

  • 在typescript中的代码静态检查不要随意忽略
  • 对于js对象中包含Buffer类型的字段,最好使用自己的序列化器,进行序列化,而不要依赖第三方内置的序列化器
  • 相关文章

    JavaScript2024新功能:Object.groupBy、正则表达式v标志
    PHP trim 函数对多字节字符的使用和限制
    新函数 json_validate() 、randomizer 类扩展…20 个PHP 8.3 新特性全面解析
    使用HTMX为WordPress增效:如何在不使用复杂框架的情况下增强平台功能
    为React 19做准备:WordPress 6.6用户指南
    如何删除WordPress中的所有评论

    发布评论