Files
ssw-ontology/server/handlers_backup.go
T
admin e7b39805fb feat(backup): 按 schema 镜像 + 请求级 search_path 切库 (issue #4 #5 后续)
「让客户端敢操作」的关键能力:写前/写后打一份快照 → 任意 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]。
2026-09-07 11:35:47 +08:00

120 lines
3.3 KiB
Go
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.
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})
}