FoXiMao/a-share-analysis
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(GOV-007): 建立开发库 Schema 基线门禁

Browse Source
This commit is contained in:
FoXiMao
2026-08-13 12:50:37 +08:00
parent 2c502ebbec
commit da056681b6
30 changed files with 1734 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/database/fixtures/mysql57-schema-expected.sql
+18
View File
@@ -0,0 +1,18 @@
/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;
CREATE TABLE `market_snapshot` (
`id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
`trade_date` date NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
/*!50001 DROP VIEW IF EXISTS `active_market_snapshot`*/;
/*!50001 CREATE ALGORITHM=UNDEFINED */
/*!50013 SQL SECURITY DEFINER */
/*!50001 VIEW `active_market_snapshot` AS select `market_snapshot`.`id` AS `id` from `market_snapshot` */;
DELIMITER ;;
/*!50003 CREATE*/ /*!50003 TRIGGER `market_snapshot_before_insert` BEFORE INSERT ON `market_snapshot` FOR EACH ROW SET NEW.trade_date = COALESCE(NEW.trade_date, CURRENT_DATE) */;;
/*!50003 CREATE*/ /*!50003 PROCEDURE `refresh_market_snapshot`() BEGIN SELECT COUNT(*) FROM market_snapshot; END */;;
/*!50106 CREATE*/ /*!50106 EVENT `purge_market_snapshot` ON SCHEDULE EVERY 1 DAY DO DELETE FROM market_snapshot WHERE trade_date < CURRENT_DATE - INTERVAL 365 DAY */;;
DELIMITER ;
tools/database/fixtures/mysql57-schema-input.sql
+26
View File
@@ -0,0 +1,26 @@
-- MySQL dump 10.13 Distrib 5.7.44, for Linux (x86_64)
--
-- Host: 127.0.0.1 Database: a_share_analysis_dev
-- ------------------------------------------------------
-- Server version 5.7.44-log
/*!40101 SET @OLD_CHARACTER_SET_CLIENT=@@CHARACTER_SET_CLIENT */;
CREATE TABLE `market_snapshot` (
`id` bigint(20) unsigned NOT NULL AUTO_INCREMENT,
`trade_date` date NOT NULL,
PRIMARY KEY (`id`)
) ENGINE=InnoDB AUTO_INCREMENT=128 DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_general_ci;
/*!50001 DROP VIEW IF EXISTS `active_market_snapshot`*/;
/*!50001 CREATE ALGORITHM=UNDEFINED */
/*!50013 DEFINER=`dev_reader`@`127.0.0.1` SQL SECURITY DEFINER */
/*!50001 VIEW `active_market_snapshot` AS select `market_snapshot`.`id` AS `id` from `market_snapshot` */;
DELIMITER ;;
/*!50003 CREATE*/ /*!50017 DEFINER=`dev_reader`@`127.0.0.1`*/ /*!50003 TRIGGER `market_snapshot_before_insert` BEFORE INSERT ON `market_snapshot` FOR EACH ROW SET NEW.trade_date = COALESCE(NEW.trade_date, CURRENT_DATE) */;;
/*!50003 CREATE*/ /*!50020 DEFINER=`dev_reader`@`127.0.0.1`*/ /*!50003 PROCEDURE `refresh_market_snapshot`() BEGIN SELECT COUNT(*) FROM market_snapshot; END */;;
/*!50106 CREATE*/ /*!50117 DEFINER=`dev_reader`@`127.0.0.1`*/ /*!50106 EVENT `purge_market_snapshot` ON SCHEDULE EVERY 1 DAY DO DELETE FROM market_snapshot WHERE trade_date < CURRENT_DATE - INTERVAL 365 DAY */;;
DELIMITER ;
-- Dump completed on 2026-08-13 11:00:00
tools/database/schema-baseline.mjs
+739
View File
@@ -0,0 +1,739 @@
import { execFileSync } from 'node:child_process';
import {
existsSync,
mkdirSync,
readFileSync,
readdirSync,
renameSync,
rmSync,
writeFileSync,
} from 'node:fs';
import { createHash } from 'node:crypto';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
const DEVELOPMENT_DATABASE = 'a_share_analysis_dev';
const REQUIRED_CHARSET = 'utf8mb4';
const REQUIRED_COLLATION = 'utf8mb4_general_ci';
const BASELINE_FORMAT_VERSION = 1;
const TOOL_VERSION = '1.0.0';
const VERSION_PATTERN = /^v\d+\.\d+\.\d+$/;
const DEVELOPMENT_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
const OBJECT_KEYS = Object.freeze(['tables', 'views', 'triggers', 'routines', 'events']);
const CAPTURED_FILES = Object.freeze(['checksum.sha256', 'manifest.yaml', 'schema.sql']);
const NOT_APPLICABLE_FILES = Object.freeze(['manifest.yaml']);
function requireExactValue(actual, expected, message) {
if (actual !== expected) {
throw new Error(`${message}，要求 ${expected}，实际 ${actual || '(空)'}`);
}
}
function isEnabled(value) {
return value === true || value === 'true';
}
/**
* Schema 工具拥有比普通应用启动更窄的权限边界：即使连接地址看起来是本机，
* 环境名和数据库名也必须同时命中固定开发值，避免通过参数误切到生产库。
*/
export function assertSafeDevelopmentConfiguration(config) {
requireExactValue(config.APP_ENV, 'development', 'Schema 基线只允许 development 环境');
requireExactValue(
config.MYSQL_DATABASE,
DEVELOPMENT_DATABASE,
'Schema 基线只允许固定开发库 a_share_analysis_dev',
);
requireExactValue(config.MYSQL_CHARSET, REQUIRED_CHARSET, '数据库字符集不符合要求');
requireExactValue(
config.MYSQL_COLLATION,
REQUIRED_COLLATION,
'数据库排序规则不符合要求',
);
if (isEnabled(config.MYSQL_ENABLED)) {
if (!DEVELOPMENT_HOSTS.has(config.MYSQL_HOST)) {
throw new Error(
`Schema 基线只允许通过开发机回环地址连接，实际 ${config.MYSQL_HOST || '(空)'}；远程开发库必须先建立本地 SSH 隧道`,
);
}
for (const key of ['MYSQL_HOST', 'MYSQL_PORT', 'MYSQL_USERNAME', 'MYSQL_PASSWORD']) {
if (!String(config[key] ?? '').trim()) {
throw new Error(`MySQL 已启用，${key} 不能为空`);
}
}
} else if (config.MYSQL_ENABLED !== false && config.MYSQL_ENABLED !== 'false') {
throw new Error('MYSQL_ENABLED 必须显式为 true 或 false');
}
return Object.freeze({ ...config, MYSQL_ENABLED: isEnabled(config.MYSQL_ENABLED) });
}
/**
* 客户端与服务端分别校验，防止用 MySQL 8 客户端生成带有 5.7 无法稳定恢复的语法，
* 同时核对数据库自身字符规则，而不是信任 env 中的声明值。
*/
export function assertMysql57Metadata(metadata) {
if (!/^5\.7\.\d+(?:[-+].*)?$/.test(metadata.mysqlClientVersion ?? '')) {
throw new Error(`mysql 客户端必须为 5.7.x，实际 ${metadata.mysqlClientVersion || '(空)'}`);
}
if (!/^5\.7\.\d+(?:[-+].*)?$/.test(metadata.mysqldumpClientVersion ?? '')) {
throw new Error(
`mysqldump 客户端必须为 5.7.x，实际 ${metadata.mysqldumpClientVersion || '(空)'}`,
);
}
if (!/^5\.7\.\d+(?:[-+].*)?$/.test(metadata.serverVersion ?? '')) {
throw new Error(`MySQL 服务端必须为 5.7.x，实际 ${metadata.serverVersion || '(空)'}`);
}
requireExactValue(metadata.databaseCharset, REQUIRED_CHARSET, '开发数据库字符集不符合要求');
requireExactValue(
metadata.databaseCollation,
REQUIRED_COLLATION,
'开发数据库排序规则不符合要求',
);
return metadata;
}
export function buildMysqldumpArguments(config) {
assertSafeDevelopmentConfiguration(config);
return [
`--host=${config.MYSQL_HOST}`,
`--port=${config.MYSQL_PORT}`,
`--user=${config.MYSQL_USERNAME}`,
`--default-character-set=${REQUIRED_CHARSET}`,
'--no-data',
'--routines',
'--triggers',
'--events',
'--single-transaction',
'--skip-lock-tables',
'--skip-comments',
DEVELOPMENT_DATABASE,
];
}
function buildMysqlMetadataArguments(config) {
return [
`--host=${config.MYSQL_HOST}`,
`--port=${config.MYSQL_PORT}`,
`--user=${config.MYSQL_USERNAME}`,
`--default-character-set=${REQUIRED_CHARSET}`,
'--batch',
'--skip-column-names',
DEVELOPMENT_DATABASE,
'--execute=SELECT VERSION(), DEFAULT_CHARACTER_SET_NAME, DEFAULT_COLLATION_NAME FROM information_schema.SCHEMATA WHERE SCHEMA_NAME = DATABASE()',
];
}
function assertSchemaHasNoSensitiveOrDataStatements(sql) {
// 安全扫描只忽略 SQL 字符串字面量，标识符反引号仍参与检查。否则存储过程
// 合法返回“DEFINER=”等说明文字时会被误判，而真正的对象 DEFINER 仍可检出。
const sqlWithoutStringLiterals = sql.replace(/'(?:''|\\.|[^'\\])*'/gs, "''");
const prohibitedPatterns = [
[sqlWithoutStringLiterals, /\bDEFINER\s*=/i, 'DEFINER'],
[sql, /--\s*Dump completed on/i, '导出完成时间'],
[sql, /--\s*Host:/i, '连接主机注释'],
[sql, /\bpassword\s*=/i, '疑似密码'],
];
for (const [content, pattern, label] of prohibitedPatterns) {
if (pattern.test(content)) {
throw new Error(`Schema SQL 包含禁止内容：${label}`);
}
}
for (const statement of splitSqlStatements(sql)) {
let executableSql = statement
.replace(
/^(?:\s*--[^\n]*(?:\n|$)|\s*#[^\n]*(?:\n|$)|\s*\/\*(?!\!)[\s\S]*?\*\/\s*)+/g,
'',
)
.trim();
const candidates = [executableSql];
const executableComment = executableSql.match(/^\/\*!\d{5}\s+([\s\S]*?)\*\/\s*/);
if (executableComment) {
candidates.push(
executableComment[1].trim(),
executableSql.slice(executableComment[0].length).trim(),
);
}
const dataStatement = candidates.find((candidate) =>
/^(?:INSERT\s+INTO|REPLACE\s+INTO)\b/i.test(candidate),
);
if (dataStatement) {
throw new Error(
`Schema SQL 包含禁止的数据写入：${dataStatement.match(/^(?:INSERT\s+INTO|REPLACE\s+INTO)/i)[0]}`,
);
}
}
}
function findDelimiterOutsideStrings(content, delimiter) {
let quote = null;
let escaped = false;
for (let index = 0; index <= content.length - delimiter.length; index += 1) {
const character = content[index];
if (quote) {
if (escaped) {
escaped = false;
} else if (character === '\\') {
escaped = true;
} else if (character === quote) {
if (content[index + 1] === quote && quote !== '`') {
index += 1;
} else {
quote = null;
}
}
continue;
}
if (character === "'" || character === '"' || character === '`') {
quote = character;
continue;
}
if (content.startsWith(delimiter, index)) return index;
}
return -1;
}
/**
* mysqldump 用 DELIMITER 包住例程、触发器和事件。按真实分隔符切分后，
* 只有顶层以 INSERT/REPLACE 开头的语句代表数据；对象体内部 DML 必须保留。
*/
function splitSqlStatements(sql) {
const statements = [];
let delimiter = ';';
let buffer = '';
for (const line of String(sql).split(/(?<=\n)/)) {
const directive = line.trim().match(/^DELIMITER\s+(\S+)$/i);
if (directive) {
if (buffer.trim()) statements.push(buffer.trim());
buffer = '';
delimiter = directive[1];
continue;
}
buffer += line;
let delimiterIndex;
while ((delimiterIndex = findDelimiterOutsideStrings(buffer, delimiter)) >= 0) {
const statement = buffer.slice(0, delimiterIndex).trim();
if (statement) statements.push(statement);
buffer = buffer.slice(delimiterIndex + delimiter.length);
}
}
if (buffer.trim()) statements.push(buffer.trim());
return statements;
}
/**
* 规范化只删除 mysqldump 的环境噪声，不重排或重新格式化业务定义。
* 表选项中的当前 AUTO_INCREMENT 值会随数据增长变化；列定义的自增属性不匹配
* “等号加数字”的模式，因此会原样保留。
*/
export function normalizeSchemaSql(rawSql) {
const normalized = String(rawSql)
.replace(/\r\n?/g, '\n')
.replace(/^-- MySQL dump .*\n/gm, '')
.replace(/^-- Host:.*\n/gm, '')
.replace(/^-- -+\n/gm, '')
.replace(/^--\s*\n/gm, '')
.replace(/^-- Server version.*\n/gm, '')
.replace(/^-- Dump completed on .*\n?/gm, '')
.replace(/\/\*!\d{5}\s+DEFINER=`[^`]+`@`[^`]+`\*\//g, '')
.replace(
/^(\/\*!\d{5}\s+)DEFINER=`[^`]+`@`[^`]+`\s+(SQL SECURITY\s+(?:DEFINER|INVOKER)\s+\*\/)$/gm,
'$1$2',
)
// 普通视图的 DEFINER 只允许出现在版本注释外、语句行首的 CREATE 前缀中；
// 限定在行首可避免误删例程字符串或注释里的业务文本。
.replace(/^(\/\*!\d{5}\s+CREATE\s+[^\n]*?)\bDEFINER=`[^`]+`@`[^`]+`\s*/gm, '$1')
.replace(/^(\) ENGINE=[^\n;]*?) AUTO_INCREMENT=\d+(?= )/gm, '$1')
.replace(/^\s+/, '')
.replace(/\s+$/, '');
const result = normalized.length > 0 ? `${normalized}\n` : '';
assertSchemaHasNoSensitiveOrDataStatements(result);
return result;
}
function sha256(content) {
return createHash('sha256').update(content, 'utf8').digest('hex');
}
function buildManifest(fields) {
// JSON 是 YAML 1.2 的严格子集；使用标准解析器生成和读取，避免手写 YAML
// 对缩进、引号和同名嵌套字段产生歧义，同时仍保留约定的 manifest.yaml 文件名。
return `${JSON.stringify(
{
format_version: BASELINE_FORMAT_VERSION,
status: fields.status,
application_version: fields.applicationVersion,
git_commit: fields.gitCommit,
source_environment: 'development',
database_name: DEVELOPMENT_DATABASE,
mysql_client_version: fields.mysqlClientVersion,
mysqldump_client_version: fields.mysqldumpClientVersion,
mysql_server_version: fields.serverVersion,
charset: REQUIRED_CHARSET,
collation: REQUIRED_COLLATION,
generated_at: fields.generatedAt,
generator: `schema-baseline/${TOOL_VERSION}`,
reason: fields.reason ?? 'none',
schema_sha256: fields.schemaSha256 ?? 'not_applicable',
objects: {
tables: fields.captured,
views: fields.captured,
triggers: fields.captured,
routines: fields.captured,
events: fields.captured,
},
},
null,
2,
)}\n`;
}
export function buildCapturedArtifacts(metadata, sql) {
assertMysql57Metadata(metadata);
if (!VERSION_PATTERN.test(metadata.applicationVersion ?? '')) {
throw new Error(`应用版本格式无效：${metadata.applicationVersion || '(空)'}`);
}
const normalizedSql = normalizeSchemaSql(sql);
if (!normalizedSql.trim()) {
throw new Error('真实 Schema SQL 不能为空');
}
const schemaSha256 = sha256(normalizedSql);
const manifest = buildManifest({
...metadata,
status: 'captured',
captured: true,
schemaSha256,
});
return Object.freeze({
status: 'captured',
schemaSha256,
files: Object.freeze({
'manifest.yaml': manifest,
'schema.sql': normalizedSql,
'checksum.sha256': `${schemaSha256} schema.sql\n`,
}),
});
}
export function buildNotApplicableArtifacts(metadata) {
if (!VERSION_PATTERN.test(metadata.applicationVersion ?? '')) {
throw new Error(`应用版本格式无效：${metadata.applicationVersion || '(空)'}`);
}
const manifest = buildManifest({
...metadata,
mysqlClientVersion: 'not_enabled',
mysqldumpClientVersion: 'not_enabled',
serverVersion: 'not_enabled',
status: 'not_applicable',
reason: 'mysql_disabled',
captured: false,
});
return Object.freeze({
status: 'not_applicable',
files: Object.freeze({ 'manifest.yaml': manifest }),
});
}
function compareExistingArtifacts(targetDirectory, artifacts) {
const actualFiles = readdirSync(targetDirectory).sort();
const expectedFiles = Object.keys(artifacts.files).sort();
if (
actualFiles.length !== expectedFiles.length ||
actualFiles.some((file, index) => file !== expectedFiles[index])
) {
return false;
}
return expectedFiles.every(
(file) => readFileSync(path.join(targetDirectory, file), 'utf8') === artifacts.files[file],
);
}
/**
* 先在目标父目录写入临时目录，再原子改名。这样异常不会留下半份基线；
* 已发布版本目录只允许逐字节相同的幂等重跑，任何差异都必须人工留痕修正。
*/
export function persistBaselineArtifacts(targetDirectory, artifacts) {
if (existsSync(targetDirectory)) {
if (compareExistingArtifacts(targetDirectory, artifacts)) {
return { reused: true };
}
throw new Error(`目标版本基线已存在且内容不同，禁止覆盖：${targetDirectory}`);
}
const parentDirectory = path.dirname(targetDirectory);
mkdirSync(parentDirectory, { recursive: true });
const temporaryDirectory = path.join(
parentDirectory,
`.${path.basename(targetDirectory)}.tmp-${process.pid}-${Date.now()}`,
);
mkdirSync(temporaryDirectory);
try {
for (const [file, content] of Object.entries(artifacts.files)) {
writeFileSync(path.join(temporaryDirectory, file), content, 'utf8');
}
renameSync(temporaryDirectory, targetDirectory);
} catch (error) {
rmSync(temporaryDirectory, { recursive: true, force: true });
throw error;
}
return { reused: false };
}
function parseManifest(content) {
try {
return JSON.parse(content);
} catch {
throw new Error('manifest.yaml 不是有效的结构化 YAML/JSON 清单');
}
}
function assertExactFileSet(targetDirectory, expectedFiles) {
const actualFiles = readdirSync(targetDirectory).sort();
const sortedExpected = [...expectedFiles].sort();
if (
actualFiles.length !== sortedExpected.length ||
actualFiles.some((file, index) => file !== sortedExpected[index])
) {
throw new Error(
`Schema 基线文件集合无效，要求 ${sortedExpected.join(', ')}，实际 ${actualFiles.join(', ')}`,
);
}
}
export function verifyBaselineDirectory(targetDirectory, expectedRelease, expectedCommit) {
if (!VERSION_PATTERN.test(expectedRelease ?? '')) {
throw new Error(`待验证版本格式无效：${expectedRelease || '(空)'}`);
}
if (!existsSync(targetDirectory)) {
throw new Error(`当前已发布版本缺少 Schema 基线：${targetDirectory}`);
}
const manifest = parseManifest(
readFileSync(path.join(targetDirectory, 'manifest.yaml'), 'utf8'),
);
const status = manifest.status;
const applicationVersion = manifest.application_version;
const generatedAt = Date.parse(manifest.generated_at ?? '');
if (
manifest.format_version !== BASELINE_FORMAT_VERSION ||
manifest.generator !== `schema-baseline/${TOOL_VERSION}` ||
!Number.isFinite(generatedAt) ||
!/^[0-9a-f]{40}$/.test(manifest.git_commit ?? '')
) {
throw new Error('Schema 清单格式、生成器、时间或 Git 提交无效');
}
requireExactValue(applicationVersion, expectedRelease, 'Schema 基线版本与发布版本不一致');
if (expectedCommit !== undefined) {
requireExactValue(
manifest.git_commit,
expectedCommit,
'Schema 基线提交与发布标签不一致',
);
}
requireExactValue(
manifest.source_environment,
'development',
'Schema 基线来源环境无效',
);
requireExactValue(
manifest.database_name,
DEVELOPMENT_DATABASE,
'Schema 基线数据库名无效',
);
requireExactValue(manifest.charset, REQUIRED_CHARSET, 'Schema 字符集无效');
requireExactValue(
manifest.collation,
REQUIRED_COLLATION,
'Schema 排序规则无效',
);
if (status === 'not_applicable') {
assertExactFileSet(targetDirectory, NOT_APPLICABLE_FILES);
const reason = manifest.reason;
requireExactValue(reason, 'mysql_disabled', 'Schema 不适用原因无效');
if (
manifest.mysql_client_version !== 'not_enabled' ||
manifest.mysqldump_client_version !== 'not_enabled' ||
manifest.mysql_server_version !== 'not_enabled' ||
manifest.schema_sha256 !== 'not_applicable' ||
Object.keys(manifest.objects ?? {}).sort().join(',') !== [...OBJECT_KEYS].sort().join(',') ||
OBJECT_KEYS.some((key) => manifest.objects[key] !== false)
) {
throw new Error('Schema 不适用清单必须证明 MySQL 未启用且所有对象均未捕获');
}
return { status, applicationVersion, reason };
}
if (status !== 'captured') {
throw new Error(`Schema 基线状态无效：${status}`);
}
assertExactFileSet(targetDirectory, CAPTURED_FILES);
assertMysql57Metadata({
mysqlClientVersion: manifest.mysql_client_version,
mysqldumpClientVersion: manifest.mysqldump_client_version,
serverVersion: manifest.mysql_server_version,
databaseCharset: manifest.charset,
databaseCollation: manifest.collation,
});
if (Object.keys(manifest.objects ?? {}).sort().join(',') !== [...OBJECT_KEYS].sort().join(',')) {
throw new Error('Schema 对象范围字段无效');
}
for (const objectName of OBJECT_KEYS) {
requireExactValue(manifest.objects?.[objectName], true, `Schema 对象范围缺少 ${objectName}`);
}
const sql = readFileSync(path.join(targetDirectory, 'schema.sql'), 'utf8');
if (!sql.trim()) {
throw new Error('真实 Schema SQL 不能为空');
}
assertSchemaHasNoSensitiveOrDataStatements(sql);
if (/^(\) ENGINE=[^\n;]*?) AUTO_INCREMENT=\d+(?= )/m.test(sql)) {
throw new Error('Schema SQL 仍包含当前 AUTO_INCREMENT 值');
}
const schemaSha256 = sha256(sql);
const manifestChecksum = manifest.schema_sha256;
const checksumFile = readFileSync(path.join(targetDirectory, 'checksum.sha256'), 'utf8');
if (manifestChecksum !== schemaSha256 || checksumFile !== `${schemaSha256} schema.sql\n`) {
throw new Error('Schema SQL、manifest 和 checksum 校验值不一致');
}
return { status, applicationVersion, schemaSha256 };
}
export function parseEnvironmentFile(content) {
const config = {};
for (const rawLine of String(content).replace(/\r\n?/g, '\n').split('\n')) {
const line = rawLine.trim();
if (!line || line.startsWith('#')) continue;
const separator = line.indexOf('=');
if (separator <= 0) {
throw new Error('开发环境配置包含无效行');
}
const key = line.slice(0, separator).trim();
const value = line.slice(separator + 1).trim();
if (!/^[A-Z][A-Z0-9_]*$/.test(key)) {
throw new Error(`开发环境配置键无效：${key}`);
}
config[key] = value;
}
return config;
}
function extractClientVersion(output) {
const match = String(output).match(/\b(?:Distrib\s+)?(5\.7\.\d+(?:[-+][^\s,]+)?)/);
return match?.[1] ?? String(output).trim();
}
/**
* 真实执行器可注入是为了让测试证明“关闭时零数据库调用”和命令边界；默认执行器
* 仍使用 execFileSync 参数数组。密码仅放入子进程环境 MYSQL_PWD，不会进入 argv。
*/
export function runBaselineGeneration(options) {
if ((options.commandArguments ?? []).length > 0) {
throw new Error('Schema 基线命令不接受命令参数，不能覆盖环境、数据库或 env 路径');
}
const config = assertSafeDevelopmentConfiguration(
parseEnvironmentFile(readFileSync(options.envFile, 'utf8')),
);
const targetDirectory = path.join(
options.repositoryRoot,
'database',
'schema-baselines',
options.applicationVersion,
);
if (existsSync(targetDirectory)) {
return verifyBaselineDirectory(
targetDirectory,
options.applicationVersion,
options.gitCommit,
);
}
const commonMetadata = {
applicationVersion: options.applicationVersion,
gitCommit: options.gitCommit,
generatedAt: options.generatedAt ?? new Date().toISOString(),
};
if (!config.MYSQL_ENABLED) {
const artifacts = buildNotApplicableArtifacts(commonMetadata);
persistBaselineArtifacts(targetDirectory, artifacts);
return verifyBaselineDirectory(targetDirectory, options.applicationVersion);
}
const executeFile = options.executeFile ?? execFileSync;
const childEnvironment = { ...process.env, MYSQL_PWD: config.MYSQL_PASSWORD ?? '' };
const executionOptions = {
cwd: options.repositoryRoot,
encoding: 'utf8',
stdio: ['ignore', 'pipe', 'pipe'],
env: childEnvironment,
};
const mysqlClientVersion = extractClientVersion(
executeFile('mysql', ['--version'], executionOptions),
);
const mysqldumpClientVersion = extractClientVersion(
executeFile('mysqldump', ['--version'], executionOptions),
);
assertMysql57Metadata({
mysqlClientVersion,
mysqldumpClientVersion,
serverVersion: '5.7.0-pending-server-check',
databaseCharset: REQUIRED_CHARSET,
databaseCollation: REQUIRED_COLLATION,
});
const serverMetadata = String(
executeFile('mysql', buildMysqlMetadataArguments(config), executionOptions),
)
.trim()
.split('\t');
if (serverMetadata.length !== 3) {
throw new Error('无法从固定开发库读取 MySQL 版本、字符集和排序规则');
}
const metadata = {
...commonMetadata,
mysqlClientVersion,
mysqldumpClientVersion,
serverVersion: serverMetadata[0],
databaseCharset: serverMetadata[1],
databaseCollation: serverMetadata[2],
};
assertMysql57Metadata(metadata);
const rawSql = executeFile('mysqldump', buildMysqldumpArguments(config), executionOptions);
const artifacts = buildCapturedArtifacts(metadata, rawSql);
persistBaselineArtifacts(targetDirectory, artifacts);
return verifyBaselineDirectory(targetDirectory, options.applicationVersion);
}
function runGit(repositoryRoot, args) {
return execFileSync('git', args, {
cwd: repositoryRoot,
encoding: 'utf8',
stdio: ['ignore', 'pipe', 'pipe'],
}).trim();
}
export function getCurrentReleasedVersion(repositoryRoot) {
const applicationVersion = runGit(repositoryRoot, [
'describe',
'--tags',
'--abbrev=0',
'--match',
'v[0-9]*',
]);
if (!VERSION_PATTERN.test(applicationVersion)) {
throw new Error(`最近发布标签格式无效：${applicationVersion}`);
}
return {
applicationVersion,
gitCommit: runGit(repositoryRoot, ['rev-list', '-n', '1', applicationVersion]),
};
}
export function assertCurrentReleasedBaseline(repositoryRoot) {
const { applicationVersion, gitCommit } = getCurrentReleasedVersion(repositoryRoot);
return verifyBaselineDirectory(
path.join(repositoryRoot, 'database', 'schema-baselines', applicationVersion),
applicationVersion,
gitCommit,
);
}
function runGitLines(repositoryRoot, args) {
const output = runGit(repositoryRoot, args);
return output ? output.split('\n').filter(Boolean) : [];
}
/**
* 开始下一版本前使用严格门禁：本地校验只证明内容正确，不能证明它已经进入
* 可协作历史。这里进一步要求基线已跟踪、工作区无相关改动、当前 HEAD 已推送，
* 且 origin 上的发布标签仍指向清单记录的提交。
*/
export function assertCurrentReleasedBaselinePublished(repositoryRoot) {
const release = getCurrentReleasedVersion(repositoryRoot);
const relativeDirectory = path.posix.join(
'database',
'schema-baselines',
release.applicationVersion,
);
const result = verifyBaselineDirectory(
path.join(repositoryRoot, relativeDirectory),
release.applicationVersion,
release.gitCommit,
);
const trackedFiles = new Set(
runGitLines(repositoryRoot, ['ls-files', '--', relativeDirectory]),
);
const expectedFiles =
result.status === 'captured' ? CAPTURED_FILES : NOT_APPLICABLE_FILES;
for (const file of expectedFiles) {
const relativeFile = path.posix.join(relativeDirectory, file);
if (!trackedFiles.has(relativeFile)) {
throw new Error(`Schema 基线尚未提交到 Git：${relativeFile}`);
}
}
const localChanges = runGitLines(repositoryRoot, [
'status',
'--porcelain',
'--',
relativeDirectory,
]);
if (localChanges.length > 0) {
throw new Error(`Schema 基线存在未提交改动：${localChanges.join(', ')}`);
}
const branch = runGit(repositoryRoot, ['branch', '--show-current']);
if (!branch) {
throw new Error('Schema 发布门禁要求当前位于可推送分支');
}
const localHead = runGit(repositoryRoot, ['rev-parse', 'HEAD']);
assertRemoteBranchMatches(repositoryRoot, branch, runGit, localHead);
const remoteTag = runGit(repositoryRoot, [
'ls-remote',
'--tags',
'origin',
`refs/tags/${release.applicationVersion}^{}`,
]);
const remoteTagCommit = remoteTag.split(/\s+/)[0];
requireExactValue(remoteTagCommit, release.gitCommit, '远程发布标签与基线提交不一致');
return result;
}
export function assertRemoteBranchMatches(repositoryRoot, branch, gitRunner = runGit, localHead) {
const expectedHead = localHead ?? gitRunner(repositoryRoot, ['rev-parse', 'HEAD']);
const remoteOutput = gitRunner(repositoryRoot, ['ls-remote', 'origin', `refs/heads/${branch}`]);
const remoteHead = remoteOutput.split(/\s+/)[0];
requireExactValue(remoteHead, expectedHead, '当前分支尚未完整推送到 origin');
return true;
}
function resolveFixedDevelopmentEnv(repositoryRoot) {
const realDevelopmentEnv = path.join(repositoryRoot, 'deploy', 'env', 'development', 'api.env');
if (existsSync(realDevelopmentEnv)) return realDevelopmentEnv;
return path.join(repositoryRoot, 'deploy', 'env', 'development', 'api.env.example');
}
function runCommandLine() {
const [command, ...commandArguments] = process.argv.slice(2);
if (!['generate', 'verify'].includes(command) || commandArguments.length > 0) {
throw new Error('用法：node tools/database/schema-baseline.mjs <generate|verify>（不接受额外参数）');
}
const repositoryRoot = process.cwd();
const release = getCurrentReleasedVersion(repositoryRoot);
const result =
command === 'generate'
? runBaselineGeneration({
repositoryRoot,
envFile: resolveFixedDevelopmentEnv(repositoryRoot),
...release,
commandArguments,
})
: assertCurrentReleasedBaseline(repositoryRoot);
process.stdout.write(
`Schema 基线验证通过：${release.applicationVersion} (${result.status})\n`,
);
}
if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
runCommandLine();
}
tools/database/schema-baseline.test.mjs
+403
View File
@@ -0,0 +1,403 @@
import assert from 'node:assert/strict';
import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import path from 'node:path';
import test from 'node:test';
import {
assertMysql57Metadata,
assertCurrentReleasedBaselinePublished,
assertSafeDevelopmentConfiguration,
buildCapturedArtifacts,
buildMysqldumpArguments,
buildNotApplicableArtifacts,
normalizeSchemaSql,
persistBaselineArtifacts,
runBaselineGeneration,
assertRemoteBranchMatches,
verifyBaselineDirectory,
} from './schema-baseline.mjs';
const validConfig = Object.freeze({
APP_ENV: 'development',
MYSQL_ENABLED: 'true',
MYSQL_HOST: '127.0.0.1',
MYSQL_PORT: '3306',
MYSQL_DATABASE: 'a_share_analysis_dev',
MYSQL_USERNAME: 'schema_reader',
MYSQL_PASSWORD: 'never-place-this-in-arguments',
MYSQL_CHARSET: 'utf8mb4',
MYSQL_COLLATION: 'utf8mb4_general_ci',
});
const validMetadata = Object.freeze({
applicationVersion: 'v0.0.5',
gitCommit: '0a69aa1f6f5cc75d72f21c43d96f5ff648e2ec93',
mysqlClientVersion: '5.7.44',
mysqldumpClientVersion: '5.7.44',
serverVersion: '5.7.44-log',
databaseCharset: 'utf8mb4',
databaseCollation: 'utf8mb4_general_ci',
generatedAt: '2026-08-13T03:00:00.000Z',
});
function makeTemporaryDirectory() {
return mkdtempSync(path.join(tmpdir(), 'a-share-schema-baseline-'));
}
test('拒绝任何非开发环境和非固定开发库配置', () => {
assert.throws(
() => assertSafeDevelopmentConfiguration({ ...validConfig, APP_ENV: 'production' }),
/只允许 development/,
);
assert.throws(
() =>
assertSafeDevelopmentConfiguration({
...validConfig,
MYSQL_DATABASE: 'a_share_analysis',
}),
/a_share_analysis_dev/,
);
assert.throws(
() =>
assertSafeDevelopmentConfiguration({
...validConfig,
MYSQL_HOST: 'forbidden-remote.example.invalid',
}),
/开发机回环地址/,
);
});
test('拒绝错误字符集、排序规则和不完整的启用配置', () => {
assert.throws(
() => assertSafeDevelopmentConfiguration({ ...validConfig, MYSQL_CHARSET: 'utf8' }),
/utf8mb4/,
);
assert.throws(
() =>
assertSafeDevelopmentConfiguration({
...validConfig,
MYSQL_COLLATION: 'utf8mb4_0900_ai_ci',
}),
/utf8mb4_general_ci/,
);
assert.throws(
() => assertSafeDevelopmentConfiguration({ ...validConfig, MYSQL_USERNAME: '' }),
/MYSQL_USERNAME/,
);
assert.throws(
() => assertSafeDevelopmentConfiguration({ ...validConfig, MYSQL_PASSWORD: '' }),
/MYSQL_PASSWORD/,
);
});
test('只接受 MySQL 5.7 客户端、服务端和固定数据库字符规则', () => {
assert.doesNotThrow(() => assertMysql57Metadata(validMetadata));
assert.throws(
() => assertMysql57Metadata({ ...validMetadata, serverVersion: '8.0.39' }),
/服务端必须为 5\.7/,
);
assert.throws(
() => assertMysql57Metadata({ ...validMetadata, mysqlClientVersion: '8.0.39' }),
/mysql 客户端必须为 5\.7/,
);
assert.throws(
() => assertMysql57Metadata({ ...validMetadata, databaseCollation: 'utf8mb4_bin' }),
/utf8mb4_general_ci/,
);
});
test('mysqldump 只导出完整结构且密码不进入命令参数', () => {
const args = buildMysqldumpArguments(validConfig);
for (const required of ['--no-data', '--routines', '--triggers', '--events']) {
assert.ok(args.includes(required), `缺少强制导出参数：${required}`);
}
assert.equal(args.at(-1), 'a_share_analysis_dev');
assert.equal(args.join(' ').includes(validConfig.MYSQL_PASSWORD), false);
assert.equal(args.some((argument) => argument.startsWith('--password')), false);
});
test('规范化移除环境噪声和账号绑定但保留全部业务对象', () => {
const fixtureDirectory = path.join(import.meta.dirname, 'fixtures');
const input = readFileSync(path.join(fixtureDirectory, 'mysql57-schema-input.sql'), 'utf8');
const expected = readFileSync(
path.join(fixtureDirectory, 'mysql57-schema-expected.sql'),
'utf8',
);
const actual = normalizeSchemaSql(input);
assert.equal(actual, expected);
assert.match(actual, /NOT NULL AUTO_INCREMENT/);
assert.doesNotMatch(actual, /AUTO_INCREMENT=128/);
assert.doesNotMatch(actual, /DEFINER=`/);
for (const objectName of [
'CREATE TABLE',
'VIEW `active_market_snapshot`',
'TRIGGER `market_snapshot_before_insert`',
'PROCEDURE `refresh_market_snapshot`',
'EVENT `purge_market_snapshot`',
]) {
assert.ok(actual.includes(objectName), `规范化误删对象：${objectName}`);
}
});
test('规范化不改写例程字符串中的业务文本', () => {
const sql = [
'CREATE PROCEDURE `describe_schema`()',
"BEGIN SELECT 'DEFINER=`business`@`text` AUTO_INCREMENT=128' AS description; END;",
'',
].join('\n');
assert.equal(normalizeSchemaSql(sql), sql);
});
test('数据扫描拒绝同行顶层写入但保留例程中的合法 DML', () => {
assert.throws(
() => normalizeSchemaSql('CREATE TABLE `sample` (`id` int); INSERT INTO `sample` VALUES (1);\n'),
/INSERT INTO/,
);
const routineSql = [
'DELIMITER ;;',
'CREATE PROCEDURE `seed_fixture`()',
'BEGIN',
'INSERT INTO `sample` VALUES (1);',
'END ;;',
'DELIMITER ;',
'',
].join('\n');
assert.equal(normalizeSchemaSql(routineSql), routineSql);
for (const prefixedSql of [
'/* comment */\nINSERT INTO `sample` VALUES (1);\n',
'/*!40101 SET @x=1 */ INSERT INTO `sample` VALUES (1);\n',
'/*!40101 INSERT INTO `sample` VALUES (1) */;\n',
'/*!40101 REPLACE INTO `sample` VALUES (1) */;\n',
'CREATE TABLE `sample` (`id` int); -- comment\nREPLACE INTO `sample` VALUES (1);\n',
]) {
assert.throws(() => normalizeSchemaSql(prefixedSql), /INSERT INTO|REPLACE INTO/);
}
});
test('真实基线的清单、校验文件和 SQL 必须三方一致', () => {
const sql = 'CREATE TABLE `sample` (`id` bigint NOT NULL AUTO_INCREMENT);\n';
const root = makeTemporaryDirectory();
const target = path.join(root, 'v0.0.5');
const artifacts = buildCapturedArtifacts(validMetadata, sql);
persistBaselineArtifacts(target, artifacts);
const result = verifyBaselineDirectory(target, 'v0.0.5');
assert.equal(result.status, 'captured');
assert.equal(result.applicationVersion, 'v0.0.5');
assert.equal(result.schemaSha256, artifacts.schemaSha256);
assert.equal(readFileSync(path.join(target, 'checksum.sha256'), 'utf8'), `${artifacts.schemaSha256} schema.sql\n`);
});
test('拒绝静默覆盖已存在且内容不同的版本基线', () => {
const root = makeTemporaryDirectory();
const target = path.join(root, 'v0.0.5');
const artifacts = buildCapturedArtifacts(validMetadata, 'CREATE TABLE `sample` (`id` int);\n');
persistBaselineArtifacts(target, artifacts);
assert.doesNotThrow(() => persistBaselineArtifacts(target, artifacts));
assert.throws(
() =>
persistBaselineArtifacts(
target,
buildCapturedArtifacts(validMetadata, 'CREATE TABLE `changed` (`id` int);\n'),
),
/禁止覆盖/,
);
});
test('MySQL 未启用时只生成可验证不适用清单', () => {
const root = makeTemporaryDirectory();
const target = path.join(root, 'v0.0.5');
const artifacts = buildNotApplicableArtifacts(validMetadata);
persistBaselineArtifacts(target, artifacts);
const result = verifyBaselineDirectory(target, 'v0.0.5');
assert.equal(result.status, 'not_applicable');
assert.equal(result.reason, 'mysql_disabled');
assert.throws(() => readFileSync(path.join(target, 'schema.sql')), /ENOENT/);
assert.throws(() => readFileSync(path.join(target, 'checksum.sha256')), /ENOENT/);
});
test('未启用入口不调用数据库且拒绝额外命令参数', () => {
const root = makeTemporaryDirectory();
const envFile = path.join(root, 'development.env');
writeFileSync(
envFile,
'APP_ENV=development\nMYSQL_ENABLED=false\nMYSQL_DATABASE=a_share_analysis_dev\nMYSQL_CHARSET=utf8mb4\nMYSQL_COLLATION=utf8mb4_general_ci\n',
);
let executionCount = 0;
const result = runBaselineGeneration({
repositoryRoot: root,
envFile,
applicationVersion: 'v0.0.5',
gitCommit: validMetadata.gitCommit,
generatedAt: validMetadata.generatedAt,
executeFile() {
executionCount += 1;
throw new Error('未启用路径不应执行数据库命令');
},
});
assert.equal(result.status, 'not_applicable');
assert.equal(executionCount, 0);
assert.throws(
() => runBaselineGeneration({ ...result, commandArguments: ['--env', 'production.env'] }),
/不接受命令参数/,
);
});
test('启用入口分别校验 mysql 与 mysqldump 客户端版本', () => {
const root = makeTemporaryDirectory();
const envFile = path.join(root, 'development.env');
writeFileSync(
envFile,
Object.entries(validConfig)
.map(([key, value]) => `${key}=${value}`)
.join('\n'),
);
assert.throws(
() =>
runBaselineGeneration({
repositoryRoot: root,
envFile,
applicationVersion: 'v0.0.5',
gitCommit: validMetadata.gitCommit,
generatedAt: validMetadata.generatedAt,
executeFile(command, args) {
if (args[0] === '--version') {
return command === 'mysql'
? 'mysql Ver 8.0.39 for macos'
: 'mysqldump Ver 10.13 Distrib 5.7.44, for macos';
}
if (command === 'mysql') {
return '5.7.44-log\tutf8mb4\tutf8mb4_general_ci\n';
}
return 'CREATE TABLE `sample` (`id` int);\n';
},
}),
/mysql 客户端必须为 5\.7/,
);
});
test('幂等重跑仍核对清单提交与发布标签提交', () => {
const root = makeTemporaryDirectory();
const envFile = path.join(root, 'development.env');
writeFileSync(
envFile,
'APP_ENV=development\nMYSQL_ENABLED=false\nMYSQL_DATABASE=a_share_analysis_dev\nMYSQL_CHARSET=utf8mb4\nMYSQL_COLLATION=utf8mb4_general_ci\n',
);
const target = path.join(root, 'database', 'schema-baselines', 'v0.0.5');
persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata));
assert.throws(
() =>
runBaselineGeneration({
repositoryRoot: root,
envFile,
applicationVersion: 'v0.0.5',
gitCommit: 'ffffffffffffffffffffffffffffffffffffffff',
}),
/提交与发布标签不一致/,
);
});
test('校验能发现 SQL 被修改且生成阶段拒绝空基线', () => {
const root = makeTemporaryDirectory();
const target = path.join(root, 'v0.0.5');
persistBaselineArtifacts(
target,
buildCapturedArtifacts(validMetadata, 'CREATE TABLE `sample` (`id` int);\n'),
);
writeFileSync(path.join(target, 'schema.sql'), 'CREATE TABLE `tampered` (`id` int);\n');
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /校验值不一致/);
assert.throws(
() => buildCapturedArtifacts({ ...validMetadata, applicationVersion: 'v0.0.4' }, ''),
/不能为空/,
);
});
test('基线清单中的提交必须等于发布标签指向的提交', () => {
const root = makeTemporaryDirectory();
const target = path.join(root, 'v0.0.5');
persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata));
assert.throws(
() => verifyBaselineDirectory(target, 'v0.0.5', 'ffffffffffffffffffffffffffffffffffffffff'),
/提交与发布标签不一致/,
);
});
test('校验拒绝篡改成错误 MySQL 版本或伪造对象范围的真实清单', () => {
const root = makeTemporaryDirectory();
const target = path.join(root, 'v0.0.5');
persistBaselineArtifacts(
target,
buildCapturedArtifacts(validMetadata, 'CREATE TABLE `sample` (`id` int);\n'),
);
const manifestPath = path.join(target, 'manifest.yaml');
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
manifest.mysql_server_version = '8.0.39';
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /服务端必须为 5\.7/);
manifest.mysql_server_version = '5.7.44-log';
manifest.objects.events = false;
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /events/);
});
test('不适用清单必须明确记录 MySQL 未启用且所有对象未捕获', () => {
const root = makeTemporaryDirectory();
const target = path.join(root, 'v0.0.5');
persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata));
const manifestPath = path.join(target, 'manifest.yaml');
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
manifest.mysql_server_version = '5.7.44';
manifest.objects.tables = true;
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /不适用清单/);
});
test('不适用清单拒绝未知对象键和伪造的格式元数据', () => {
const root = makeTemporaryDirectory();
const target = path.join(root, 'v0.0.5');
persistBaselineArtifacts(target, buildNotApplicableArtifacts(validMetadata));
const manifestPath = path.join(target, 'manifest.yaml');
const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
manifest.format_version = 999;
manifest.generator = 'unknown';
manifest.schema_sha256 = 'forged';
manifest.objects = { a: false, b: false, c: false, d: false, e: false };
writeFileSync(manifestPath, `${JSON.stringify(manifest, null, 2)}\n`);
assert.throws(() => verifyBaselineDirectory(target, 'v0.0.5'), /清单格式/);
});
test('严格发布门禁通过已提交且远程同步的当前基线', () => {
assert.doesNotThrow(() => assertCurrentReleasedBaselinePublished(process.cwd()));
});
test('远程分支校验实时读取 origin 而不是陈旧 tracking ref', () => {
assert.doesNotThrow(() =>
assertRemoteBranchMatches('/repo', 'main', (_root, args) => {
assert.deepEqual(args, ['ls-remote', 'origin', 'refs/heads/main']);
return 'abc123\trefs/heads/main';
}, 'abc123'),
);
assert.throws(
() =>
assertRemoteBranchMatches('/repo', 'main', () => 'def456\trefs/heads/main', 'abc123'),
/尚未完整推送到 origin/,
);
});