Files
archer/openspec/changes/archive/2026-11-06-normalize-state-config/design.md
T
voidandClaude Sonnet 4.6 bc4a6b504f Initial commit: archer, a Go-native MySQL/MariaDB table archiver
Renamed from arcdb: module path, cmd/archer, internal/archererr,
docs, build scripts and ARCHER_* environment variables.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-11-06 22:12:17 +08:00

76 lines
4.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
## Context
当前实现(见 proposal.md - Why):
- `cli.Config.Fingerprint()`(internal/cli/hash.go:17)把 `dsnFingerprint(src)` 与 `dsnFingerprint(dst)` 的结果放进 `fields` map,该 map 既用于计算 `config_hash`,也原样写入 `state.json` 的 `config`(internal/app/app.go:492)。
- `dsnFingerprint`(internal/cli/hash.go:69)手工拼接 `Net|Addr|DBName|User` 和 `Params`。
- `normalize()`(internal/cli/config.go:86)统一设置 `ParseTime=false`,`Loc` 为空时置为 UTC。
- `redactDSN`(internal/app/dryrun.go:155)已经采用"复制配置、清空密码、`FormatDSN()`"的做法。
约束:指纹必须保持可复现;密码不得落盘;旧 `state.json` 必须仍能读取(版本号不变)。
## Goals / Non-Goals
**Goals:**
- `config.source` / `config.dest` 使用可逆、可转义、生态通用的标准 DSN。
- 指纹覆盖所有可能改变导出结果的连接参数,尤其是 `charset` 与 `collation`。
**Non-Goals:**
- 不拆分"哈希输入"与"展示快照";两者继续共用同一份 `fields` map。
- 不改变 `state.json` 的 schema 版本,不做旧指纹的兼容计算。
- 不改变 `--source` / `--dest` 的输入语法(仍然是 MySQL DSN)。
## Decisions
### 1. 用 `FormatDSN()` 生成指纹片段
```go
func dsnFingerprint(c *mysql.Config) string {
if c == nil {
return ""
}
redacted := *c // 值拷贝,保留未导出字段(charsets 等)
redacted.Passwd = ""
return redacted.FormatDSN()
}
```
理由:
- `charset`、`collation`、`compress`、`timeTruncate` 是驱动的未导出字段,**只有 `FormatDSN` 能序列化它们**(dsn.go:318、322 等),手工枚举字段必然继续漏检。
- `FormatDSN` 对库名做 `PathEscape`、对参数做 `QueryEscape`、对参数 key 排序(dsn.go:379-396),输出确定且无歧义。
- 与 `redactDSN` 共用同一套序列化逻辑,`--dry-run` 与 `state.json` 的写法一致。
备选方案:
- 继续竖线格式、补上 `charset`:仍是非标准写法,未导出字段没有稳定的读取入口。
- 嵌套 JSON 对象:需要改 `State.Config` 类型与 `DiffFields`,收益是更精确的 diff;本次不取,记录为后续方向。
### 2. 用值拷贝而不是原地清空密码
`mysql.Config` 含未导出字段,值拷贝会一起带上,`FormatDSN` 因而仍能输出 `charset`。原地清空 `Passwd` 会污染调用方的配置,直接排除。
### 3. 保持 `state.json` `Version = 1`
指纹变化会让旧任务一次性失配。不升版本的理由:`checkpoint.Load` 对未知版本直接报错,会让已 `complete` 的目录也无法重入;而保持版本 1 时,`DiffFields` 会把 `source` 的旧竖线串与新 DSN 并列展示,用户能直观看懂差异,必要时加 `--force-resume` 即可。
### 4. 密码继续排除在指纹之外
`Passwd` 清空后再序列化。口令轮换不应使续跑失效,这是现有契约。
## Risks / Trade-offs
- `FormatDSN` 会连带覆盖 `tls`、`timeout` 等不影响产物字节的参数,这类修改也会触发续跑失配 → 方向是"宁可多报";确实需要时用 `--force-resume`。若未来噪声过大,再改为语义白名单。
- 旧 `state.json` 需要一次性 `--force-resume` → 在变更说明中标注为 BREAKING,且错误信息本身会展示新旧写法。
- `Params` 中若有自定义敏感参数会被写入 `state.json` → 与现状相同(原实现同样写入 `Params`),本次不扩大范围。
- 哈希输入与展示快照仍然耦合,未来再改 state 展示格式仍会触发失配 → 接受为已知债务,不在本次处理。
## Migration Plan
1. 修改 `dsnFingerprint` 并补充单元测试。
2. 验证新 `state.json` 中 `config.source` 为标准 DSN 且不含密码。
3. 对存量任务:首轮续跑加 `--force-resume`;已完成任务不受影响。
4. 回滚:还原 `dsnFingerprint` 即可;已写入的新格式 `config` 只是普通字符串,仍可读取,但指纹会再次失配,需要 `--force-resume`。