「让客户端敢操作」的关键能力:写前/写后打一份快照 → 任意 GET 带 X-Snapshot-Id
头即可命中 backups_<id> schema 的同名表(业务 SQL 不带 schema 前缀照样切)。
设计要点:
- 备份 = 独立 schema backups_<id>(真表,不是单存 JSONB)—— 查询性能与活库一致
- snapshotRouter 中间件:BeginTx + SET LOCAL search_path → 把 a.pool 临时换
为事务视图 txPool → handler 结束 commit + 还原 a.pool。业务代码一行不改。
- a.pool 字段类型从 *pgxpool.Pool 升级为 dbRunner interface(中间件可换 txPool)。
- 11 个 helper 函数签名同步改为 dbExec(与现有 dbExec 共存,无破坏性)。
- 写方法(POST/PUT/PATCH/DELETE)带快照头 → 403 拒绝(mistake-safety)。
接口:
- POST /api/v1/backups 创建
- GET /api/v1/backups 列表
- GET /api/v1/backups/:id 元信息(含 schema_name)
- GET /api/v1/backups/:id/switch 切库提示
- DELETE /api/v1/backups/:id 级联删 schema
- 支持 X-Snapshot-Id (直接 run id) + X-Snapshot-Ts (秒级时间戳) 两种切换入口
MCP 工具 (5 个):backup_create / backup_list / backup_inspect / backup_switch / backup_delete
测试 (22 个全绿,~5.5s 集成):
- SnapshotRouter:改前建快照 → 改后读快照只见改前
- SnapshotSearchPathPersist:不污染下一个请求
- SnapshotByTimestamp:ts 头也能切库
- SnapshotDeleteCleansSchema:delete 真 DROP schema
- BackupLifecycle / BackupDiffAfterMutation:完整 create→list→inspect→switch→delete
文档:docs/BACKUP.md 写清用法、机制、客户端工作流;CHANGELOG.md [1.3.0]。
120 lines
3.3 KiB
Go
120 lines
3.3 KiB
Go
package main
|
||
|
||
import (
|
||
"strconv"
|
||
|
||
"github.com/gin-gonic/gin"
|
||
)
|
||
|
||
// ============================================================================
|
||
// 备份 HTTP 接口(v1.3.0,按 schema 镜像)
|
||
//
|
||
// 路由前缀:/api/v1/backups(挂在 mgmt 之下,需 manager 主体)
|
||
// ============================================================================
|
||
|
||
type createBackupInput struct {
|
||
Name string `json:"name"`
|
||
Notes string `json:"notes"`
|
||
}
|
||
|
||
// createBackupHandler POST /api/v1/backups
|
||
func (a *app) createBackupHandler(c *gin.Context) {
|
||
if !a.requireBackupManager(c) {
|
||
return
|
||
}
|
||
var body createBackupInput
|
||
_ = c.ShouldBindJSON(&body)
|
||
authz, _ := a.authzOf(c)
|
||
principal := authz.Principal
|
||
|
||
run, err := a.createBackup(c, principal, body.Name, body.Notes)
|
||
if err != nil {
|
||
c.JSON(500, gin.H{"error": err.Error()})
|
||
return
|
||
}
|
||
c.JSON(201, run)
|
||
}
|
||
|
||
// listBackupsHandler GET /api/v1/backups?limit=50&offset=0
|
||
func (a *app) listBackupsHandler(c *gin.Context) {
|
||
if !a.requireBackupManager(c) {
|
||
return
|
||
}
|
||
limit, _ := strconv.Atoi(c.Query("limit"))
|
||
offset, _ := strconv.Atoi(c.Query("offset"))
|
||
runs, err := a.listBackups(c, limit, offset)
|
||
if err != nil {
|
||
c.JSON(500, gin.H{"error": err.Error()})
|
||
return
|
||
}
|
||
total, _ := a.countBackups(c)
|
||
c.JSON(200, gin.H{
|
||
"items": runs, "count": len(runs), "total": total,
|
||
"limit": limit, "offset": offset,
|
||
})
|
||
}
|
||
|
||
// inspectBackupHandler GET /api/v1/backups/:id
|
||
func (a *app) inspectBackupHandler(c *gin.Context) {
|
||
if !a.requireBackupManager(c) {
|
||
return
|
||
}
|
||
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
|
||
if err != nil {
|
||
c.JSON(400, gin.H{"error": "id 必须是整数"})
|
||
return
|
||
}
|
||
run, err := a.loadBackupRun(c, id)
|
||
if err != nil {
|
||
c.JSON(404, gin.H{"error": "快照不存在: " + err.Error()})
|
||
return
|
||
}
|
||
c.JSON(200, run)
|
||
}
|
||
|
||
// switchBackupHandler GET /api/v1/backups/:id/switch
|
||
//
|
||
// 返回「切到这个快照需要的东西」:schema_name + 提示头名。MCP 客户端拿到后
|
||
// 在下次调用任接口时带 X-Snapshot-Id: <id>,snapshotRouter 自动把请求路由
|
||
// 到 backups_<id> schema 的同名表里,SQL 不需要任何前缀。
|
||
func (a *app) switchBackupHandler(c *gin.Context) {
|
||
if !a.requireBackupManager(c) {
|
||
return
|
||
}
|
||
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
|
||
if err != nil {
|
||
c.JSON(400, gin.H{"error": "id 必须是整数"})
|
||
return
|
||
}
|
||
run, err := a.loadBackupRun(c, id)
|
||
if err != nil {
|
||
c.JSON(404, gin.H{"error": "快照不存在: " + err.Error()})
|
||
return
|
||
}
|
||
c.JSON(200, gin.H{
|
||
"snapshot_id": run.ID,
|
||
"schema_name": run.SchemaName,
|
||
"switch_via": "X-Snapshot-Id",
|
||
"switch_via_2": "X-Snapshot-Ts",
|
||
"created_at": run.CreatedAt,
|
||
"hint": "下次任意 GET 请求带上 X-Snapshot-Id: " + strconv.FormatInt(run.ID, 10) +
|
||
"(或 X-Snapshot-Ts: <created_at unix>)即可命中此快照;写方法(POST/PUT/PATCH/DELETE)会被 403 拒绝",
|
||
})
|
||
}
|
||
|
||
// deleteBackupHandler DELETE /api/v1/backups/:id
|
||
func (a *app) deleteBackupHandler(c *gin.Context) {
|
||
if !a.requireBackupManager(c) {
|
||
return
|
||
}
|
||
id, err := strconv.ParseInt(c.Param("id"), 10, 64)
|
||
if err != nil {
|
||
c.JSON(400, gin.H{"error": "id 必须是整数"})
|
||
return
|
||
}
|
||
if err := a.deleteBackup(c, id); err != nil {
|
||
c.JSON(500, gin.H{"error": err.Error()})
|
||
return
|
||
}
|
||
c.JSON(200, gin.H{"ok": true, "id": id})
|
||
} |