docs(guides): 完善框架文档并新增代码生成器说明
- 添加代码生成器完整使用说明文档，包含配置规则和自定义规则 - 新增 Common 工具类使用说明，介绍 Map/Slice/Obj 类型及转换函数 - 更新 QUICKSTART 文档中的配置项说明和数据库配置示例 - 完善请求参数获取方法，添加新版链式调用推荐用法 - 更新响应数据处理说明，包含错误码含义和自定义响应方法 - 优化中间件和 Session 操作的代码示例 - 修正路由路径参数获取的安全检查逻辑 - 更新 README 添加新文档链接索引
This commit is contained in:
@@ -0,0 +1,468 @@
|
||||
# HoTime 代码生成器使用说明
|
||||
|
||||
`code` 包提供了 HoTime 框架的自动代码生成功能，能够根据数据库表结构自动生成 CRUD 接口代码和配置文件。
|
||||
|
||||
## 目录
|
||||
|
||||
- [功能概述](#功能概述)
|
||||
- [配置说明](#配置说明)
|
||||
- [使用方法](#使用方法)
|
||||
- [生成规则](#生成规则)
|
||||
- [自定义规则](#自定义规则)
|
||||
- [生成的代码结构](#生成的代码结构)
|
||||
|
||||
---
|
||||
|
||||
## 功能概述
|
||||
|
||||
代码生成器可以：
|
||||
|
||||
1. **自动读取数据库表结构** - 支持 MySQL 和 SQLite
|
||||
2. **生成 CRUD 接口** - 增删改查、搜索、分页
|
||||
3. **生成配置文件** - 表字段配置、菜单配置、权限配置
|
||||
4. **智能字段识别** - 根据字段名自动识别类型和权限
|
||||
5. **支持表关联** - 自动识别外键关系
|
||||
|
||||
---
|
||||
|
||||
## 配置说明
|
||||
|
||||
在 `config.json` 中配置代码生成：
|
||||
|
||||
```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. 基础配置
|
||||
|
||||
```json
|
||||
{
|
||||
"mode": 2,
|
||||
"codeConfig": [
|
||||
{
|
||||
"table": "admin",
|
||||
"config": "config/admin.json",
|
||||
"rule": "config/rule.json",
|
||||
"mode": 0
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 2. 启动应用
|
||||
|
||||
```go
|
||||
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 |
|
||||
|
||||
### 字段备注解析
|
||||
|
||||
支持从数据库字段备注中提取信息：
|
||||
|
||||
```sql
|
||||
-- 字段备注格式: 标签名:选项1-名称1,选项2-名称2 {提示信息}
|
||||
-- 例如:
|
||||
status TINYINT COMMENT '状态:0-禁用,1-启用 {用户账号状态}'
|
||||
```
|
||||
|
||||
生成的配置：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "status",
|
||||
"label": "状态",
|
||||
"type": "select",
|
||||
"ps": "用户账号状态",
|
||||
"options": [
|
||||
{"name": "禁用", "value": "0"},
|
||||
{"name": "启用", "value": "1"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 自定义规则
|
||||
|
||||
### rule.json 配置
|
||||
|
||||
创建 `config/rule.json` 自定义字段规则：
|
||||
|
||||
```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 表控制器
|
||||
└── ... # 其他表控制器
|
||||
```
|
||||
|
||||
### 生成的控制器结构
|
||||
|
||||
```go
|
||||
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 示例
|
||||
|
||||
```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` 结尾的字段作为外键：
|
||||
|
||||
```sql
|
||||
-- user 表
|
||||
CREATE TABLE user (
|
||||
id INT PRIMARY KEY,
|
||||
name VARCHAR(50),
|
||||
role_id INT, -- 自动关联 role 表
|
||||
org_id INT -- 自动关联 org 表
|
||||
);
|
||||
```
|
||||
|
||||
生成的配置会包含 `link` 和 `value` 字段：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "role_id",
|
||||
"type": "number",
|
||||
"label": "角色",
|
||||
"link": "role",
|
||||
"value": "name"
|
||||
}
|
||||
```
|
||||
|
||||
### 树形结构
|
||||
|
||||
`parent_id` 字段会被识别为树形结构的父级关联：
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "parent_id",
|
||||
"type": "number",
|
||||
"label": "上级",
|
||||
"link": "org",
|
||||
"value": "name"
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 权限控制
|
||||
|
||||
### 数据权限
|
||||
|
||||
配置 `flow` 实现数据权限控制：
|
||||
|
||||
```json
|
||||
{
|
||||
"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. 字段命名规范
|
||||
|
||||
```sql
|
||||
-- 推荐的命名方式
|
||||
id -- 主键
|
||||
name -- 名称
|
||||
status -- 状态（自动识别为 select）
|
||||
create_time -- 创建时间
|
||||
modify_time -- 修改时间
|
||||
xxx_id -- 外键关联
|
||||
parent_id -- 树形结构父级
|
||||
avatar -- 头像（自动识别为 image）
|
||||
content -- 内容（自动识别为 textArea）
|
||||
```
|
||||
|
||||
### 3. 自定义扩展
|
||||
|
||||
如果默认规则不满足需求，可以：
|
||||
|
||||
1. 修改 `rule.json` 添加自定义规则
|
||||
2. 使用 `mode=1` 生成代码后手动修改
|
||||
3. 在生成的配置文件中直接调整字段属性
|
||||
|
||||
---
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [快速上手指南](QUICKSTART.md)
|
||||
- [HoTimeDB 使用说明](HoTimeDB_使用说明.md)
|
||||
- [Common 工具类使用说明](Common_工具类使用说明.md)
|
||||
Reference in New Issue
Block a user