应用开发者指南

本指南面向使用 MatrixOne 构建应用的开发者,按 v4.2.5 的接口组织从连接到上线的路径。源码贡献者使用贡献指南。

第一条应用链路

  1. 在独立实例记录实际版本、连接信息和账户,不把 root 口令写进应用仓库。

  2. 选用客户端与驱动,验证参数绑定、连接池、会话时区、Decimal/UInt64/JSON/二进制的往返结果。

  3. 按建模指南设计主键、约束、类型和索引,以真实数据分布检查查询。

  4. 明确事务成功、语句失败、整事务中止和提交结果未知的处理;设计幂等键、超时与重试,不仅捕获消息字符串。

  5. 增加查询/检索与外部数据,保留结果基线和真实路径,再扩大规模。

从教程到真实应用

阶段

入口

完成标准

连接与 CRUD

Java/Python/Go 等教程与驱动

真实驱动读写、参数绑定、提交/回滚

事务建模

事务

并发、错误范围、幂等与失败恢复

SQL 分析

JOIN、EXPLAIN

结果一致、计划与真实数据规模

AI 检索与版本工作区

RAG、分支

模型/Embedding 来源、检索质量、权限/变更审查

GIS

空间类型与函数

SRID、单位、边界点、客户端表示

工具和摄取

生态入口、CDC

插入/更新/删除、Schema、checkpoint 与目标提交

上线与恢复

安全、备份

最小权限、TLS、容量、监控、独立恢复验收

生产前检查

固定服务端/驱动/连接器/Operator 版本及开关。MySQL 接入兼容范围按兼容页逐项检查,包括 ORM 反射、生成 DDL、事务、时区和返回类型。连接成功不认证 binlog 源或所有生态操作。

查询优化先看正确结果、数据粒度和计划,再看扫描、连接分布、内存/Spill、缓存与 I/O。性能报告记录数据、硬件、并发、运行时间和错误率。

单机示例完成后,在目标拓扑验证断线、取消、节点重启和恢复。外部文件、模型服务及目标 connector 的副作用不自动由数据库事务回滚。部署和备份工具是独立版本,恢复需要真实演练。

驱动字符集与返回值探针

握手字符集与返回列元数据需要分别验证。2026-10-14 在 v4.2.5 和 mysql2 3.22.6 的最小查询中,空间😀 返回为 空间����,列字符集标记为 33,但服务端 HEX 值是正确 UTF-8 字节;PyMySQL 的 utf8mb4 路径能回读原值。这个记录只覆盖上述组合。

SELECT HEX('空间😀') AS utf8_bytes;

预期为 E7A9BAE997B4F09F9880。应用还应使用真实驱动查询原字符串并逐字符比较,同时保存字段元数据。为握手设置支持的 collation 不会自动纠正列解码。需要非 BMP 字符的应用应把该组合列为待修复/需适配验证项,并独立验证表示转换路径;不能仅以连接成功判定兼容。