第 8 章 常见开发问题、线上踩坑总结、二次开发实战指南

1 学习目标

学完本章你应该能够：

1. 独立诊断并修复 6 个"硬伤级"问题——对每个坑都能说清症状、根因、修复方案，以及为什么会有这个坑；
2. 运用本地调试三板斧（绕过鉴权、打开 SQL 日志、用 dict 模块当探活接口）快速定位"服务挂没挂、SQL 发了什么"；
3. 跑通 secret 模块的完整闭环——录入凭证 → 脱敏查询 → 查详情 → 删除，并验证库里是 @ciphered@ 密文；
4. 实现 resource.Delete 的级联删除，并解释"先子后主"与事务边界为什么这么设计；
5. 照着"最近的亲戚"样板，给 redis 空地皮模块规划出最小落地方案——把前七章学的模块规范、DAO 范式、对账思想串起来用一遍。

前置知识：

• 第 7 章 7.2.8 的短板清单（本章的坑就是从那里来的）；
• 第 4 章资源模型与 resource_meta 四件套、第 6 章同步对账思想；
• GORM 基础：TableName()、事务（Begin/Commit/Rollback）、JOIN 别名、批量删除的标准姿势。

本章你会动手做的事：

1. 修复 secrets 表名与 encrypt_key 配置，跑通 secret 模块的录入→脱敏→删除闭环；
2. 给 Put 补上标签持久化（方案 B"先删后插"），并给 Delete 补级联删除；
3. 给空地皮模块 redis 写一份六步落地方案（DDL → 模型 → provider → impl → task → 路由）。

2 知识点通俗系统化讲解

2.1 踩坑清单总览

下表全部来自底稿 7.x 节与源码核验，都是"直接运行就会撞上"的坑：

另有三个"软伤"：同步任务 30 分钟硬超时且丢弃 cancel（apps/task/impl/task.go:58）、CreatTask 先 go 后 insert 的小竞态（同文件 61-69 行）、recover() 只保状态不重试（apps/task/impl/host.go:30-37）。

2.2 逐个修复（坑 1~3：三个"改名"级修复）

坑 1：配置字段名。 修复方案二选一：

• 改配置文件（推荐）：etc/config.toml 里把 [app] 段的 key = ... 改成 encrypt_key = "<你的强随机密钥>"；
• 改代码（不推荐）：把 conf/config.go:61 的 tag 从 toml:"encrypt_key" 改成 toml:"key"——不推荐是因为 env tag APP_ENCRYPT_KEY 也要跟着动，牵一发动全身。

坑 2：resource 幻影表。 host 模块的查询 SQL（apps/host/impl/sql.go:20-27）引用了不存在的表。修复——queryHostSQL 与 countHostSQL 两处都要改：

-- 修复前：FROM resource AS r ...（表不存在！）
-- 修复后：
SELECT r.*, h.*
FROM resource_meta AS r
	LEFT JOIN resource_host h ON r.id = h.resource_id
	LEFT JOIN resource_tag t ON r.id = t.resource_id

apps/rds/impl/sql.go 的 queryRdsSQL 有同样的 FROM resource as r 问题，一并修复。改完后 host 模块的 QueryHost/DescribeHost 才能真正跑通。

坑 3：secrets 表名。 修复方向跟坑 1、坑 2 相反——这次该改的是你的 DDL，不是代码：

-- 你自备的建表 SQL 里，表名必须是复数（与 TableName() 对齐）
CREATE TABLE secrets ( ... );   -- ✅ 正确
-- CREATE TABLE secret (...);  -- ❌ 凭直觉写单数，GORM 报 Table 'cmdb.secrets' doesn't exist

为什么会有这个坑值得深想：仓库没有附带 DDL 文件，而 Go 生态表名惯例并不统一——GORM 默认把 Secret 映射成复数 secrets，本项目的 TableName()（apps/secret/secret.go:5-7）也是复数。教训：仓库没有 DDL 时，TableName() 和 impl/sql.go 里的表名就是唯一事实来源，建表前先 grep 一遍再动手。

2.3 逐个修复（坑 4：补上标签持久化）

Put 里 temp.Tags 已经构建好了（apps/resource/impl/model.go:44-51），只差落库。两种修复：

方案 A（最小改动）——在 Put 保存 status 之后追加：

// 利用表的 UNIQUE(t_key, t_value, resource_id) 约束，逐条 upsert
for i := range temp.Tags {
	if err := tx.Save(temp.Tags[i]).Error; err != nil {
		return nil, err
	}
}

方案 B（对账友好，推荐）——“先删后插”，让标签集合与云端完全对齐：

// 1. 先删除该资源的全部旧标签（云端删掉的标签不会残留）
if err := tx.Where("resource_id = ?", res.Meta.Id).
	Delete(ResourceTag{}).Error; err != nil {
	return nil, err
}
// 2. 再批量插入新标签（GORM 批量插入，CreateBatchSize: 200 生效）
if len(temp.Tags) > 0 {
	if err := tx.Create(&temp.Tags).Error; err != nil {
		return nil, err
	}
}

方案 B 把第 6 章的"对账"思想从主机字段延伸到了标签：云端是事实来源，本地向云端对齐，而不是叠加。

2.4 逐个修复（坑 5：BuildQuery 别名统一）

统一规则：主表别名 m，四张子表别名 spec/cost/status/tag（与 WHERE 里已用的名字对齐）：

// 修复 apps/resource/impl/dao.go:13-17
query := s.db.WithContext(ctx).
	Table("resource_meta m").
	Joins("LEFT JOIN resource_spec spec ON spec.resource_id=m.id").   // spsc → spec
	Joins("LEFT JOIN resource_cost cost ON cost.resource_id=m.id").
	Joins("LEFT JOIN resource_status status ON status.resource_id=m.id")

第二处：dao.go:68 的 Keywords 条件用了 r.name/r.id/r.private_ip/r.public_ip，而主表别名是 m、IP 字段在 status 表上。修复：

if req.Keywords != "" {
	query = query.Where(
		"spec.name LIKE ? OR m.id = ? OR status.private_ip LIKE ? OR status.public_ip LIKE ?",
		"%"+req.Keywords+"%",
		req.Keywords,
		req.Keywords+"%",
		req.Keywords+"%",
	)
}

第三处容易漏：标签过滤里 value 条件用了 t.t_value（dao.go:58），但 tag 表的 JOIN 别名是 tag（dao.go:44），同样要统一成 tag.t_value。

坑 6（Delete 不级联） 留作课后实战——修复思路与方案 B 的"先删后插"同构：在同一事务里按 resource_id 依次 DELETE 五张子表（spec/cost/status/tag/类型明细），最后删 meta。

2.5 本地调试三板斧

1. 绕过鉴权（仅限本地学习）：临时注释 protocol/http.go:42 的 r.Filter(middleware.RestfulServerInterceptor()) 与 protocol/grpc.go:27 的 middleware.GrpcAuthUnaryServerInterceptor(...)；
2. 打开 SQL 日志：GORM 侧在 conf/config.go 的 gorm.Config 之外接 Logger，或最粗暴地在 zap 配置里把 level 设为 debug——原生 SQL 模块本来就打了 s.log.Debugf("sql: %s", querySQL)，debug 级别直接可见；
3. 探活：curl http://127.0.0.1:8060/cmdb/api/v1/dict/vendors，dict 是纯静态模块，不受数据库和同步链路影响，最适合判断"服务本体活没活"。

2.6 二次开发实战一：修复并跑通 secret 模块完整闭环

目标：录入凭证 → 查询列表（脱敏）→ 查详情 → 删除。步骤：

1. 避开坑 3：你自备的 DDL 里表名用复数 secrets（与 TableName() 返回值对齐）；
2. 按坑 1 修好 encrypt_key；
3. 启动后依次调用：

# 录入（api_secret 会被 CBC 加密后落库）
curl -X POST http://127.0.0.1:8060/cmdb/api/v1/secrets/ \
  -H 'Content-Type: application/json' \
  -d '{"vendor":"aliyun","api_key":"LTAI5tXXXXXX","api_secret":"my-secret",
       "regions":["cn-hangzhou"],"description":"测试凭证"}'

# 列表（返回的 api_secret 应为 ******）
curl http://127.0.0.1:8060/cmdb/api/v1/secrets/

# 详情 / 删除
curl http://127.0.0.1:8060/cmdb/api/v1/secrets/<id>
curl -X DELETE http://127.0.0.1:8060/cmdb/api/v1/secrets/<id>

4. 验证加密生效：直接查库 SELECT api_secret FROM secrets; 应看到 @ciphered@ 前缀的密文。

2.7 二次开发实战二：实现 resource.Delete 的级联删除

在第 8.2.3 方案 B 的基础上，给 Delete（apps/resource/impl/resource.go:56-82）补级联：

// 事务内追加（示意）：先删子表，再删主表
for _, table := range []string{
	"resource_spec", "resource_cost", "resource_status", "resource_tag",
} {
	if err := tx.Where("resource_id IN (?)", req.ResourceIds).
		Table(table).Delete(nil).Error; err != nil {
		return nil, err
	}
}
// 最后删主表（原逻辑）
err = tx.Where("id IN (?)", req.ResourceIds).Delete(ResourceMeta{}).Error

要点：删除顺序是先子后主（虽然本项目没建物理外键，顺序其实不强制，但保持这个习惯能兼容将来加外键约束的场景）；全部在原事务里做，要么全删要么全回滚。

2.8 二次开发实战三：给空地皮模块（redis）规划最小闭环

以 apps/redis（当前为 proto 占位模块）为例，按第 3 章的模块规范，落地"同步 + 查询"最小闭环需要六步：

① DDL：你自备的建表 SQL 增加 resource_redis 明细表（仓库未附带 DDL 文件）
   （字段：resource_id 主键 + 引擎版本/端口/规格/分片数等，参考 resource_rds 的建表风格）
② 领域模型：apps/redis/app.go 写 NewDefaultRedis()，复用
   resource.NewDefaultResource(resource.TYPE_REDIS)（照抄 host 的样板）
③ provider 接口：provider/redis.go 已有 RedisOperator 接口定义，
   在各厂商实现 PageQueryRedis（照抄 ecs 的 pager + mapping 归一化样板）
④ impl 层：impl.go（四方法标配）+ redis.go（SyncRedis 对账，照抄 host.SyncHost）
            + dao.go + sql.go（注意：FROM resource_meta，别再踩幻影表的坑！）
⑤ task 挂载：apps/task/impl/task.go 的 switch 增加
   case resource.TYPE_REDIS: go s.syncRedis(...)（照抄 syncHost 的厂商分发）
⑥ 路由：apps/redis/api/http.go 注册 GET / 查询路由，
   并在 apps/api.go 补匿名导入

每一步都有现成样板可抄——这正是一个结构清晰的开源项目送给二开者最好的礼物：你永远不需要从零发明，只需要找到那个"最近的亲戚"照着改。

2.9 更多二开方向（按投入产出排序）

1. 同步任务健壮性：30 分钟超时改为可配置 + 保留 cancel 支持外部取消；失败明细支持自动重试（限定次数）；
2. 增量同步：利用 resource_meta 的 hash 列，Put 前先比对 hash，未变化直接跳过写库（大资源量场景下写库次数可下降一个数量级）；
3. 批量对账：把"逐台 DescribeHost + save/update"改成"批量查存在集合 + 分桶批量 UPDATE/INSERT"（第 6 章思考题 3 的答案落地）；
4. 告警接缝：任务完成后若 total_failed > 0，向告警系统（如 Prometheus Alertmanager 的 webhook）发事件；
5. 补齐检索体验：修复别名 bug 后，给 host 模块补上"按标签过滤"（resource 模块已有 TagSelector 现成实现，跨模块移植即可）。

3 核心代码片段逐行解析

3.1 片段：修复后的完整 Put（含标签持久化，方案 B 合并版）

// apps/resource/impl/resource.go —— 修复后（关键新增段有 ★ 标记）
func (s *service) Put(ctx context.Context, res *resource.Resource) (
	*resource.Resource, error) {
	if err := res.Validate(); err != nil {
		return nil, err
	}

	var err error
	tx := s.db.WithContext(ctx).Begin()
	defer func() {
		if err == nil {
			tx.Commit()
		} else {
			tx.Rollback()
		}
	}()

	temp := NewResource(res)

	if err := tx.Save(temp.ResourceMeta).Error; err != nil {
		return nil, err
	}
	if err := tx.Save(temp.ResourceSpec).Error; err != nil {
		return nil, err
	}
	if res.Cost != nil {
		if err := tx.Save(temp.ResourceCost).Error; err != nil {
			return nil, err
		}
	}
	if err := tx.Save(temp.ResourceStatus).Error; err != nil {
		return nil, err
	}

	// ★ 标签对账：先删旧
	if err = tx.Where("resource_id = ?", res.Meta.Id).
		Delete(ResourceTag{}).Error; err != nil {
		return nil, err
	}
	// ★ 标签对账：再插新（空标签则只删不插，等于清空标签）
	if len(temp.Tags) > 0 {
		if err = tx.Create(&temp.Tags).Error; err != nil {
			return nil, err
		}
	}

	return res, nil
}

注意一个 GORM 细节：tx.Where(...).Delete(ResourceTag{}) 传的是空结构体（告诉 GORM 操作哪张表）+ Where 条件（删哪些行）——这是 GORM 按条件批量删除的标准姿势，等价于 DELETE FROM resource_tag WHERE resource_id = ?。

4 业务逻辑流程图与核心要点总结

4.1 踩坑-修复全景图

启动阶段                          运行阶段
─────────                        ─────────
坑1 encrypt_key 没读到           坑4 标签不落库 → Put 补"先删后插"
   ↓ 密钥回退默认值(危险)            坑5 检索报 Unknown column → 别名统一
   ↓ 同步解密必失败                 坑2 host/rds 查询报表不存在 → resource_meta
坑3 secrets 表不存在              坑6 删除留孤儿 → 事务内先子后主级联
   ↓ secret 模块全挂               软伤: 30min硬超时/不可取消/不重试
                                  → 二开方向1~5

4.2 核心要点总结

1. 六个硬伤，四个是"命名/别名不一致"——半重构项目最大的雷区就是新旧两套命名并存，接手任何项目先全局 grep 新旧表名/别名是否一致；
2. 修复顺序建议：坑1（配置）→ 坑3（secret 表名）→ 坑2（幻影表）→ 坑5（别名）→ 坑4（标签）→ 坑6（级联）——前四个不修，功能根本跑不起来；
3. 二开心法：找到"最近的亲戚"照着改（host 是一切资源模块的亲戚，resource 是一切 DAO 的亲戚）；
4. 所有写操作放事务里，删除先子后主，标签对账"先删后插"。

5 自测题（对话式）

下面把本章的三道课后思考题搬进"面试现场"——先遮住候选人的回答自己想一遍，再对照参考答案。

6 本章小结