# 4.11 扩展性设计

:::tip 概述
扩展性来自两方面：一是**标准变更的操作清单**（按变更类型给出 checklist，不漏步骤、不变异架构）；二是**逃生舱挂点**（基座装不下的需求有明确的合法出口）。本节按变更类型组织。
:::

## 变更类型 Checklist

### 1. 给现有模块新增一个接口

```text
□ api/v1/{模块}.go：新增 {Mod}{Action}Req（内嵌 gmeta.Meta，path 带 /api 前缀、
  permission、log、logType）+ {Mod}{Action}Res
□ controller：同名方法，签名 func (c *CXxx) Action(ctx, req) (res, err)
□ service/{模块}.go：接口追加方法声明（手维护）
□ logic：实现方法（基座可表达走 spec 钩子，复杂走手写）
□ 权限节点同步：若 permission 为新码，需在菜单管理为角色勾选
  （或插入 goframe_menu type=1 节点）
□ go build ./... && gofmt；重启；/api.json 核对新条目
```

### 2. 给现有模块加字段

```text
□ MySQL ALTER（列注释按枚举规范写"字段：1-x 2-y"；需要唯一性则补 uk_*）
□ gf gen dao -c hack/config.yaml（刷新 entity/do/dao internal；service 不动）
□ api/v1：Req/Res/Item 结构体补字段（json 驼峰 + dc 注释）
□ logic：ToData 补键；枚举补 SerializeMaps（字典编码 {模块}_{字段}）；
  文件字段补 FileFields+FileSaveDir；富文本补 ContentFields
□ 前端：columns.ts / querySchemas.ts / edit.vue 同步
□ document/ 五方言脚本同步；必要时附录表清单更新
□ go build → 重启 → page/detail 黄金样本更新
```

### 3. 新增模块

```text
□ 设计表（统一审计列 + del_flag + uk_* + 注释枚举）→ DDL 落库
□ 租户级？→ hooks.tenantTables 登记
□ go run ./cmd/generator -tables "goframe_x|中文名"（或手动四件套）
□ logic 调整：spec 声明（筛选/树形/字典/文件/唯一 Group）、扩展接口
□ service 接口核对；router.go 注册行确认
□ go build ./... → 重启 → 角色勾选新权限节点
```

### 4. 新增中间件

```text
□ internal/middleware/{name}.go：func(r *ghttp.Request)，职责单一；
  读配置用 cfgBool/cfgInt；客户端 IP 用 realClientIP；响应用 utility/response
□ 不得 import 业务包——需要业务数据时在 wire.go 增加 Loader 函数变量，
  由 logic init 注册（参照 IdentityLoader 模式）
□ router.Register 的 s.Use 链按序插入（顺序即语义，评审明确插入点）
□ public 路径行为：确认对 IsPublicPath 的放行策略
```

### 5. 新增定时任务

```text
□ internal/task/{task_name}.go + init RegisterJobHandler("TaskName", h)
□ handler 签名 (ctx, params) (string, error)；长任务分批+上限；禁 HTTP 于事务内
□ 任务表配置：url="TaskName"、params JSON、cron（6 段或 # 5 段）、
  execute_policy/is_sync；发布（status=1）
□ 验证：daemonStatus 挂载 + runOnce + job/log 成功记录
□ go build 重启（init 注册发生在进程加载期）
```

### 6. 自定义 / 扩展 dao

```text
□ dao/{m}.go 尾部"Add your custom methods"区追加方法（统计/联查等）
□ 修改模板本身：改 hack/tpl/dao_index.tpl 后 gf gen dao 重新生成
  （overwriteDao:false 保留手工扩展；新旧模板产物差异需人工合并）
□ 红线：自定义方法也必须以 Ctx(ctx) 为查询入口；禁止在 dao 内做业务判断
```

### 7. 配置变更

```text
□ manifest/config/config.yaml 修改
□ 多环境差异用 GF_ 环境变量覆盖，不改文件
□ 新增配置键：注释说明 + 代码 cfgBool/cfgInt 带默认值读取（缺失不 panic）
□ 影响限流/日志/上传/调度的键变更后跑对应回归
```

## 逃生舱与扩展挂点

| 挂点 | 场景 | 说明 |
|------|------|------|
| BodyUnmarshaler | 请求体形态不规则（平铺 map 等） | Req 实现 `UnmarshalBody(r)` 跳过默认 Parse（自行做 gvalid） |
| ModuleSpec.Filter | 复杂查询条件 | 不与 Like/Eq 重复声明 |
| ModuleSpec.DataScope | 数据权限挂点 | 共享工厂 `ApplyDataScope(col)`，声明即生效 |
| ModuleSpec 钩子装不下 | 基座禁止按模块分支 | 整个方法手写（合法逃生舱，如 job.Detail 因嵌入结构手写） |
| logic 包级共享函数 | 跨模块复用 | 放具体模块文件顶部（同包可见）；横切能力进 base.go（15 导出上限） |
| RegisterJobHandler | 本地任务处理器 | 全局注册表（重名 panic） |
| middleware wire | 业务与中间件解耦 | 三 Loader/Sink 函数变量 |

## 未启用项与前端遗留

| 项 | 现状 | 启用/处理要点 |
|----|------|-------------|
| 用户注册 | publicPaths 含 /api/register（路由未注册） | 启用时补建表逻辑 + 开放策略 + 租户归属规则 |
| 数据范围自定义档 | 现四档纯列值（role.data_scope） | 第 5 档需部门关联表 + 角色表单部门树多选 |
| 导出增强 | 当前导出返回临时文件 URL | 可加流式下载/异步导出 |
| SendSms 任务 | task/send_sms.go 仅记日志 | 接短信通道时替换实现 |
| 站内信/数据源/短信/OSS/WebSocket | 前端遗留死代码（后端桩已删除） | 不再调用即无影响 |

## 封板后的变更纪律

```text
1) 一切接口行为以 API 接口清单 + /api.json 为准，改动即更新文档
2) 表结构改动三同步：document/mysql/ 定稿 → 其余四方言脚本 → 迁移（跨环境时）
3) 破坏性变更（改名/删字段/改枚举值）必须走版本化说明 + 前端同步 +
   黄金样本更新，禁止静默变更
4) 架构红线复查：绕过 dao / 手写租户条件 / 反向依赖 task / 超 15 导出的 base /
   未登记 tenantTables——任何一项都应打回
```