Skip to content

refactor(db): unify console API key dual-write into a single atomic ownership boundary #201

Description

@arthur-zhang

背景

当前 CreateConsoleAPIKey / UpdateConsoleAPIKeyStatus 通过调用层协调 console_api_keysapi_keys 两套 mapper。虽然事务存在,但同一业务对象的双写一致性仍然分散在调用编排中。

相关代码:

  • internal/db/console_api_keys.go
  • internal/db/console_api_keys_mapper.xml
  • internal/db/admin_api_keys_mapper.xml
  • internal/admin/service.go

问题

1. Console API key 的双写缺少单一 canonical owner

当前实现需要在调用层显式协调:

  • consoleMapper.Insert(...) + adminMapper.Insert(...)
  • consoleMapper.UpdateStatus(...) + adminMapper.UpdateStatusByUUID(...)

这会带来几个问题:

  • 同一业务对象的一致性规则分散在两个 mapper 和调用顺序之间。
  • 调用方必须理解写入顺序、失败语义和 rowsAffected == 1 之类的校验细节。
  • 后续如果再扩展 Console API key 生命周期,容易继续在调用层长出分支和特殊处理。

2. UpdateAPIKey 退化成 update + get

UpdateAdminAPIKey 现在只返回 error,导致 service 层需要:

  1. UpdateAdminAPIKey(...)
  2. 再调 GetAdminAPIKey(...)

这让复杂度从 DB 层外溢到 service 层,也增加了一次额外查询。

3. creator UUID 的边界语义收紧,但抽象不够明确

findConsoleAPIKeyCreatorUUID 现在本质上是“校验内部 UUID 是否存在”,不再像旧逻辑那样解析更宽泛的用户标识。即使当前调用路径没坏,这个语义变化也应该在命名或边界约束上表达清楚,避免后续误用。

期望改进

  • 为 Console API key 提供一个单一原子写入口,把双表一致性封装进 canonical DB 边界,而不是由调用层编排两个 mapper。
  • 收敛 DB 抽象,让 service 层不需要理解双写顺序和一致性校验细节。
  • 评估是否恢复“更新并返回记录”的单入口能力,避免 update + get
  • 如果 creator 只允许内部 UUID,调整 helper / mapper 命名,让边界更显式;否则补回明确的兼容解析策略。

验收标准

  • CreateConsoleAPIKey / UpdateConsoleAPIKeyStatus 不再由调用层显式协调两个 mapper 完成同一业务对象的双写。
  • Console API key 的双表写入语义通过一个清晰、原子的 DB 入口表达。
  • UpdateAPIKey 不再需要 service 层手动执行 update + get
  • 相关单测和 PostgreSQL 集成测试继续覆盖生成 SQL、事务行为和双表一致性。

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions