5.2 KiB
MySQL 5.7 字符集与兼容性基线设计规格
- 功能编号：GOV-005
- 规格版本：0.1
- 状态：approved_for_review
- 日期：2026-08-13
背景与目标
系统架构和开发规范已经选择 MySQL，但尚未固定服务端版本、字符集和排序规则。不同开发环境如果分别使用 MySQL 5.7、8.x 或不同排序规则，会造成迁移语法、索引行为、字符串比较和排序结果不一致。
本功能建立项目级数据库兼容性基线：所有正式实现固定使用 MySQL 5.7.x，字符集固定为 utf8mb4，排序规则固定为 utf8mb4_general_ci。虽然市场概览第一阶段只定义持久化接口、不启用 MySQL，该约束仍从数据模型设计开始生效。
约束方案
采用方案：全链路显式声明
数据库实例/Schema、连接会话、迁移脚本、表、需要覆盖默认值的文本列，以及 Docker、测试和 CI 环境都显式声明或验证版本和字符集规则。
采用原因：只设置服务器默认值无法防止迁移脚本、ORM 连接或外部工具创建出不同排序规则的对象。全链路显式声明能够在代码审查和自动测试中直接验证。
不采用：仅依赖服务器默认值
部署配置简单，但开发机、测试环境或后续迁移工具可能使用不同默认值，无法保证可复现，不采用。
不采用：允许 MySQL 8.x 向下兼容
在 8.x 开发、声称兼容 5.7，容易无意引入 CTE、窗口函数、函数索引和 8.x 行为差异。项目明确要求不使用 8.x，因此不采用。
技术基线
- 数据库服务端：MySQL
5.7.x，部署镜像和测试环境必须固定到明确的 5.7 补丁版本；禁止latest、8或8.x。 - 默认字符集：
utf8mb4。 - 默认排序规则：
utf8mb4_general_ci。 - 数据库创建语句必须包含
DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci。 - 表创建或迁移必须显式保持
DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci。 - ORM/数据库驱动连接配置必须设置
charset=utf8mb4，连接建立后验证会话排序规则为utf8mb4_general_ci，不能假设服务器默认值正确。 - 文本列原则上继承表级规则；只有确实需要不同比较语义时才允许列级覆盖，并必须另建 ADR 获得批准。
MySQL 5.7 兼容边界
代码、查询、迁移和测试不得使用仅在 MySQL 8.x 可用或行为不同的能力，包括但不限于：
- 公用表表达式
WITH和递归 CTE。 - 窗口函数，例如
ROW_NUMBER()、RANK()和OVER (...)。 - 函数索引和不可见索引。
CHECK约束在 8.x 的强制执行语义；5.7 中业务约束必须由应用校验、普通索引或可验证的数据写入逻辑保证。utf8mb4_0900_*排序规则。- 依赖 MySQL 8.x 默认认证插件、保留字、数据字典或 JSON 增强能力的实现。
JSON 字段只有在需求能够由 MySQL 5.7 原生 JSON 能力稳定完成时才能使用；查询和索引设计必须有 5.7 实际测试证据。
排序规则语义
utf8mb4_general_ci 为不区分大小写的通用排序规则。业务代码不得把数据库字符串比较误认为大小写敏感；证券代码、外部事件 ID、幂等键等需要严格身份语义的字段，应通过规范化输入、二进制字段/排序规则或明确的唯一键设计解决，并在具体功能设计中说明。
索引长度必须按 MySQL 5.7、utf8mb4 最多四字节字符进行预算。迁移设计不得假设 MySQL 8.x 的默认索引能力；超长文本标识应使用长度受控字段、前缀索引或稳定摘要，并提供碰撞与唯一性处理说明。
配置落点
docs/architecture/system-architecture.md：记录数据库技术基线、第一阶段接口边界和未来启用条件。docs/governance/code-development-standards.md：把版本、字符集、排序规则、禁用能力、迁移和 Review 检查设为强制规范。- 后续
deploy/：MySQL 镜像固定 5.7 补丁版本，初始化参数显式声明字符集和排序规则。 - 后续
server/：ORM 与连接配置、迁移、Repository 实现按本规格验证。 - 后续测试：连接真实 MySQL 5.7 检查
SELECT VERSION()、数据库/表排序规则和查询兼容性。
实施范围
本功能只更新架构、开发规范、版本记录和 GOV-005 追溯档案，不创建数据库、不启动容器、不引入 ORM，也不启用市场概览的 MySQL Repository。正式部署配置和代码实现由后续业务功能按照本基线完成。
验收标准
- 系统架构明确 MySQL 5.7.x、
utf8mb4和utf8mb4_general_ci。 - 开发规范明确数据库、表、连接、迁移、测试和 Review 的全链路要求。
- 开发规范明确禁止依赖 MySQL 8.x 专属能力和
utf8mb4_0900_*排序规则。 - 文档说明
utf8mb4_general_ci不区分大小写及对身份字段、唯一键和索引长度的影响。 - 市场概览第一阶段仍只定义 MySQL Repository 接口，不实际启用数据库。
- GOV-005 具备 PRD、需求、设计、实施计划、测试、GitNexus 前后对比、双 Review、发布和回退档案。
- 治理测试、文档一致性检查、敏感信息检查和 GitNexus 变更检测通过。
- 中文提交和
v0.0.4标签均精确推送到 Gitea。