hotime/docs/CodeGen_使用说明.md

HoTime 代码生成器使用说明

code 包提供了 HoTime 框架的自动代码生成功能，能够根据数据库表结构自动生成 CRUD 接口代码和配置文件。

目录

• 功能概述
• 配置说明
• 使用方法
• 生成规则
• 自定义规则
• 生成的代码结构

---

功能概述

代码生成器可以：

1. 自动读取数据库表结构 - 支持 MySQL、SQLite 和达梦 DM8
2. 生成 CRUD 接口 - 增删改查、搜索、分页
3. 生成配置文件 - 表字段配置、菜单配置、权限配置
4. 智能字段识别 - 根据字段名自动识别类型和权限
5. 支持表关联 - 自动识别外键关系

---

配置说明

在 config.json 中配置代码生成：

{
    "codeConfig": [
        {
            "table": "admin",
            "config": "config/admin.json",
            "configDB": "config/adminDB.json",
            "rule": "config/rule.json",
            "name": "",
            "mode": 0
        }
    ]
}

配置项说明

配置项	必须	说明
table	✅	用户表名，用于权限控制的基准表
config	✅	接口描述配置文件路径
configDB	❌	数据库结构配置输出路径，有则每次自动生成
rule	❌	字段规则配置文件，无则使用默认规则
name	❌	生成代码的包名和目录名，空则使用内嵌模式
mode	❌	0=内嵌代码模式，1=生成代码模式

运行模式

• mode=0（内嵌模式）：不生成独立代码文件，使用框架内置的通用控制器
• mode=1（生成模式）：为每张表生成独立的 Go 控制器文件

---

使用方法

1. 基础配置

{
    "mode": 2,
    "codeConfig": [
        {
            "table": "admin",
            "config": "config/admin.json",
            "rule": "config/rule.json",
            "mode": 0
        }
    ]
}

2. 启动应用

package main

import (
    . "code.hoteas.com/golang/hotime"
    . "code.hoteas.com/golang/hotime/common"
)

func main() {
    app := Init("config/config.json")
    
    // 代码生成器在 Init 时自动执行
    // 会读取数据库结构并生成配置
    
    app.Run(Router{
        // 路由配置
    })
}

3. 开发模式

在 config.json 中设置 "mode": 2（开发模式）时：

• 自动读取数据库表结构
• 自动生成/更新配置文件
• 自动生成代码（如果 codeConfig.mode=1）

---

生成规则

默认字段规则

代码生成器内置了一套默认的字段识别规则：

字段名	列表显示	新增	编辑	详情	类型
id	✅	❌	❌	✅	number
name	✅	✅	✅	✅	text
status	✅	✅	✅	✅	select
create_time	❌	❌	❌	✅	time
modify_time	✅	❌	❌	✅	time
password	❌	✅	✅	❌	password
image/img/avatar	❌	✅	✅	✅	image
file	❌	✅	✅	✅	file
content/info	❌	✅	✅	✅	textArea
parent_id	✅	✅	✅	✅	number
parent_ids/index	❌	❌	❌	❌	index
delete	❌	❌	❌	❌	-

数据类型映射

数据库字段类型自动映射：

数据库类型	生成类型
int, integer, float, double, decimal	number
char, varchar, text, blob	text
date, datetime, time, timestamp, year	time

字段备注解析

支持从数据库字段备注中提取信息：

-- 字段备注格式: 标签名(提示信息):选项1-名称1,选项2-名称2
-- 括号支持三种写法：()、（）、{}
-- 例如:
status TINYINT COMMENT '状态(用户账号状态):0-禁用,1-启用'
parent_id INT COMMENT '父级ID（顶级为NULL）'
phone VARCHAR(20) COMMENT '手机号(请输入11位手机号)'

生成的配置（以第一行为例）：

{
    "name": "status",
    "label": "状态",
    "type": "select",
    "ps": "用户账号状态",
    "options": [
        {"name": "禁用", "value": "0"},
        {"name": "启用", "value": "1"}
    ]
}

ps 字段在前端的展示效果：

• 编辑/新增页面：输入框右侧灰色小字提示
• 表格/详情页面：鼠标悬停字段名时气泡提示

---

自定义规则

rule.json 配置

创建 config/rule.json 自定义字段规则：

[
    {
        "name": "id",
        "list": true,
        "add": false,
        "edit": false,
        "info": true,
        "must": false,
        "strict": true,
        "type": ""
    },
    {
        "name": "status",
        "list": true,
        "add": true,
        "edit": true,
        "info": true,
        "must": false,
        "strict": false,
        "type": "select"
    },
    {
        "name": "user.special_field",
        "list": true,
        "add": true,
        "edit": true,
        "info": true,
        "type": "text",
        "strict": true
    }
]

规则字段说明

字段	说明
name	字段名，支持 表名.字段名 格式精确匹配
list	是否在列表中显示
add	是否在新增表单中显示
edit	是否在编辑表单中显示
info	是否在详情中显示
must	是否必填
strict	是否严格匹配字段名（false 则模糊匹配）
type	字段类型（覆盖自动识别）

字段类型

类型	说明
text	普通文本输入
textArea	多行文本
number	数字输入
select	下拉选择
time	时间选择器
unixTime	Unix 时间戳
image	图片上传
file	文件上传
password	密码输入
money	金额（带格式化）
index	索引字段（不显示）
tree	树形选择
form	表单配置
auth	权限配置

---

生成的代码结构

内嵌模式 (mode=0)

不生成代码文件，使用框架内置控制器，只生成配置文件：

config/
├── admin.json      # 接口配置
├── adminDB.json    # 数据库结构配置（可选）
└── rule.json       # 字段规则

生成模式 (mode=1)

生成独立的控制器代码：

admin/              # 生成的包目录
├── init.go         # 包初始化和路由注册
├── user.go         # user 表控制器
├── role.go         # role 表控制器
└── ...             # 其他表控制器

生成的控制器结构

package admin

var userCtr = Ctr{
    "info": func(that *Context) {
        // 查询单条记录
    },
    "add": func(that *Context) {
        // 新增记录
    },
    "update": func(that *Context) {
        // 更新记录
    },
    "remove": func(that *Context) {
        // 删除记录
    },
    "search": func(that *Context) {
        // 搜索列表（分页）
    },
}

---

配置文件结构

admin.json 示例

{
    "name": "admin",
    "label": "管理平台",
    "menus": [
        {
            "label": "系统管理",
            "name": "sys",
            "icon": "Setting",
            "menus": [
                {
                    "label": "用户管理",
                    "table": "user",
                    "auth": ["show", "add", "delete", "edit", "info", "download"]
                },
                {
                    "label": "角色管理",
                    "table": "role",
                    "auth": ["show", "add", "delete", "edit", "info"]
                }
            ]
        }
    ],
    "tables": {
        "user": {
            "label": "用户",
            "table": "user",
            "auth": ["show", "add", "delete", "edit", "info", "download"],
            "columns": [
                {"name": "id", "type": "number", "label": "ID"},
                {"name": "name", "type": "text", "label": "用户名"},
                {"name": "status", "type": "select", "label": "状态", 
                 "options": [{"name": "禁用", "value": "0"}, {"name": "启用", "value": "1"}]}
            ],
            "search": [
                {"type": "search", "name": "keyword", "label": "请输入关键词"},
                {"type": "search", "name": "daterange", "label": "时间段"}
            ]
        }
    }
}

---

外键关联

自动识别

代码生成器会自动识别 _id 结尾的字段作为外键：

-- user 表
CREATE TABLE user (
    id INT PRIMARY KEY,
    name VARCHAR(50),
    role_id INT,        -- 自动关联 role 表
    org_id INT          -- 自动关联 org 表
);

生成的配置会包含 link 和 value 字段：

{
    "name": "role_id",
    "type": "number",
    "label": "角色",
    "link": "role",
    "value": "name"
}

树形结构

parent_id 字段会被识别为树形结构的父级关联：

{
    "name": "parent_id",
    "type": "number",
    "label": "上级",
    "link": "org",
    "value": "name"
}

---

权限控制

数据权限

配置 flow 实现数据权限控制：

{
    "flow": {
        "order": {
            "table": "order",
            "stop": false,
            "sql": {
                "user_id": "id"
            }
        }
    }
}

• stop: 是否禁止修改该表
• sql: 数据过滤条件，user_id = 当前用户.id

操作权限

每张表可配置的权限：

权限	说明
show	查看列表
add	新增
edit	编辑
delete	删除
info	查看详情
download	下载导出

---

最佳实践

1. 开发流程

1. 设置 config.json 中 mode: 2（开发模式）
2. 设计数据库表结构，添加字段备注
3. 启动应用，自动生成配置
4. 检查生成的配置文件，按需调整
5. 生产环境改为 mode: 0

2. 字段命名规范

-- 推荐的命名方式
id              -- 主键
name            -- 名称
status          -- 状态（自动识别为 select）
create_time     -- 创建时间
modify_time     -- 修改时间
xxx_id          -- 外键关联
parent_id       -- 树形结构父级
avatar          -- 头像（自动识别为 image）
content         -- 内容（自动识别为 textArea）

3. 自定义扩展

如果默认规则不满足需求，可以：

1. 修改 rule.json 添加自定义规则
2. 使用 mode=1 生成代码后手动修改
3. 在生成的配置文件中直接调整字段属性

4. 达梦 DM8 使用注意

代码生成器已原生支持达梦 DM8，会自动读取 DM 数据库的表结构和字段备注。使用时注意：

• 表注释（COMMENT）在 DM 中通过 COMMENT ON TABLE 语句单独设置，建表后需额外执行
• 字段备注同样通过 COMMENT ON COLUMN 设置
• 由于 DM 的 USER_TAB_COLUMNS 视图字段名称与 MySQL information_schema 不同，代码生成器已做兼容处理

-- DM8 设置表备注（替代 MySQL 的 COMMENT='...' 语法）
COMMENT ON TABLE "user" IS '用户管理';

-- DM8 设置字段备注
COMMENT ON COLUMN "user"."state" IS '状态:0-正常,1-异常,2-隐藏';
COMMENT ON COLUMN "user"."name"  IS '用户名';

---

相关文档

• 快速上手指南
• HoTimeDB 使用说明
• Common 工具类使用说明