7. 数据库访问

TypeScript 课程用三章来讲解 MySQL 数据库的访问:先是原生驱动 [mysql2],然后是两个 ORM([TypeORM] 和 [Prisma]),使用同一个示例——两个数据库,[dbpersons](单个表)和 [dbschool](四个相关联的表:班级、学生、科目和成绩)。本章与第一章相同,然后把两个 ORM 章节合并为一章:Dart 没有成熟的、可用于 MySQL 的 [TypeORM] 或 [Prisma] 的等价物(见本章末尾的补充说明),因此我们不去强行与其中任何一个建立人为的对应关系,而是亲自动手编写一个“轻量级 ORM”,以此展示 ORM 究竟做了什么。
7.1. 直接访问数据库

TypeScript 的 [mysql2] 包在 Dart 一侧没有由 MySQL 团队自己维护的等价物。本章的早期版本使用的是 [package:mysql1](pub.dev/packages/mysql1),这是一个被广泛使用的纯 Dart 驱动——MySQL——但事实证明它与 MySQL 8.4(Laragon 随附的版本)不兼容:即使是“select 1”这样简单的查询也始终失败,并报告协议错误“Got packets out of order”,这是该包中一个已知且尚未解决的缺陷(GitHub 问题 adamlofts/mysql1_dart #112 和 #161)。因此我们现在改用 [package:mysql_client_plus](pub.dev/packages/mysql_client_plus),这是一个积极维护的分支,已在 MySQL 8.x 上测试过,其 API——[MySQLConnection.createConnection]、[connection.connect]、[connection.execute]、[connection.close]——与 [mysql2] 的非常相似。
7.1.1. 准备 [dbpersons] 数据库
dbpersons 数据库只包含一个表 persons, 其结构与 Python 课程中使用的相同(列 id、first\_name、last\_name, age,并对 (last\_name, first\_name) 这一对列设有唯一性约束)。下面的脚本 sql/create_dbpersons.sql 会创建数据库、应用程序用户和表,然后向其中插入五个任意的人员:
-- create_dbpersons.sql
-- Recreates the [dbpersons] database used by the chapter "Accessing MySQL with the
-- native [mysql2] driver", with arbitrary data (the originals of the 2020
-- Python/Flask course being no longer available).
--
-- Usage:
-- mysql -u root -p < create_dbpersons.sql
--
-- Creates the database, the application user [admpersons/nobody] (same
-- credentials as the original course) and the [persons] table.
DROP DATABASE IF EXISTS dbpersons;
CREATE DATABASE dbpersons CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER IF NOT EXISTS 'admpersons'@'localhost' IDENTIFIED BY 'nobody';
GRANT ALL PRIVILEGES ON dbpersons.* TO 'admpersons'@'localhost';
FLUSH PRIVILEGES;
USE dbpersons;
CREATE TABLE persons (
id INT PRIMARY KEY,
first_name VARCHAR(30) NOT NULL,
last_name VARCHAR(30) NOT NULL,
age INTEGER NOT NULL,
UNIQUE (last_name, first_name)
);
-- arbitrary data (same persons as the examples of the original course)
INSERT INTO persons (id, first_name, last_name, age) VALUES
(1, 'Paul', 'Langevin', 48),
(2, 'Sylvie', 'Lefur', 70),
(3, 'Pierre', 'Nicazou', 35),
(4, 'Geraldine','Colou', 26),
(5, 'Paulette', 'Girond', 56);
要创建此数据库(MySQL),可以使用 Laragon 的 [HeidiSQL] 工具。我们之前已经用过它。
![]() |
- 在 [1] 中,启动 Laragon 的所有服务。这将启动 MySQL 数据库管理系统;
- 在 [2] 中,进入 [HeidiSQL] 数据库管理工具;
![]() |
- 在 [1-2] 中,登录 MySQL;
![]() |
通过 [1-2],依次运行项目中的两个 SQL 文件:

仍在 [HeidiSQL] 中,按 F5 刷新显示:
![]() |
现在我们可以使用这两个数据库了。
7.1.2. [mysql_01] 脚本
我们来说明这段代码:
- 第 19 行:[import 'package:mysql_client_plus/mysql_client_plus.dart';]:全新的、完全用 Dart 编写的 MySQL 驱动,用来取代 [package:mysql1]——后者与 MySQL 8.4(Laragon 自带)不兼容:即使是“select 1”这样简单的查询也始终失败,并报告协议错误“Got packets out of order”,这是该包中一个已知且尚未解决的缺陷(参见文件顶部的注释)。
- 第 34 行:[MySQLConnection? connection;]:可空(NULLABLE)字段,其作用与 TypeScript 的联合类型 [MySqlConnection | undefined] 完全相同——[null] 表示“尚未连接”,就像 TS 中的 [undefined] 一样。
- 第 47–55 行:[final newConnection = await MySQLConnection.createConnection(...); await newConnection.connect(); connection = newConnection;]:[mysql_client_plus] 把连接对象的创建([createConnection],此时尚未产生任何网络交互)与连接的实际建立([connect],与服务器协商协议)分开——这是两个不同的阶段,而 [mysql1](与 TypeScript 一侧的 [mysql2] 一样)把它们合并为一次调用。[connection]([finally] 中使用的可空变量)只有在 [connect] 成功之后才会被赋值,这样 [finally] 就绝不会关闭一个从未真正打开的连接。
- [try] / [catch] / [finally]:结构与前一版本相同——无论是否发生错误,连接总是在 [finally] 中关闭。
执行结果如下:
7.1.3. [mysql_02] 脚本
我们来说明这段代码:
- 第 10–36 行:[Future<void> connect(String host, int port, String database, String login, String pwd) async { ... }]:连接被封装在一个可复用的函数中,该函数在失败时抛出异常,而不是自己捕获——如何处理由调用者决定。它复用了 [mysql_01.dart] 中的“创建 + [connect()]”模式:[cnx] 只有在 [connect] 成功之后才会被赋值。
- 第 43 行:[const int port = 3306;]:[mysql_client_plus] 要求显式指定端口([createConnection]),而 [mysql1] 的 [ConnectionSettings] 会自行推断默认端口(3306)。
- [main] 在两个独立的 [try] 和 [catch] 块中调用此函数两次:一次使用有效的标识,一次使用无效的标识,以演示两种路径。
执行结果如下:
7.1.4. 脚本 [mysql_03]
我们来说明这段代码:
- 第 10–12 行:[Future<void> executeSql(MySQLConnection connection, String query) async { await connection.execute(query); }]:一个执行 SQL 更新命令的工具函数(此处是 DROP TABLE 后接 CREATE TABLE)——[connection.execute(...)] 取代了 [mysql1] 的 [connection.query(...)](作用相同,只是在 [mysql_client_plus] 一侧方法名称变了)。
- 第 41 行:[exit(1);](来自 [dart:io]):等价于 [process.exit(1)]——语义相同,连接失败时的进程退出码也相同。
- 第 47 行:[try { await executeSql(connection, 'drop table persons'); } catch (_) {}]:把 [_] 作为参数传给 [catch],表示忽略异常值——因为该表可能根本还不存在。
执行结果如下:
7.1.5. 脚本 [config_04]
我们来分析这段代码:
- 第 43 行:[Platform.script.resolve('data/commands.sql').toFilePath()](来自 [dart:io]):相当于 TypeScript 中 [dirname(fileURLToPath(import.meta.url))] 的更直接、更简短的写法——[Platform.script] 本身已经是当前运行脚本的 URI,只需在其中解析一个相对路径即可。
- 重要说明:[Platform.script] 指的是由 [dart run] 启动的主(MAIN)脚本(这里是 [mysql_04.dart]),而不一定是编写该表达式的文件——这一点与 [import.meta.url] 不同,后者对每个文件都是唯一的。由于 [config_04.dart] 和 [mysql_04.dart] 位于同一文件夹,这里的结果仍然正确。
- 第 18–28 行:[class Config { final String commandsFilename; ...; final int port; ...; const Config({required this... }); }]:一个用于组织配置的不可变类,类似于 TypeScript 版本的 [Config] 接口——另外多了一个 [port] 字段,这是 [MySQLConnection.createConnection] 明确要求的(而 [mysql1] 的 [ConnectionSettings] 会自动推断默认端口 3306)。
7.1.6. 脚本 [mysql_module]
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 | |
我们来说明这段代码:
- 第 20 行:[void _displayInfo(IResultSet results)]:区分 SELECT([results.cols] 描述所请求的列)与更新语句([results.affectedRows],相当于游标的 [rowcount])——[results.cols]/[results.rows] 取代了 [mysql1] 的 [results.fields],[row.colByName(t)] 取代了 [row.fields[t]] 这种写法。
- 第 61–67 行:[Future<List<String>> executeListOfCommands(MySQLConnection connection, List<String> sqlCommands, {bool verbose = false, bool stop = true, bool withTransaction = true}) async { ... }]:带默认值的命名参数(NAMED PARAMETERS),与 [mysql1] 版本相比没有变化——完全类似于 TypeScript 配置对象的可选参数。
- 第 74–108 行:[Future<void> executeCommands(MySQLConnection cnx) async { ... }]:一个(嵌套的)局部(LOCAL)函数,既用于“带事务”的情形(此时它接收 [transactional] 传给其回调的工作连接),也用于“不带事务”的情形(此时它直接接收 [connection])——这样,命令执行循环只需写一次。在带事务的情形下,触发 ROLLBACK 的是重新抛出的异常(EXCEPTION,[rethrow]),而不是像 [mysql1] 版本中手动 ROLLBACK 时那样简单地结束循环。
- 第 110–118 行:[if (withTransaction) { try { await connection.transactional((cnx) => executeCommands(cnx)); } catch (_) { ... } }]:[mysql2] 直接提供 [connection.beginTransaction()]/[commit()]/[rollback()]。[package:mysql1] 没有逐一提供这些方法:必须自己发送 SQL 命令 [START TRANSACTION]、[COMMIT] 和 [ROLLBACK],“手动”控制事务。[package:mysql_client_plus] 终于提供了 [mysql2] 的直接等价物:[connection.transactional((cnx) async { ... })] 在事务中执行回调,正常完成时自动提交(COMMIT),抛出异常时自动回滚(ROLLBACK)——不再需要自己编写 SQL 事务控制语句。
- 第 128–134 行:[Future<List<String>> executeFileOfCommands(...) async { ... }]:读取文件([File(sqlFilename).readAsString()]),然后委托给 [executeListOfCommands]——与 [mysql1] 版本相比没有变化,结构与 TypeScript 中相同。
7.1.7. 脚本 [mysql_04]
这个主脚本协调前面的两个脚本来执行文件 [data/commands.sql](与 TypeScript 课程中的相同),是否使用事务取决于提供的命令行参数。
我们来说明这段代码:
- 第 14–28 行:[Future<void> main(List<String> arguments) async { ... }]:[arguments] 接收命令行参数,就像 Node 一侧的 [process.argv.slice(2)]——这里只期望一个参数:[true] 或 [false]。
- 第 45–53 行:[final newConnection = await MySQLConnection.createConnection(...); await newConnection.connect(); connection = newConnection;]:连接使用与 [connect()] 相同的创建模式,如 [mysql_01.dart] 中所示,参数取自 [config](包括新增的字段 [port])。
- 第 55–61 行:[executeFileOfCommands(connection, config.commandsFilename, verbose: true, stop: false, withTransaction: withTransaction)]:执行 [data/commands.sql],是否使用事务取决于参数——[dart run mysql_04.dart true] 或 [dart run mysql_04.dart false]。
下面是两种可能的执行情况:
7.1.8. 脚本 [mysql_05]
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 | |
我们来说明这段代码:
- 第 25 行:[typedef Person = (int id, String lastName, String firstName, int age);]:TypeScript 中的元组,命名为 [type Person = [id: number, lastName: string, firstName: string, age: number]](运行时只是一个简单数组),在 Dart 3 中变为位置记录(POSITIONAL RECORD)——它本身就是一个完整的类型,与 [List] 不同。
- 第 75–80 行:[for (final (idP, lastName, firstName, age) in persons) { await connection.execute('insert into persons(id,last_name,first_name,age) values(:id,:last_name,:first_name,:age)', {'id': idP, 'last_name': lastName, 'first_name': firstName, 'age': age}); }]:每条预处理插入语句都在 [for] 头部直接解构位置记录(参见“Dart 3.x 的新特性”一章)——使用与 [Map] 关联的命名(NAMED)占位符([:id]、[:last_name]……),而不是 [mysql1] 和 [mysql2] 的位置(POSITIONAL)占位符([?] 加值列表)。
- 第 90–99 行:[final placeholderGroups = <String>[]; final values = <String, Object?>{}; for (...) { placeholderGroups.add('(:id$i,:last_name$i,:first_name$i,:age$i)'); ... }]:[mysql2] 直接支持通过数组的数组进行批量插入([values ?] 配合 [[[...],[...]]])。[package:mysql_client_plus] 没有这样的等价物(与之前的 [mysql1] 一样):因此必须自己构造 SQL 文本,但每一行使用一组带名称且带编号的(NAMED 且 NUMBERED)占位符([:id0]、[:last_name0]……[:id1]、[:last_name1]……),因为命名占位符不能在同一个请求中重复使用——与 TypeScript 版本一样,只需一次网络往返。
- 第 93 行:[final (idP, lastName, firstName, age) = otherPersons[i];]:这里再次使用位置记录的解构——需要根据记录的四个字段为每个占位符([:id0]、[:last_name0]……)单独命名,因为 [mysql_client_plus] 不像此脚本前一版本中使用的 [p.$1, p.$2...] 那样提供直接的位置访问。
执行结果如下:
可以使用 Laragon 的 HeidiSQL 验证结果:

7.1.9. 结论
原生驱动的移植忠实于原来的 TypeScript 版本。在最初尝试 [package:mysql1]——因与 MySQL 8.4 不兼容而被放弃——之后,[package:mysql_client_plus] 最终提供了比 [mysql1] 更接近 [mysql2] 的 API:[connection.transactional(...)] 直接等价于 [beginTransaction()]/[commit()]/[rollback()],而 [mysql1] 则需要使用 SQL 命令 [START TRANSACTION]、[COMMIT] 和 [ROLLBACK] 手动管理事务。还有一个差异依然存在,尽管更为细微:DECIMAL 列([dbschool] 数据库中的 [subjects.coefficient]、[grades.value])需要借助一个小的辅助函数 [_decimal]([typedColByName<String>(...)] 然后 [num.parse(...)])进行显式转换,因为驱动不支持把此 SQL 类型直接转换为 [num] 或 [double]。
7.2. 轻量级 ORM

TypeScript 课程用两个独立的章节讲解通过 ORM([Object-Relational Mapping],对象关系映射)访问数据库:先是 [TypeORM],然后是 [Prisma],使用同一个示例模式。两者基于一个共同的原理:先一次性描述模式(TypeORM 在类上使用装饰器,Prisma 则使用 [.prisma] 文件),然后让工具在启动时或编译期间生成所有把对象的读写转换为 SQL 的代码——包括表之间关系的加载。
Dart 没有成熟且被广泛采用的、可用于 MySQL 的这两个工具的等价物:虽然存在 Dart 的 ORM 库,但它们主要面向 Flutter/SQLite([Drift]、[Floor])或其他不同的架构——Prisma 本身也不提供 Dart 客户端。我们不去强行建立“某某 Dart 包 = TypeORM”或“某某包 = Prisma”这样的人为对应,而是采用一种不同的、教学上更合理的方式:通过亲自编写一个刻意保持精简的版本,来展示 ORM 究竟做了什么——因此得名 [light ORM]。
7.2.1. 实体:[entities.dart] 文件
我们来说明这段代码:
- TypeORM 的实体是普通的带装饰器(DECORATED)的类([@Entity]、[@Column]、[@ManyToOne]……):是 TypeORM 在启动时读取这些装饰器(一种反射),以确定如何用 SQL 读写每个字段,并按需加载关系。Dart 在这里没有可用的等价反射机制([dart:mirrors] 在 Web 编译/AOT 中已被弃用):因此这些类只是可变的“字段袋”,不带任何注解。
- 第 29 行:[class SchoolClass { ...; List<Student> students = []; }]、[class Student { ...; SchoolClass? schoolClass; List<Grade> grades = []; }](第 43 行):关系只是简单字段(空集合或可空引用),永远不会被自动加载——扮演 TypeORM 中反射所起作用的,是手工编写的 [repository.dart]。
7.2.2. 泛型仓库:[repository.dart] 文件
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 | |
我们来说明这段代码:
- 第 20–33 行:[class Repository<T> { ...; final T Function(ResultSetRow row) fromRow; final Map<String, Object?> Function(T entity) toColumns; final Object? Function(T entity) key; ... }]:一个泛型(GENERIC)类,由实体类型 [T] 进行配置,围绕调用者提供的三个函数(THREE FUNCTIONS)构建——如何读取一行 SQL、如何写入,以及主键是什么。这就是“对象关系映射”的全部,精简到了最核心的部分;与 [mysql1] 版本相比,只有第一个函数的类型发生了变化(用 [ResultSetRow] 代替 [ResultRow])。
- 第 57 行:[final where = conditions.keys.map((c) => '$c = :$c').join(' and ');]:[conditions] 的键既是 SQL 的列名,又是命名占位符(NAMED PLACEHOLDER,[:column])的名称——与使用位置占位符([?] 加按顺序排列的值列表 LIST)的 [mysql1] 不同,[mysql_client_plus] 需要一个 [Map](占位符名称 → 值),这正好很合适,因为此仓库本来就用 [Map<String, Object?>] 处理列。
- 第 45–63 行:[Future<List<T>> findAll({String? orderBy}) async { ... }]、[Future<T?> findOneBy(Map<String, Object?> conditions) async { ... }]:直接等价于 TypeORM 的 [repo.find(...)] 和 [repo.findOneBy(...)]——[execute()] 取代了 [query()],[results.rows] 包含结果行(而不是 [mysql1] 直接返回的列表)。
- 第 78–96 行:[Future<void> save(T entity) async { ...; final alreadyExists = await findOneBy(...) != null; if (alreadyExists) { ... update ... } else { ... insert ... } }]:[repo.save(...)] 的“upsert”行为——主键尚不存在则插入,否则更新——与 [mysql1] 版本相比保持不变,只是占位符的风格不同。
7.2.3. 脚本 [orm_01_persons]
我们来说明这段代码:
- 第 24–42 行:[final repo = Repository<Person>(connection, table: 'persons', keyColumn: 'id', fromRow: (row) => Person(...), toColumns: (p) => {...}, key: (p) => p.id);]:为 [Person] 实体构建一个仓库,并向其提供所期望的三个函数——这是文件中唯一“了解”SQL 列细节的地方。[mysql1] 已经把每一列解码为所期望的 Dart 原生类型([row.fields['id'] as int] 可直接使用);[mysql_client_plus] 则要求按列进行显式的类型化(TYPED)访问——[typedColByName<T>(name)]——由它自己处理转换。
- 脚本的其余部分([repo.findAll]、[repo.findOneBy]、[repo.save]、[repo.delete])不再包含任何 SQL 行——与 TypeORM 日常提供的体验完全相同,不因迁移而改变。
执行结果如下:
7.2.4. 脚本 [orm_02_school]
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 | |
我们来分析这段代码:
- 第 10–17 行:[num _decimal(ResultSetRow row, String column) => num.parse(row.typedColByName<String>(column)!);]:[mysql_client_plus] 可以把 SQL 的 DECIMAL 列(此处是 [subjects.coefficient])转换为 [String](任何 SQL 类型都可以按 [String] 读取),但无法把它直接转换为 [num] 或 [double]——[typedColByName<num>(...)] 随后会产生 [MySQLProtocolException: Cannot convert MySQL type 246 to requested type num](246 = NEWDECIMAL,即 MySQL 中 DECIMAL 列的内部类型)。因此该列先按 [String] 读取,再手动转换。
- 三个私有函数——[_classRepo]、[_studentRepo] 和 [_subjectRepo]——各自为 [dbschool] 中三个实体之一构建一个 [Repository];只有 [_subjectRepo] 对 [coefficient] 列使用了 [_decimal]。
- 第 99–100 行:[final reread = await studentRepo.findOneByOrFail({'id': 999}); reread.schoolClass = await classRepo.findOneByOrFail({'id': reread.classId});]:[typeorm-02.ts] 通过指定 [relations: { schoolClass: true }] 来在加载学生的同时加载关联的班级,而 [Repository.findOneBy] 只能从 [students] 表加载(没有自动连接)——因此我们自己通过第二次显式查询来获取班级:这正是 TypeORM 在幕后触发的那次额外查询,只不过在这里变得可见(VISIBLE)了。
执行结果如下:
7.2.5. 脚本 [orm_03_joined_queries]
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 | |
我们来分析这段代码:
- 与 [orm_02_school.dart](两个独立的请求)不同,这个文件编写的是真正的 SQL 连接——这正是 TypeORM 通过 [relations] 选项在幕后所做的事情,只是在这里完全可见。
- 第 44–61 行:[from students s join classes c on s.class_id = c.id where s.id = :id]、[from classes c left join students s on s.class_id = c.id where c.id = :id]:JOIN(必需的关系)和 LEFT JOIN(可选的关系;一个班级可以没有学生)——TypeORM 会根据所声明的关系可选性替你选择其中之一。[mysql1] 的位置占位符([?])变成命名占位符([:id]),对一行中各列的访问([mysql1] 中的 [row['x']] 或 [row.fields['x']])变成类型化调用([row.typedColByName<T>('x')])。
- 第 135 行:[value: _decimal(row, 'g_value')]、[coefficient: _decimal(row, 'sub_coefficient')]:与 [orm_02_school.dart] 中相同的辅助函数 [_decimal],这里的两个 DECIMAL 列 [grades.value] 和 [subjects.coefficient] 需要它。
- TypeORM(与 SQLAlchemy 一样)默认不会对“标准”实体执行懒加载:必须使用 [relations] 选项显式请求关系。轻量级 ORM 把这一原则推得更远,因为这里根本没有懒加载——没有“神奇的”关系加载:每个连接都是手工编写的——这是不依赖任何对象关系映射库所要付出的代价。
执行结果如下:
7.2.6. [orm_04_stats] 脚本
我们来说明这段代码:
- [typeorm-04-stats.ts] 指出,MySQL 的 [decimal] 列(此处是 [grade.value] 和 [subject.coefficient])在运行时被 [mysql2] 以字符串(CHARACTER STRINGS)形式返回(以避免丢失精度),尽管其声明的类型是 [number]——这是 TypeScript 的一个经典陷阱:静态类型可能并不反映运行时的实际值。
- 第 26 行:[num _decimal(ResultSetRow row, String column) => num.parse(row.typedColByName<String>(column)!);]:在 Dart 一侧,[package:mysql_client_plus] 存在与 TypeScript 类似的陷阱,但它由编译器变得可见(VISIBLE),而不是在运行时被隐藏:类型化访问([typedColByName<T>(...)])无法把 DECIMAL 列转换为 [num] 或 [double]——它会抛出 [MySQLProtocolException: Cannot convert MySQL type 246 to requested type num]。对任何 SQL 类型唯一有保证的转换是转为 [String];因此标记为 DECIMAL 的列先按 [String] 读取,再手动用 [num.parse] 转换。
- 第 67 行:[final average = weightedSum / coefficientsSum;]:加权平均值的计算本身与 TypeScript 版本和 [mysql1] 版本完全相同——只有 DECIMAL 列的读取(READING)发生了变化。
执行结果如下:
7.2.7. 轻量级 ORM 不做的事情
与 TypeORM/Prisma 不同:没有模式生成([synchronize]/迁移),没有装饰器,没有懒加载或标识缓存,没有查询构建器([QueryBuilder]),而且加载关系始终是(ALWAYS)第二次查询或手工编写的连接——绝不会自动进行。这是一种刻意的折衷:足以借助课程中的示例来说明仓库模式,而不妄称可以在生产环境中取代真正的仓库。



