MooTool Next-Compose 编辑器设置规范化实战:SQL 方言回退机制与 JSON 系字号即时生效(DIFF-530 深度解析)
MooTool Next-Compose 编辑器设置规范化实战:SQL 方言回退机制与 JSON 系字号即时生效(DIFF-530 深度解析)
导读
本文以 DIFF-530 设计文档 为骨架,系统讲解 MooTool Next(Compose Desktop 分支)在编辑器设置一致性上的三项收口工作:editor.sqlDialect 非法值回退、JSON 系编辑器字号即时生效、HTTP 响应区字号修复。文中将结合仓库内 EditorFontSettings.kt、EditorSettingsLiveApply.kt、SettingsRepository.kt 及对应测试,给出可验证的源码级依据,帮助开发者理解"Electron 迁入兼容"与"设置即时生效"的实现模式。
背景:DIFF-529 遗留的三处不一致
DIFF-530 是 MooTool Next-Compose 特性切片序列中的一环,前置的 DIFF-529 已实现"按工具区分软换行"(httpEditorWrap / newQuickNoteLineWrap / runtimeEditorWrap),但遗留了三个缺口:
- SQL 方言非法值无回退:设置加载 / Electron 迁入时,
editor.sqlDialect若为未知字符串不会回退到默认值;且 Electron 下拉仅有 10 项预设,其他方言字符串进入 Compose 后会失配。 - HTTP 响应区字号硬编码:F09 HTTP 工具的响应区
EditorHost固定fontSize = 11,与请求 Body 读取全局设置不一致。 - 命令盘难搜到 SQL 方言设置:命令盘搜索
sql/dialect/方言无法定位到编辑器设置页。
DIFF-530 用三个行为(A01、A01/F04/F05/F09)逐项收口。
A01 设置 · 编辑器:SQL 方言规范化
预设列表与回退规则
EditorFontSettings.normalizeSqlDialect 是本次的核心函数,位于 EditorFontSettings.kt:
fun normalizeSqlDialect(value: String, fallback: String): String {
val trimmed = value.trim()
if (trimmed.isEmpty()) return fallback
if (trimmed.equals("mysql", ignoreCase = true)) return "MySQL"
sqlDialectPresets.firstOrNull { it.equals(trimmed, ignoreCase = true) }?.let { return it }
return fallback
}
回退规则明确:
- 空串 / 纯空白 → 返回
fallback(默认Standard SQL); mysql别名 → 归一为MySQL(大小写不敏感,兼容旧配置);- 命中预设列表(大小写不敏感)→ 返回预设的标准写法(如
postgresql→PostgreSQL); - 未知值 → 返回
fallback。
预设列表 sqlDialectPresets 共 10 项,与 Electron SettingsWindow 下拉及 SqlFormatEngine.dialects 完全一致(EditorFontSettings.kt):
| 序号 | 方言(标准写法) |
|---|---|
| 1 | Standard SQL |
| 2 | MySQL |
| 3 | MariaDB |
| 4 | PostgreSQL |
| 5 | Oracle PL/SQL |
| 6 | SQL Server Transact-SQL |
| 7 | IBM DB2 |
| 8 | Couchbase N1QL |
| 9 | Amazon Redshift |
| 10 | Spark |
在 Compose 侧,SqlFormatEngine.kt 直接复用 EditorFontSettings.sqlDialectPresets 作为格式化器方言表:
object SqlFormatEngine {
val dialects: List<String> = EditorFontSettings.sqlDialectPresets
也就是说"设置下拉"与"SQL 格式化器"共享同一份权威方言清单,避免两边漂移。SqlFormatEngine 还根据方言归一化结果决定标识符引用符(identifierQuotes):MySQL/MariaDB 用反引号 `,SQL Server T-SQL 用方括号 [],其余用双引号 "——这是方言值在格式化场景的真实消费点。
规范化管道的三处接入点
normalizeSqlDialect 通过 normalizeEditorSettings 统一入口生效,该函数还会同时修剪两个字体名字段:
fun normalizeEditorSettings(editor: EditorSettings, defaults: EditorSettings): EditorSettings =
editor.copy(
sqlDialect = normalizeSqlDialect(editor.sqlDialect, defaults.sqlDialect),
jsonFontName = normalizeFontName(editor.jsonFontName, defaults.jsonFontName),
quickNoteFontName = normalizeFontName(editor.quickNoteFontName, defaults.quickNoteFontName),
)
三处接入点覆盖了全部设置写入路径:
- 设置加载:SettingsRepository.sanitizeLoadedSettings 在读取设置文件后调用
normalizeEditorSettings,并在结果与原始值不同时写回磁盘(if (sanitized != base) save(sanitized)),实现"脏数据自愈"。 SettingsRepository.save/update:所有保存动作都先经过sanitizeLoadedSettings(SettingsRepository.kt),保证落盘值永远是合法的。- Electron 设置迁入:ElectronNextSettingsImport.sanitize 在解析 Electron store 后立即调用
normalizeEditorSettings;mergeInto合并时也对editor.sqlDialect单独走normalizeSqlDialect(fallback 取当前值),且对jsonFontSize/quickNoteFontSize使用SettingsNumericBounds.clampNumber夹取到 [11, 24]。
设置界面消费
SettingsScreen.kt 的编辑器分组通过 MooSelect 渲染方言下拉:选项来自 SqlFormatEngine.dialects,当前值用 firstOrNull { it.equals(settings.editor.sqlDialect, true) } 做大小写不敏感匹配,并保留 mysql → MySQL 的兼容分支;变更后直接 updateSettings { it.copy(editor = it.editor.copy(sqlDialect = dialect)) } 落库,落库路径再次经过规范化。
单测验证
EditorFontSettingsTest.kt 覆盖了全部回退分支:
assertEquals("MySQL", EditorFontSettings.normalizeSqlDialect("mysql", "Standard SQL"))
assertEquals("PostgreSQL", EditorFontSettings.normalizeSqlDialect(" postgresql ", "Standard SQL"))
assertEquals("Standard SQL", EditorFontSettings.normalizeSqlDialect("unknown-dialect", "Standard SQL"))
assertEquals("Standard SQL", EditorFontSettings.normalizeSqlDialect("", "Standard SQL"))
其中 normalizeEditorSettings_coercesUnknownSqlDialect 专门验证 sqlDialect = "legacy" 被强制回退为 Standard SQL。
命令盘可搜索 SQL 方言设置
DIFF-530 为命令盘的 editor 分类补充了 sql / dialect / 方言 关键词,定义在 CommandSearchCatalog.kt:
CommandSettingsTarget(
categoryId = "editor",
labelKey = "settings.category.editor",
navIcon = "{ }",
keywords = listOf(
"editor", "font", "wrap", "json", "note",
"sql", "dialect", "javascript", "typescript",
"format", "jsonpath", "schema", "path",
"编辑器", "字体", "换行", "方言", "格式化", "路径",
) + EditorColumnEditPresentation.commandPaletteKeywords,
)
对应测试 CommandSearchCatalogTest.kt 保证"搜索 sql 恰好命中一个 editor 分类":
@Test
fun sqlDialectQueryOpensEditorSettings() {
val hits = CommandSearchCatalog.search("sql", Translator(AppLanguage.EnUS)::t)
assertEquals("editor", hits.single().categoryId)
}
A01 / F04 / F05 / F09:JSON 系编辑器字号即时生效
统一读取点:jsonEditorFontSize
EditorSettingsLiveApply.jsonEditorFontSize 是 JSON 系编辑器字号的唯一读取入口(EditorSettingsLiveApply.kt):
/** JSON / HTTP / CodeRun `EditorHost` font size follows global settings on each recomposition. */
fun jsonEditorFontSize(settingsJsonFontSize: Int): Int = settingsJsonFontSize
函数本身是纯透传,但其"即时生效"语义依赖各界面在**每次重组(recomposition)**时都从全局设置读取字号,而非把字号缓存进本地会话状态。DIFF-530 将其统一接入到四类工具(A01 = 设置项,F04 = JSON 检查器/Vault,F05 = 代码运行,F09 = HTTP):
| 工具界面 | 文件 | 字号取值 |
|---|---|---|
| JSON 格式化/编辑器 | JsonScreen.kt | EditorSettingsLiveApply.jsonEditorFontSize(settings.editor.jsonFontSize) |
| HTTP 请求 Body | HttpScreen.kt | 同上 |
| HTTP 响应区 | HttpScreen.kt | 同上(本次修复点) |
| 代码运行源码区 | CodeRunScreen.kt | 同上 |
| Vault Git 差异编辑器 | VaultGitDialog.kt | 同上 |
五个 EditorHost 的字号参数均为 EditorSettingsLiveApply.jsonEditorFontSize(settings.editor.jsonFontSize),配合 fontName = DocumentFormatEngine.editorFont(settings.editor.jsonFontName),实现在设置页失焦提交后重组即生效。
修复:HTTP 响应区此前固定 11sp
DIFF-530 修复了 HTTP 响应区 EditorHost 此前硬编码 fontSize = 11 的问题。修复后,HttpScreen.kt 的响应区与请求 Body 一样读取 settings.editor.jsonFontSize,两栏字号保持一致。
字号提交与边界
设置页的字号输入走失焦提交逻辑(SettingCommitTextField + SettingsEditorNumericNormalize.commitJsonFontSize / commitQuickNoteFontSize),边界为 11, 24]([SettingsToolsEditorNumericNormalize.kt),非法输入(如空串、非数字)返回 Rejected 并触发校验提示。默认值在 Settings.kt 中定义为 jsonFontSize = 14、quickNoteFontSize = 14、softWrap = true。
软换行协同
DIFF-529 已确立的按工具软换行规则在 DIFF-530 的界面中同时生效:HTTP 请求/响应区用 httpEditorWrap(settings.editor.softWrap) 每重组跟随全局设置;代码运行区用 runtimeEditorWrap() 固定 false(与 Electron RuntimeTool.tsx 的 wrap={false} 对齐);随手记新建笔记的 lineWrap 取 newQuickNoteLineWrap(settings.editor.softWrap)(对齐 Electron createQuickNote)。字号与换行两套规则共同构成"设置 → 编辑器"的即时联动模型。
单测验证
EditorSettingsLiveApplyTest.kt 验证透传与边界:
@Test
fun jsonEditorFontSizePassesThroughClampedSettingsValue() {
assertEquals(14, EditorSettingsLiveApply.jsonEditorFontSize(14))
assertEquals(11, EditorSettingsLiveApply.jsonEditorFontSize(11))
}
验证方式
DIFF-530 的验证命令与仓库既有约定一致:
./gradlew :composeApp:desktopTest --offline
前置条件为 JDK 21。涉及的测试用例集中在 EditorFontSettingsTest.kt、EditorSettingsLiveApplyTest.kt 与 CommandSearchCatalogTest.kt(sqlDialectQueryOpensEditorSettings)。该用例矩阵也被 docs/fixtures/electron-next-settings-vitest.md 记录为 Electron 迁移对应的 vitest 对照用例。
未做:明确划界,避免越权
DIFF-530 同时明确了不在本次切片范围内的项目,避免与后续切片混淆:
- 六套 CSS 皮肤;
- 产品主窗 Tab 走查;
- Host 软换行(Host 为纯文本域,无软换行开关);
- 随手记已开笔记随全局
softWrap切换(Electron 保持 frontmatter 行为); - multipart 文件 Tab;
- TCC / P7 相关目标。
这些"未做"项与 DIFF-529 的收尾方向一致,属于后续切片的输入。
小结
DIFF-530 展示了 MooTool Next-Compose 在"设置兼容性"上的三个可复用模式:
- 单一权威预设:方言列表只定义在
EditorFontSettings.sqlDialectPresets,设置下拉(SqlFormatEngine.dialects)与格式化器共用,杜绝双源漂移; - 写路径全覆盖的规范化:加载、保存、Electron 迁入三条路径统一过
normalizeEditorSettings,脏数据要么回退要么写回自愈; - 即时生效靠重组:字号/换行不缓存进会话,而是每次重组从
settings.editor读取,设置失焦提交后界面立即响应。
对需要在多端(Electron / Compose Desktop / 未来其他平台)保持一致设置的开发者,这套"规范化 + 统一读取点 + 重组驱动"的组合可以直接作为实现参照。